jfl 0.9.1 → 0.9.3

package/packages/pi/extensions/subway-mesh.ts

@@ -0,0 +1,893 @@
+/**
+ * Subway Mesh Extension
+ *
+ * WebSocket client for the Subway P2P agent mesh. Provides real-time
+ * messaging, RPC calls, pub/sub broadcasting, and name resolution
+ * between Pi agent sessions connected to a Subway relay.
+ *
+ * Registers tools: subway_send, subway_call, subway_resolve,
+ * subway_rpc_respond, subway_inbox, subway_subscribe, subway_unsubscribe,
+ * subway_broadcast.
+ *
+ * Registers command: /subway (status, connect, disconnect, send, etc.)
+ *
+ * Provides TUI integration: status bar indicator, inbox widget,
+ * and agent context injection on each turn.
+ *
+ * @purpose Subway P2P mesh client — messaging, RPC, pub/sub tools + TUI
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from "fs"
+import { join } from "path"
+import { homedir } from "os"
+import type { PiContext, JflConfig, PiTheme } from "./types.js"
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface SubwayMessage {
+  ts: number
+  from: string
+  payload: string
+}
+
+export interface SubwayConfig {
+  name?: string
+  relay?: string
+  debug?: boolean
+}
+
+export interface CallResult {
+  success: boolean
+  payload: string
+  error: string
+}
+
+interface PendingRequest {
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+type MessageHandler = (type: string, msg: Record<string, unknown>) => void
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const RPC_TIMEOUT_MS = 30_000
+const RESOLVE_TIMEOUT_MS = 10_000
+const KEEPALIVE_INTERVAL_MS = 15_000
+const HEALTH_CHECK_INTERVAL_MS = 60_000
+const MAX_INBOX = 50
+const MAX_VISIBLE_WIDGET = 3
+
+const DEFAULT_RELAY = "wss://relay.subway.dev/ws"
+const DEFAULT_NAME = "claude.relay"
+const CONFIG_DIR = join(homedir(), ".subway")
+const CONFIG_PATH = join(CONFIG_DIR, "config.json")
+const DEBUG_LOG_PATH = join(CONFIG_DIR, "debug.log")
+
+// ─── Config helpers ──────────────────────────────────────────────────────────
+
+export function loadConfig(): SubwayConfig {
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"))
+    }
+  } catch {}
+  return {}
+}
+
+export function saveConfig(cfg: SubwayConfig): void {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true })
+  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n")
+}
+
+export function normalizeName(name: string): string {
+  return name.endsWith(".relay") ? name : `${name}.relay`
+}
+
+export function displayName(name: string): string {
+  return name.replace(/\.relay$/, "")
+}
+
+// ─── SubwayClient ────────────────────────────────────────────────────────────
+
+export class SubwayClient {
+  name: string
+  relayUrl: string
+  registered = false
+  inbox: SubwayMessage[] = []
+
+  private ws: import("ws").WebSocket | null = null
+  private WebSocketCtor: typeof import("ws").WebSocket | null = null
+  private debug: boolean
+  private intentionalDisconnect = false
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private keepaliveTimer: ReturnType<typeof setInterval> | null = null
+  private healthCheckTimer: ReturnType<typeof setInterval> | null = null
+  private registeredPeerId: string | null = null
+  private pending = new Map<string, PendingRequest>()
+  private _subscriptions = new Set<string>()
+  private onMessage: MessageHandler | null = null
+  private onStatusChange: (() => void) | null = null
+
+  get subscriptions(): ReadonlySet<string> {
+    return this._subscriptions
+  }
+
+  constructor(config: SubwayConfig) {
+    this.name = normalizeName(config.name || DEFAULT_NAME)
+    this.relayUrl = config.relay || DEFAULT_RELAY
+    this.debug = config.debug ?? false
+  }
+
+  onMessageReceived(handler: MessageHandler): void {
+    this.onMessage = handler
+  }
+
+  onStatus(handler: () => void): void {
+    this.onStatusChange = handler
+  }
+
+  private async ensureWs(): Promise<typeof import("ws").WebSocket> {
+    if (this.WebSocketCtor) return this.WebSocketCtor
+    const ws = await import("ws")
+    this.WebSocketCtor = ws.default ?? ws.WebSocket
+    return this.WebSocketCtor!
+  }
+
+  async connect(): Promise<void> {
+    const WS = await this.ensureWs()
+    if (this.ws && (this.ws.readyState === WS.OPEN || this.ws.readyState === WS.CONNECTING)) return
+    this.intentionalDisconnect = false
+
+    this.ws = new WS(this.relayUrl)
+
+    this.ws.on("open", () => {
+      this.wsSend({ type: "register", name: this.name })
+      if (this.keepaliveTimer) clearInterval(this.keepaliveTimer)
+      this.keepaliveTimer = setInterval(() => {
+        if (this.ws?.readyState === WS.OPEN) this.ws.ping()
+      }, KEEPALIVE_INTERVAL_MS)
+    })
+
+    this.ws.on("message", (data: Buffer) => {
+      let msg: Record<string, unknown>
+      try {
+        msg = JSON.parse(data.toString())
+      } catch {
+        return
+      }
+
+      if (this.debug) {
+        appendFileSync(DEBUG_LOG_PATH, `${new Date().toISOString()} ${data.toString().slice(0, 500)}\n`)
+      }
+
+      this.dispatch(msg)
+    })
+
+    this.ws.on("close", () => {
+      this.registered = false
+      this.onStatusChange?.()
+      if (!this.intentionalDisconnect) {
+        this.reconnectTimer = setTimeout(() => this.connect(), 5000)
+      }
+    })
+
+    this.ws.on("error", () => {})
+  }
+
+  disconnect(): void {
+    this.intentionalDisconnect = true
+    if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = null }
+    if (this.keepaliveTimer) { clearInterval(this.keepaliveTimer); this.keepaliveTimer = null }
+    if (this.healthCheckTimer) { clearInterval(this.healthCheckTimer); this.healthCheckTimer = null }
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer)
+      p.reject(new Error("disconnected"))
+    }
+    this.pending.clear()
+    if (this.ws) { this.ws.removeAllListeners(); this.ws.close(); this.ws = null }
+    this.registered = false
+    this.registeredPeerId = null
+    this._subscriptions.clear()
+    this.onStatusChange?.()
+  }
+
+  private startHealthCheck(): void {
+    if (this.healthCheckTimer) clearInterval(this.healthCheckTimer)
+    this.healthCheckTimer = setInterval(() => this.runHealthCheck(), HEALTH_CHECK_INTERVAL_MS)
+  }
+
+  private runHealthCheck(): void {
+    if (!this.registered || !this.ws) return
+    const WS = this.WebSocketCtor
+    if (!WS || this.ws.readyState !== WS.OPEN) return
+
+    const checkId = `healthcheck:${this.name}:${Date.now()}`
+    const timer = setTimeout(() => {
+      this.pending.delete(checkId)
+      this.log("health check timed out — forcing reconnect")
+      this.forceReconnect()
+    }, 10_000)
+
+    this.pending.set(checkId, {
+      resolve: (peerId: unknown) => {
+        if (this.registeredPeerId && peerId !== this.registeredPeerId) {
+          this.log(`stale registration detected: relay has ${peerId}, we are ${this.registeredPeerId} — forcing reconnect`)
+          this.forceReconnect()
+        }
+      },
+      reject: () => {
+        this.log("health check resolve failed — name not found, forcing reconnect")
+        this.forceReconnect()
+      },
+      timer,
+    })
+    this.wsSend({ type: "resolve", name: this.name })
+  }
+
+  private forceReconnect(): void {
+    if (this.ws) { this.ws.removeAllListeners(); this.ws.close(); this.ws = null }
+    this.registered = false
+    this.registeredPeerId = null
+    this.onStatusChange?.()
+    setTimeout(() => this.connect(), 1000)
+  }
+
+  private log(msg: string): void {
+    if (this.debug) {
+      appendFileSync(DEBUG_LOG_PATH, `${new Date().toISOString()} [health] ${msg}\n`)
+    }
+  }
+
+  async connectAndWait(timeoutMs = 5000): Promise<boolean> {
+    const WS = await this.ensureWs()
+    if (this.registered && this.ws?.readyState === WS.OPEN) return true
+    await this.connect()
+    return new Promise((resolve) => {
+      const check = setInterval(() => {
+        if (this.registered) {
+          clearInterval(check)
+          clearTimeout(timeout)
+          resolve(true)
+        }
+      }, 50)
+      const timeout = setTimeout(() => {
+        clearInterval(check)
+        resolve(false)
+      }, timeoutMs)
+    })
+  }
+
+  send(to: string, text: string): boolean {
+    if (!this.registered) return false
+    return this.wsSend({ type: "send", to, message_type: "text", payload: text })
+  }
+
+  call(to: string, method: string, payload?: string, signal?: AbortSignal): Promise<CallResult> {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) return reject(new Error("aborted"))
+      if (!this.isConnected()) return reject(new Error("Not connected to Subway relay"))
+      const id = crypto.randomUUID()
+      const cleanup = () => { this.pending.delete(id); clearTimeout(timer) }
+      const timer = setTimeout(() => {
+        cleanup()
+        reject(new Error(`RPC call to ${to}.${method} timed out (${RPC_TIMEOUT_MS / 1000}s)`))
+      }, RPC_TIMEOUT_MS)
+      const onAbort = () => { cleanup(); reject(new Error("aborted")) }
+      signal?.addEventListener("abort", onAbort, { once: true })
+      this.pending.set(id, {
+        resolve: (v: unknown) => { signal?.removeEventListener("abort", onAbort); resolve(v as CallResult) },
+        reject: (e: Error) => { signal?.removeEventListener("abort", onAbort); reject(e) },
+        timer,
+      })
+      this.wsSend({ type: "call", to, method, payload: payload ?? "", correlation_id: id })
+    })
+  }
+
+  resolve(targetName: string, signal?: AbortSignal): Promise<string> {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) return reject(new Error("aborted"))
+      if (!this.isConnected()) return reject(new Error("Not connected to Subway relay"))
+      const id = `resolve:${targetName}:${Date.now()}`
+      const cleanup = () => { this.pending.delete(id); clearTimeout(timer) }
+      const timer = setTimeout(() => {
+        cleanup()
+        reject(new Error(`Resolve timed out: ${targetName}`))
+      }, RESOLVE_TIMEOUT_MS)
+      const onAbort = () => { cleanup(); reject(new Error("aborted")) }
+      signal?.addEventListener("abort", onAbort, { once: true })
+      this.pending.set(id, {
+        resolve: (v: unknown) => { signal?.removeEventListener("abort", onAbort); resolve(v as string) },
+        reject: (e: Error) => { signal?.removeEventListener("abort", onAbort); reject(e) },
+        timer,
+      })
+      this.wsSend({ type: "resolve", name: targetName })
+    })
+  }
+
+  respondToRpc(correlationId: string, success: boolean, payload: string, error?: string): boolean {
+    if (!this.registered) return false
+    return this.wsSend({
+      type: "call_response",
+      correlation_id: correlationId,
+      success,
+      payload,
+      error: error ?? "",
+    })
+  }
+
+  subscribe(topic: string): boolean {
+    if (!this.registered) return false
+    const ok = this.wsSend({ type: "subscribe", topic })
+    if (ok) this._subscriptions.add(topic)
+    return ok
+  }
+
+  unsubscribe(topic: string): boolean {
+    if (!this.registered) return false
+    const ok = this.wsSend({ type: "unsubscribe", topic })
+    if (ok) this._subscriptions.delete(topic)
+    return ok
+  }
+
+  broadcast(topic: string, text: string): boolean {
+    if (!this.registered) return false
+    return this.wsSend({ type: "broadcast", topic, message_type: "text", payload: text })
+  }
+
+  setName(name: string): void {
+    this.name = normalizeName(name)
+  }
+
+  private isConnected(): boolean {
+    return !!(this.ws && this.registered)
+  }
+
+  private wsSend(msg: Record<string, unknown>): boolean {
+    const WS = this.WebSocketCtor
+    if (!this.ws || !WS || this.ws.readyState !== WS.OPEN) return false
+    this.ws.send(JSON.stringify(msg))
+    return true
+  }
+
+  private pushInbox(from: string, payload: string): SubwayMessage {
+    const entry: SubwayMessage = { ts: Date.now(), from, payload }
+    this.inbox.push(entry)
+    if (this.inbox.length > MAX_INBOX) this.inbox.splice(0, this.inbox.length - MAX_INBOX)
+    return entry
+  }
+
+  private dispatch(msg: Record<string, unknown>): void {
+    const type = msg.type as string
+
+    switch (type) {
+      case "registered":
+        this.registered = true
+        this.registeredPeerId = (msg.peer_id as string) ?? null
+        this.startHealthCheck()
+        this.onStatusChange?.()
+        break
+
+      case "message":
+        this.pushInbox(
+          (msg.from_name || msg.from_peer) as string,
+          msg.payload as string,
+        )
+        break
+
+      case "inbound_call":
+        this.pushInbox(
+          (msg.from_name || msg.from_peer || "unknown") as string,
+          `[RPC ${msg.method || "unknown"}] ${msg.payload || ""}`,
+        )
+        break
+
+      case "call_result": {
+        const cid = msg.correlation_id as string
+        const p = cid ? this.pending.get(cid) : undefined
+        if (p) {
+          this.pending.delete(cid)
+          clearTimeout(p.timer)
+          p.resolve({
+            success: msg.success ?? false,
+            payload: msg.payload ?? "",
+            error: msg.error ?? "",
+          })
+        }
+        break
+      }
+
+      case "resolved": {
+        const name = msg.name as string
+        const key = [...this.pending.keys()].find((k) =>
+          k.startsWith(`resolve:${name}:`) || k.startsWith(`healthcheck:${name}:`),
+        )
+        if (key) {
+          const p = this.pending.get(key)!
+          this.pending.delete(key)
+          clearTimeout(p.timer)
+          p.resolve(msg.peer_id ?? "")
+        }
+        break
+      }
+
+      case "broadcast_message":
+        this.pushInbox(
+          (msg.from_name || msg.from_peer_id || "unknown") as string,
+          `[${msg.topic}] ${msg.payload}`,
+        )
+        break
+
+      case "error": {
+        const errMsg = (msg.message || msg.error || "") as string
+        const errorName = msg.name as string | undefined
+        if (errMsg.includes("name_not_found") && errorName) {
+          const key = [...this.pending.keys()].find((k) =>
+            k.startsWith(`resolve:${errorName}:`) || k.startsWith(`healthcheck:${errorName}:`),
+          )
+          if (key) {
+            const p = this.pending.get(key)!
+            this.pending.delete(key)
+            clearTimeout(p.timer)
+            p.reject(new Error(`Name not found: ${errorName}`))
+          }
+        }
+        break
+      }
+    }
+
+    this.onMessage?.(type, msg)
+  }
+}
+
+// ─── Exported module state (for other JFL modules to query) ──────────────────
+
+let meshClient: SubwayClient | null = null
+
+export function getMeshClient(): SubwayClient | null {
+  return meshClient
+}
+
+// ─── Setup ───────────────────────────────────────────────────────────────────
+
+let standaloneDetected = false
+
+export function isStandaloneSubwayLoaded(): boolean {
+  return standaloneDetected
+}
+
+export async function setupSubwayMesh(ctx: PiContext, _config: JflConfig): Promise<void> {
+  // Detect if the standalone subway Pi extension is already loaded.
+  // If so, skip everything — let the standalone handle mesh tools, TUI, and lifecycle.
+  // This avoids double WebSocket connections, duplicate tool registrations, and command conflicts.
+  const existingTools = ctx.pi.getAllTools()
+  if (existingTools.some(t => t.name === "subway_send")) {
+    standaloneDetected = true
+    ctx.log("Subway mesh: standalone extension detected, skipping built-in mesh setup", "debug")
+    return
+  }
+
+  const config = loadConfig()
+  const client = new SubwayClient(config)
+  meshClient = client
+
+  let widgetDebounce: ReturnType<typeof setTimeout> | null = null
+
+  function scheduleWidgetUpdate(): void {
+    if (widgetDebounce) clearTimeout(widgetDebounce)
+    widgetDebounce = setTimeout(() => updateWidget(), 250)
+  }
+
+  // ─── Status bar ────────────────────────────────────────────────────────────
+
+  client.onStatus(() => {
+    if (client.registered) {
+      ctx.ui.setStatus("subway", ctx.ui.theme.fg("success", `● ${client.name}`))
+      ctx.ui.notify(`Subway: connected as ${client.name}`, { level: "info" })
+    } else {
+      ctx.ui.setStatus("subway", ctx.ui.theme.fg("error", "○ subway (disconnected)"))
+    }
+    updateWidget()
+  })
+
+  // ─── Message delivery into conversation ────────────────────────────────────
+
+  client.onMessageReceived((type, msg) => {
+    if (type === "message") {
+      const from = (msg.from_name || msg.from_peer) as string
+      ctx.pi.sendMessage(
+        { customType: `subway - ${displayName(from)}`, content: msg.payload as string, display: true },
+        { triggerTurn: true, deliverAs: "followUp" },
+      )
+      scheduleWidgetUpdate()
+    }
+
+    if (type === "inbound_call") {
+      const from = (msg.from_name || msg.from_peer || "unknown") as string
+      const method = msg.method || "unknown"
+      const correlationId = msg.correlation_id || ""
+      ctx.pi.sendMessage(
+        {
+          customType: `subway - ${displayName(from)}`,
+          content: `[RPC ${method}] correlation_id=${correlationId}\n\n${msg.payload || ""}`,
+          display: true,
+        },
+        { triggerTurn: true, deliverAs: "followUp" },
+      )
+      scheduleWidgetUpdate()
+    }
+
+    if (type === "broadcast_message") {
+      const from = (msg.from_name || msg.from_peer_id || "unknown") as string
+      ctx.pi.sendMessage(
+        { customType: `subway - ${displayName(from)}`, content: `[${msg.topic}] ${msg.payload}`, display: true },
+        { triggerTurn: false },
+      )
+      scheduleWidgetUpdate()
+    }
+
+    if (type === "error") {
+      const errMsg = (msg.message || msg.error || "") as string
+      if (errMsg.includes("NoPeersSubscribedToTopic")) {
+        ctx.ui.notify("Subway: no subscribers on topic", { level: "warn" })
+      } else if (!errMsg.includes("already registered")) {
+        ctx.ui.notify(`Subway error: ${errMsg}`, { level: "error" })
+      }
+    }
+  })
+
+  // ─── Widget ────────────────────────────────────────────────────────────────
+
+  function updateWidget(): void {
+    if (!client.registered) {
+      ctx.ui.setWidget("subway", undefined)
+      ctx.ui.setStatus("subway", undefined)
+      return
+    }
+
+    ctx.ui.setWidget("subway", (_tui: any, theme: PiTheme) => ({
+      render: (width: number) => {
+        const lines: string[] = []
+        const relay = client.relayUrl.replace("wss://", "").replace("/ws", "")
+        lines.push(`${theme.fg("success", "●")} ${theme.fg("accent", client.name)} ${theme.fg("dim", `→ ${relay}`)} ${theme.fg("dim", "(connected)")}`)
+
+        const recent = client.inbox.slice(-MAX_VISIBLE_WIDGET)
+        const maxPayload = Math.max(20, width - 30)
+        for (const m of recent) {
+          const time = new Date(m.ts).toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit" })
+          const payload = m.payload.length > maxPayload ? m.payload.slice(0, maxPayload - 3) + "..." : m.payload
+          const line = theme.fg("dim", time) + " " + theme.fg("accent", m.from) + " " + payload
+          lines.push(line.length > width ? line.slice(0, width - 1) + "…" : line)
+        }
+
+        return lines
+      },
+      invalidate: () => {},
+    }))
+  }
+
+  // ─── Tools ─────────────────────────────────────────────────────────────────
+
+  ctx.registerTool({
+    name: "subway_send",
+    description: "Send a message to another agent on the Subway P2P mesh. Use this to reply to subway messages or reach out to peers.",
+    promptSnippet: "Send a message to another agent on the Subway P2P mesh",
+    promptGuidelines: [
+      "When you receive a [Subway message from X], reply using subway_send with to=X.",
+      "Agent names end in .relay (e.g., datboi.relay, hathbanger.relay, andrew.relay).",
+    ],
+    inputSchema: {
+      type: "object",
+      properties: {
+        to: { type: "string", description: "Target agent name (e.g. datboi.relay)" },
+        message: { type: "string", description: "Message text to send" },
+      },
+      required: ["to", "message"],
+    },
+    async handler(input) {
+      const { to, message } = input as { to: string; message: string }
+      if (!client.send(to, message)) return "Not connected to Subway relay."
+      return `Sent to ${to}: ${message}`
+    },
+  })
+
+  ctx.registerTool({
+    name: "subway_call",
+    description:
+      "Make an RPC call to another agent on the Subway P2P mesh and wait for a response. " +
+      "Use this when you need a result back — e.g. asking an agent to run a task and report the outcome. Timeout: 30 seconds.",
+    promptSnippet: "Make an RPC call to another Subway agent and wait for response (30s timeout)",
+    promptGuidelines: [
+      "Use subway_call when you need a response back from an agent.",
+      "Use subway_send for fire-and-forget messages that don't need a reply.",
+    ],
+    inputSchema: {
+      type: "object",
+      properties: {
+        to: { type: "string", description: "Target agent name (e.g. datboi.relay)" },
+        method: { type: "string", description: "RPC method name (e.g. 'ping', 'ask', 'execute', 'status')" },
+        payload: { type: "string", description: "Request payload (text)" },
+      },
+      required: ["to", "method"],
+    },
+    async handler(input) {
+      const { to, method, payload } = input as { to: string; method: string; payload?: string }
+      try {
+        const result = await client.call(to, method, payload)
+        return result.success
+          ? result.payload || "(empty response)"
+          : `RPC to ${to}.${method} failed: ${result.error}`
+      } catch (err) {
+        return `RPC call failed: ${(err as Error).message}`
+      }
+    },
+  })
+
+  ctx.registerTool({
+    name: "subway_resolve",
+    description: "Check if an agent is online on the Subway P2P mesh by resolving its name. Returns the agent's PeerId if found.",
+    promptSnippet: "Check if a Subway agent is online by name",
+    promptGuidelines: [
+      "Use subway_resolve to check if an agent is reachable before calling or sending.",
+    ],
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Agent name to look up (e.g. datboi.relay)" },
+      },
+      required: ["name"],
+    },
+    async handler(input) {
+      const { name } = input as { name: string }
+      try {
+        const peerId = await client.resolve(name)
+        return `${name} is online (peer: ${peerId})`
+      } catch (err) {
+        return `${name} is not reachable: ${(err as Error).message}`
+      }
+    },
+  })
+
+  ctx.registerTool({
+    name: "subway_rpc_respond",
+    description:
+      "Respond to an inbound RPC call from another agent. Use this after receiving a [Subway RPC call] message. " +
+      "You must include the correlation_id from the inbound call.",
+    promptSnippet: "Respond to an inbound Subway RPC call with correlation_id",
+    promptGuidelines: [
+      "When you receive a [Subway RPC call from X] with a correlation_id, process the request and respond using subway_rpc_respond.",
+      "Include the correlation_id exactly as received.",
+    ],
+    inputSchema: {
+      type: "object",
+      properties: {
+        correlation_id: { type: "string", description: "The correlation_id from the inbound RPC call" },
+        success: { type: "boolean", description: "Whether the call succeeded" },
+        payload: { type: "string", description: "Response payload text" },
+        error: { type: "string", description: "Error message if success is false" },
+      },
+      required: ["correlation_id", "success", "payload"],
+    },
+    async handler(input) {
+      const { correlation_id, success, payload, error } = input as {
+        correlation_id: string; success: boolean; payload: string; error?: string
+      }
+      if (!client.respondToRpc(correlation_id, success, payload, error)) return "Not connected to Subway relay."
+      return `RPC response sent (success=${success})`
+    },
+  })
+
+  ctx.registerTool({
+    name: "subway_inbox",
+    description: "Check recent messages received on the Subway mesh.",
+    promptSnippet: "Check recent Subway messages",
+    promptGuidelines: [
+      "Use subway_inbox to review recent messages if context was lost or to catch up after reconnecting.",
+    ],
+    inputSchema: {
+      type: "object",
+      properties: {
+        count: { type: "number", description: "Number of recent messages (default 10)" },
+      },
+    },
+    async handler(input) {
+      const { count } = input as { count?: number }
+      const recent = client.inbox.slice(-(count || 10))
+      if (recent.length === 0) return "No messages in inbox."
+      return recent.map((m) => `[${new Date(m.ts).toISOString()}] ${m.from}: ${m.payload}`).join("\n")
+    },
+  })
+
+  ctx.registerTool({
+    name: "subway_subscribe",
+    description:
+      "Subscribe to a pub/sub topic on the Subway mesh. Wildcard supported: 'metrics.*' matches metrics.cpu, metrics.mem. " +
+      "Broadcast messages on subscribed topics will appear in the conversation.",
+    promptSnippet: "Subscribe to a Subway pub/sub topic (wildcards supported)",
+    promptGuidelines: [
+      "Use subway_subscribe to listen for broadcast messages on a topic.",
+      "Wildcard topics like 'metrics.*' match all subtopics (e.g. metrics.cpu, metrics.mem).",
+      "Subscriptions persist for the session — use subway_unsubscribe to stop receiving a topic.",
+    ],
+    inputSchema: {
+      type: "object",
+      properties: {
+        topic: { type: "string", description: "Topic to subscribe to (e.g. 'status', 'metrics.*')" },
+      },
+      required: ["topic"],
+    },
+    async handler(input) {
+      const { topic } = input as { topic: string }
+      if (!client.subscribe(topic)) return "Not connected to Subway relay."
+      return `Subscribed to topic: ${topic}`
+    },
+  })
+
+  ctx.registerTool({
+    name: "subway_unsubscribe",
+    description: "Unsubscribe from a pub/sub topic on the Subway mesh.",
+    promptSnippet: "Unsubscribe from a Subway pub/sub topic",
+    promptGuidelines: [
+      "Use subway_unsubscribe when you no longer need to receive messages on a topic.",
+    ],
+    inputSchema: {
+      type: "object",
+      properties: {
+        topic: { type: "string", description: "Topic to unsubscribe from" },
+      },
+      required: ["topic"],
+    },
+    async handler(input) {
+      const { topic } = input as { topic: string }
+      if (!client.unsubscribe(topic)) return "Not connected to Subway relay."
+      return `Unsubscribed from topic: ${topic}`
+    },
+  })
+
+  ctx.registerTool({
+    name: "subway_broadcast",
+    description:
+      "Broadcast a message to all subscribers of a topic on the Subway P2P mesh. " +
+      "All agents subscribed to the topic (or a matching wildcard) will receive the message.",
+    promptSnippet: "Broadcast a message to all subscribers of a Subway topic",
+    promptGuidelines: [
+      "Use subway_broadcast to publish to all agents subscribed to a topic.",
+      "Any agent subscribed to the topic or a matching wildcard will receive the message.",
+      "Use subway_send for direct messages to a specific agent instead.",
+    ],
+    inputSchema: {
+      type: "object",
+      properties: {
+        topic: { type: "string", description: "Topic to broadcast to (e.g. 'status', 'builds')" },
+        message: { type: "string", description: "Message text to broadcast" },
+      },
+      required: ["topic", "message"],
+    },
+    async handler(input) {
+      const { topic, message } = input as { topic: string; message: string }
+      if (!client.broadcast(topic, message)) return "Not connected to Subway relay."
+      return `Broadcast to ${topic}: ${message}`
+    },
+  })
+
+  // ─── /subway command ────────────────────────────────────────────────────────
+
+  ctx.registerCommand({
+    name: "subway",
+    description: "Subway mesh commands (status, connect [name], disconnect, reconnect [name], send <to> <msg>, subscribe <topic>, unsubscribe <topic>, broadcast <topic> <msg>, inbox)",
+    async handler(args: string, _ctx: PiContext) {
+      const parts = args.trim().split(/\s+/)
+      const sub = parts[0] || "status"
+
+      switch (sub) {
+        case "status": {
+          const status = client.registered ? "connected" : "disconnected"
+          ctx.ui.notify(
+            `Subway: ${status} as ${client.name} | relay: ${client.relayUrl} | ${client.inbox.length} messages`,
+            { level: client.registered ? "info" : "warn" },
+          )
+          break
+        }
+        case "connect": {
+          if (parts[1]) {
+            const newName = normalizeName(parts[1])
+            client.setName(newName)
+            const cfg = loadConfig()
+            cfg.name = newName
+            saveConfig(cfg)
+            if (client.registered) client.disconnect()
+          } else if (client.registered) {
+            ctx.ui.notify(`Already connected as ${client.name}`, { level: "info" })
+            break
+          }
+          ctx.ui.notify(`Connecting as ${client.name}...`, { level: "info" })
+          const ok = await client.connectAndWait()
+          ctx.ui.notify(ok ? `Connected as ${client.name}` : "Failed to connect (timeout)", { level: ok ? "info" : "error" })
+          break
+        }
+        case "disconnect": {
+          if (!client.registered) { ctx.ui.notify("Already disconnected", { level: "info" }); break }
+          client.disconnect()
+          ctx.ui.notify("Disconnected from Subway", { level: "info" })
+          break
+        }
+        case "reconnect": {
+          if (parts[1]) {
+            const newName = normalizeName(parts[1])
+            client.setName(newName)
+            const cfg = loadConfig()
+            cfg.name = newName
+            saveConfig(cfg)
+          }
+          ctx.ui.notify(`Reconnecting as ${client.name}...`, { level: "info" })
+          client.disconnect()
+          const ok = await client.connectAndWait()
+          ctx.ui.notify(ok ? `Connected as ${client.name}` : "Failed to reconnect (timeout)", { level: ok ? "info" : "error" })
+          break
+        }
+        case "send": {
+          if (parts.length < 3) { ctx.ui.notify("Usage: /subway send <to> <msg>", { level: "info" }); break }
+          const ok = client.send(parts[1]!, parts.slice(2).join(" "))
+          ctx.ui.notify(ok ? `Sent to ${parts[1]}` : "Not connected", { level: ok ? "info" : "error" })
+          break
+        }
+        case "inbox": {
+          const recent = client.inbox.slice(-5)
+          if (recent.length === 0) { ctx.ui.notify("Inbox empty", { level: "info" }); break }
+          for (const m of recent) ctx.ui.notify(`${m.from}: ${m.payload}`, { level: "info" })
+          break
+        }
+        case "subscribe": {
+          if (!parts[1]) { ctx.ui.notify("Usage: /subway subscribe <topic>", { level: "info" }); break }
+          const ok = client.subscribe(parts[1])
+          ctx.ui.notify(ok ? `Subscribed to ${parts[1]}` : "Not connected", { level: ok ? "info" : "error" })
+          break
+        }
+        case "unsubscribe": {
+          if (!parts[1]) { ctx.ui.notify("Usage: /subway unsubscribe <topic>", { level: "info" }); break }
+          const ok = client.unsubscribe(parts[1])
+          ctx.ui.notify(ok ? `Unsubscribed from ${parts[1]}` : "Not connected", { level: ok ? "info" : "error" })
+          break
+        }
+        case "broadcast": {
+          if (parts.length < 3) { ctx.ui.notify("Usage: /subway broadcast <topic> <msg>", { level: "info" }); break }
+          const ok = client.broadcast(parts[1]!, parts.slice(2).join(" "))
+          ctx.ui.notify(ok ? `Broadcast to ${parts[1]}` : "Not connected", { level: ok ? "info" : "error" })
+          break
+        }
+        default:
+          ctx.ui.notify(
+            "Usage: /subway [status|connect [name]|disconnect|reconnect [name]|send <to> <msg>|subscribe <topic>|unsubscribe <topic>|broadcast <topic> <msg>|inbox]",
+            { level: "info" },
+          )
+      }
+    },
+  })
+
+  // ─── Auto-connect ──────────────────────────────────────────────────────────
+
+  updateWidget()
+
+  if (config.name) {
+    client.connectAndWait().catch(() => {})
+  }
+}
+
+// ─── Lifecycle hooks (called from index.ts) ──────────────────────────────────
+
+export function injectMeshContext(): string | undefined {
+  if (standaloneDetected) return undefined
+  if (!meshClient?.registered) return undefined
+
+  const subs = [...meshClient.subscriptions]
+  const subsStr = subs.length > 0 ? ` | subscriptions: ${subs.join(", ")}` : ""
+  const relay = meshClient.relayUrl.replace("wss://", "").replace("/ws", "")
+  return `[Subway mesh: connected as ${meshClient.name} → ${relay}${subsStr} | ${meshClient.inbox.length} messages]`
+}
+
+export function onMeshShutdown(): void {
+  if (standaloneDetected) return
+  meshClient?.disconnect()
+  meshClient = null
+}