pi-xmpp 0.1.0

package/AGENTS.md

@@ -0,0 +1,3 @@
+# Agents
+
+pi-xmpp does not ship any custom Pi agents. The extension provides the bridge runtime, tools, and slash commands for the default Pi agent to interact with XMPP.

package/BACKLOG.md

@@ -0,0 +1,17 @@
+# Backlog
+
+## v0.2.0
+
+- [ ] XMPP roster management (fetch and display contacts)
+- [ ] Message delivery receipts (XEP-0184)
+- [ ] Chat state notifications (XEP-0085)
+- [ ] File transfer support (HTTP Upload / XEP-0363)
+- [ ] End-to-end encryption (OMEMO / XEP-0384)
+- [ ] Formatted messages (XEP-0071 XHTML-IM)
+
+## v0.3.0
+
+- [ ] Multi-instance bus (like pi-telegram's threaded mode)
+- [ ] Voice message support
+- [ ] Message correction (XEP-0308)
+- [ ] Last Message Correction (XEP-0308)

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Initial release
+- XMPP connection management (connect/disconnect/auto-reconnect)
+- Direct message send/receive
+- MUC/groupchat support (join/leave/participate)
+- Presence management
+- Authorization and auto-pairing
+- Slash commands (/xmpp-connect, /xmpp-disconnect, /xmpp-status, /xmpp-join, /xmpp-leave, /xmpp-set-presence)
+- Programmatic inbound/outbound handler API
+- Companion extension API (status providers, commands, update handlers)
+- Configuration via ~/.pi/agent/xmpp.json
+- Auto-join rooms on connect

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Stan Kondrat
+
+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,124 @@
+# pi-xmpp
+
+XMPP runtime adapter for [Pi](https://github.com/earendil-works/pi).
+
+Connect your Pi agent to Jabber/XMPP servers for instant messaging with AI assistance.
+
+## Features
+
+- **XMPP Connection Management** — Connect, disconnect, and auto-reconnect to any XMPP server
+- **Direct Messaging** — Receive and respond to one-on-one chat messages
+- **MUC/Groupchat Support** — Join, leave, and participate in multi-user chat rooms
+- **Presence Management** — Set your availability and status message
+- **Authorization & Pairing** — Auto-pair on first message, restrict to specific JIDs
+- **Companion Extension API** — Register inbound/outbound handlers, status providers, and slash commands
+- **Auto-join Rooms** — Automatically join configured chat rooms on connect
+- **Slash Commands** — Control the bridge via `/xmpp-connect`, `/xmpp-status`, `/xmpp-join`, and more
+
+## Installation
+
+```bash
+npm install pi-xmpp
+```
+
+## Quick Start
+
+1. **Configure your credentials** in `~/.pi/agent/xmpp.json`:
+
+```json
+{
+  "jid": "your-username@your-server.org",
+  "password": "your-password",
+  "service": "xmpp://your-server.org"
+}
+```
+
+2. **Start Pi** and the bridge auto-connects.
+
+3. **Or connect manually** from within Pi:
+
+```
+/xmpp-connect --jid user@domain.tld --password secret --service xmpp://server.tld
+```
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/xmpp-connect` | Connect to XMPP server (--jid, --password, --service) |
+| `/xmpp-disconnect` | Disconnect from XMPP server |
+| `/xmpp-status` | Show connection status and diagnostics |
+| `/xmpp-join` | Join a MUC room (--room, --nick) |
+| `/xmpp-leave` | Leave a MUC room (--room) |
+| `/xmpp-set-presence` | Set presence (--show, --status) |
+
+## Configuration
+
+Configuration is stored in `~/.pi/agent/xmpp.json`:
+
+```json
+{
+  "jid": "user@domain.tld",
+  "password": "secret",
+  "service": "xmpp://server.tld",
+  "domain": "server.tld",
+  "resource": "pi-bridge",
+  "allowedJid": "trusted@domain.tld",
+  "autoReconnect": true,
+  "autoJoinRooms": ["room@conference.tld"]
+}
+```
+
+## Extension API
+
+### Inbound Handlers
+
+```typescript
+import { registerXmppInboundHandler } from "pi-xmpp/inbound";
+
+registerXmppInboundHandler(async (input) => {
+  if (input.body.startsWith("!ping")) {
+    return { handled: true, prompt: "User requested ping" };
+  }
+  return { handled: false };
+});
+```
+
+### Outbound Handlers
+
+```typescript
+import { registerXmppOutboundHandler } from "pi-xmpp/outbound";
+
+registerXmppOutboundHandler(async (input) => {
+  return { handled: false };
+});
+```
+
+### Status Providers
+
+```typescript
+import { registerXmppStatusLineProvider } from "pi-xmpp/status";
+
+registerXmppStatusLineProvider((ctx) => ({
+  label: "My Custom Status",
+  value: "ok",
+}));
+```
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│  XMPP Server│◄───►│  xmpp.js     │◄───►│  pi-xmpp    │
+│             │     │  Client      │     │  Extension  │
+└─────────────┘     └──────────────┘     └──────┬──────┘
+                                                │
+                                         ┌──────▼──────┐
+                                         │  Pi Agent   │
+                                         │  Runtime    │
+                                         └─────────────┘
+```
+
+## License
+
+MIT

package/api/commands.ts

@@ -0,0 +1,11 @@
+/**
+ * Public XMPP commands API
+ * Zones: package boundary, companion extension interop
+ * Exposes the stable XMPP slash-command registration surface
+ */
+
+export {
+  registerXmppCommand,
+  type XmppExtensionCommandContext,
+  type XmppExtensionCommandRegistration,
+} from "../lib/commands.ts";

package/api/inbound.ts

@@ -0,0 +1,14 @@
+/**
+ * Public XMPP inbound API
+ * Zones: package boundary, companion extension interop
+ * Exposes the stable programmatic inbound handler surface
+ */
+
+export {
+  registerXmppInboundHandler,
+  type XmppInboundHandlerFile,
+  type XmppInboundHandlerOutput,
+  type XmppInboundProgrammaticHandler,
+  type XmppInboundProgrammaticHandlerInput,
+  type XmppInboundProgrammaticHandlerResult,
+} from "../lib/inbound.ts";

package/api/outbound.ts

@@ -0,0 +1,11 @@
+/**
+ * Public XMPP outbound API
+ * Zones: package boundary, companion extension interop
+ * Exposes stable outbound handler and diagnostics surfaces
+ */
+
+export {
+  recordXmppRuntimeEvent,
+  registerXmppOutboundHandler,
+  type XmppOutboundProgrammaticHandler,
+} from "../lib/outbound.ts";

package/api/status.ts

@@ -0,0 +1,12 @@
+/**
+ * Public XMPP status API
+ * Zones: package boundary, companion extension interop
+ * Exposes compact status-line registration for companion extensions
+ */
+
+export {
+  registerXmppStatusLineProvider,
+  type XmppStatusLineProvider,
+  type XmppStatusLineProviderContext,
+  type XmppStatusLineProviderResult,
+} from "../lib/status.ts";

package/api/updates.ts

@@ -0,0 +1,41 @@
+/**
+ * Public XMPP updates API
+ * Zones: package boundary, companion extension interop
+ * Exposes the stable stanza handler surface
+ */
+
+import type { XmppStanza } from "../lib/xmpp-api.ts";
+
+export type XmppUpdateHandlerVerdict =
+  | { handled: true }
+  | { handled: false; reason?: string };
+
+export interface XmppUpdateHandler {
+  (stanza: XmppStanza): XmppUpdateHandlerVerdict | Promise<XmppUpdateHandlerVerdict>;
+}
+
+const UPDATE_HANDLER_REGISTRY_KEY = "__piXmppUpdateHandlers__";
+
+/**
+ * Register a raw stanza update handler.
+ * Handlers receive every incoming stanza and can mark it as handled
+ * to prevent further processing by the default message pipeline.
+ */
+export function registerXmppUpdateHandler(
+  handler: XmppUpdateHandler,
+): void {
+  const registry = getUpdateHandlerRegistry();
+  registry.push(handler);
+}
+
+function getUpdateHandlerRegistry(): XmppUpdateHandler[] {
+  const globals = globalThis as Record<string, unknown>;
+  if (!globals[UPDATE_HANDLER_REGISTRY_KEY]) {
+    globals[UPDATE_HANDLER_REGISTRY_KEY] = [];
+  }
+  return globals[UPDATE_HANDLER_REGISTRY_KEY] as XmppUpdateHandler[];
+}
+
+export function getXmppUpdateHandlers(): XmppUpdateHandler[] {
+  return getUpdateHandlerRegistry();
+}

package/index.ts

@@ -0,0 +1,325 @@
+/**
+ * XMPP bridge extension entrypoint and orchestration layer
+ * Zones: xmpp, pi agent, orchestration
+ * Keeps the runtime wiring in one place while delegating reusable domain logic to /lib modules
+ */
+
+import * as Pi from "./lib/pi.ts";
+import * as Commands from "./lib/commands.ts";
+import * as Config from "./lib/config.ts";
+import * as Inbound from "./lib/inbound.ts";
+import * as Lifecycle from "./lib/lifecycle.ts";
+import * as Model from "./lib/model.ts";
+import * as Outbound from "./lib/outbound.ts";
+import * as Prompts from "./lib/prompts.ts";
+import * as Queue from "./lib/queue.ts";
+import * as Routing from "./lib/routing.ts";
+import * as Runtime from "./lib/runtime.ts";
+import * as Status from "./lib/status.ts";
+import * as XmppApi from "./lib/xmpp-api.ts";
+import { Type } from "@sinclair/typebox";
+import * as Updates from "./api/updates.ts";
+
+// --- Extension Runtime ---
+
+export default function (pi: Pi.ExtensionAPI) {
+  const piRuntime = Pi.createExtensionApiRuntimePorts(pi);
+  const { sendUserMessage } = piRuntime;
+
+  // --- XMPP Client ---
+  const xmppClient = XmppApi.createXmppClient();
+
+  // --- Instance identity ---
+  const xmppInstanceId = `${process.pid}:${Date.now()}`;
+
+  // --- Runtime ---
+  const bridgeRuntime = Runtime.createXmppBridgeRuntime();
+  const { abort, lifecycle, queue } = bridgeRuntime;
+
+  // --- Config ---
+  const runtimeEvents = Status.createXmppRuntimeEventRecorder();
+  const configStore = Config.createXmppConfigStore({ recordRuntimeEvent: runtimeEvents.record });
+  Outbound.bindXmppRuntimeEventRecorder(runtimeEvents.record);
+
+  const recordRuntimeEvent = function (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) {
+    runtimeEvents.record(category, error ?? undefined, details);
+  };
+
+  // --- Context store ---
+  const sessionContextStore = Lifecycle.createXmppSessionContextStore<Pi.ExtensionContext>();
+
+  // --- Active turn store ---
+  const activeTurnRuntime = Queue.createXmppActiveTurnStore();
+
+  // --- Queue store ---
+  const xmppQueueStore = Queue.createXmppQueueStore<Pi.ExtensionContext>();
+
+  // --- Status helpers ---
+  const getAllowedJid = () => configStore.getAllowedJid();
+  const getConnectionStatus = () => xmppClient.status;
+  const getActiveTurnFrom = () => activeTurnRuntime.get()?.fromBare;
+
+  const sendMessageToActiveTurn = async function (body: string): Promise<void> {
+    sendUserMessage(body);
+  };
+
+  // --- Incoming stanza handler ---
+  const handleIncomingStanza = async function (stanza: XmppApi.XmppStanza): Promise<void> {
+    // Run through update handlers first
+    const updateHandlers = Updates.getXmppUpdateHandlers();
+    for (const handler of updateHandlers) {
+      try {
+        const verdict = await handler(stanza);
+        if (verdict.handled) return;
+      } catch {
+        // Continue to next handler
+      }
+    }
+
+    // Route the stanza
+    const route = Routing.routeStanza(stanza);
+    if (!route) return;
+
+    if (route.kind === "message") {
+      await handleIncomingMessage(route);
+    } else if (route.kind === "presence") {
+      await handleIncomingPresence(route);
+    }
+  };
+
+  // --- Incoming message handler ---
+  const handleIncomingMessage = async function (route: Routing.XmppMessageRoute): Promise<void> {
+    // Skip error messages
+    if (route.type === "error") return;
+
+    // Check authorization
+    const auth = Config.getXmppAuthorizationState(
+      route.fromBare,
+      configStore.getAllowedJid(),
+    );
+
+    if (auth.kind === "deny") return;
+
+    // Auto-pair if needed
+    if (auth.kind === "pair") {
+      configStore.setAllowedJid(route.fromBare);
+      await configStore.persist();
+      recordRuntimeEvent("pair", null, { jid: route.fromBare });
+    }
+
+    // Process through inbound handler pipeline
+    const config = configStore.get();
+    const inboundResult = await Inbound.processXmppInbound(route, config);
+
+    // Build turn context
+    const turn: Queue.XmppTurnContext = {
+      from: route.from,
+      fromBare: route.fromBare,
+      body: inboundResult.rawText,
+      type: route.type,
+      thread: route.thread,
+      subject: route.subject,
+      isGroup: route.isGroup,
+      roomJid: route.roomJid,
+      senderNick: route.senderNick,
+      timestamp: Date.now(),
+    };
+
+    // Build prompt
+    const prompt = Queue.buildXmppTurnPrompt(turn, {
+      includeThread: true,
+      extraContext: inboundResult.handlerOutputs.length > 0
+        ? `handler outputs: ${inboundResult.handlerOutputs.join("; ")}`
+        : undefined,
+    });
+
+    // Enqueue the message
+    const ctx = sessionContextStore.get();
+    if (ctx) {
+      const item: Queue.XmppQueueItem<Pi.ExtensionContext> = {
+        id: `xmpp-${queue.allocateItemOrder()}-${Date.now()}`,
+        order: queue.allocateItemOrder(),
+        turn,
+        prompt,
+        ctx,
+        status: "queued",
+      };
+
+      xmppQueueStore.enqueue(item);
+      dispatchNextQueuedTurn();
+    }
+  };
+
+  // --- Incoming presence handler ---
+  const handleIncomingPresence = async function (
+    route: Routing.XmppPresenceRoute,
+  ): Promise<void> {
+    recordRuntimeEvent("presence", null, {
+      from: route.from,
+      type: route.type,
+      show: route.show,
+    });
+  };
+
+  // --- Dispatch next queued turn ---
+  const dispatchNextQueuedTurn = function (): void {
+    if (bridgeRuntime.state.xmppTurnDispatchPending) return;
+    if (bridgeRuntime.state.compactionInProgress) return;
+    if (activeTurnRuntime.has()) return;
+
+    const next = xmppQueueStore.dequeue();
+    if (!next) return;
+
+    bridgeRuntime.state.xmppTurnDispatchPending = true;
+    activeTurnRuntime.set(next.turn);
+
+    const ctx = next.ctx;
+
+    // Set abort handler
+    const abortController = new AbortController();
+    abort.setHandler(() => {
+      abortController.abort();
+      activeTurnRuntime.clear();
+      bridgeRuntime.state.xmppTurnDispatchPending = false;
+    });
+
+    // Send the prompt to Pi
+    // Note: activeTurnRuntime is cleared in onAgentEnd after the agent finishes processing
+    try {
+      sendUserMessage(next.prompt);
+    } catch (error: unknown) {
+      recordRuntimeEvent("dispatch", error);
+      activeTurnRuntime.clear();
+      bridgeRuntime.state.xmppTurnDispatchPending = false;
+      abort.clearHandler();
+    }
+  };
+
+  // --- Register slash commands ---
+  const allCommands = Commands.createXmppSlashCommands({
+    client: xmppClient,
+    configStore,
+    runtime: bridgeRuntime,
+    getConnectionStatus,
+    sendMessageToActiveTurn,
+    updateStatus: () => {
+      // Status is pushed declaratively via getConnectionStatus/getAllowedJid;
+      // individual commands that change state can call this to trigger a status refresh.
+    },
+    getAllowedJid,
+  });
+
+  for (const cmd of allCommands) {
+    pi.registerCommand(cmd.name, {
+      description: cmd.description,
+      handler: async (_args: string, _ctx: Pi.ExtensionCommandContext) => {
+        await cmd.handler({ args: [], rawArgs: _args });
+      },
+    });
+  }
+
+    // --- Register the xmpp_send tool ---
+  pi.registerTool({
+    name: "xmpp_send",
+    label: "Send XMPP Message",
+    description:
+      "Send a message via XMPP. Provide `to` (JID), `body` (message text), and optionally `type` (chat or groupchat).",
+    parameters: Type.Object({
+      to: Type.String({ description: "Recipient JID" }),
+      body: Type.String({ description: "Message body" }),
+      type: Type.Optional(Type.String({ description: "Message type (default: chat)" })),
+      subject: Type.Optional(Type.String({ description: "Optional message subject" })),
+    }),
+    execute: async (_toolCallId: string, params: { to: string; body: string; type?: string; subject?: string }) => {
+      try {
+        await Outbound.sendXmppMessage(xmppClient, params.to, params.body, {
+          type: params.type,
+          subject: params.subject,
+        });
+        return {
+          content: [{ type: "text" as const, text: `Message sent to ${params.to}` }],
+          details: {},
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Failed to send message: ${error instanceof Error ? error.message : String(error)}`,
+            },
+          ],
+          isError: true,
+          details: {},
+        };
+      }
+    },
+  });
+
+  // --- Register the xmpp_help tool ---
+  Prompts.registerXmppHelpTool(pi);
+
+  // --- Lifecycle hooks ---
+  const beforeAgentStartHook = Prompts.createXmppBeforeAgentStartHook();
+
+  Lifecycle.registerXmppLifecycleHooks(pi, {
+    onSessionStart: async (_event, ctx) => {
+      sessionContextStore.set(ctx);
+
+      // Try to auto-connect if credentials are stored
+      const config = configStore.get();
+      if (config.jid && config.password && xmppClient.status === "offline") {
+        try {
+          await xmppClient.connect(config);
+
+          // Auto-join configured rooms
+          if (config.autoJoinRooms?.length) {
+            const nick = config.jid.split("@")[0];
+            for (const room of config.autoJoinRooms) {
+              xmppClient.joinRoom(room, nick);
+            }
+          }
+        } catch (error) {
+          recordRuntimeEvent("auto-connect", error);
+        }
+      }
+    },
+
+    onSessionShutdown: async () => {
+      sessionContextStore.clear();
+    },
+
+    onBeforeAgentStart: async (event) => {
+      return beforeAgentStartHook(event);
+    },
+
+    onAgentStart: async () => {
+      // Agent started processing
+    },
+
+    onAgentEnd: async () => {
+      // Agent finished processing; clear active turn and dispatch next queued
+      activeTurnRuntime.clear();
+      bridgeRuntime.state.xmppTurnDispatchPending = false;
+      abort.clearHandler();
+      dispatchNextQueuedTurn();
+    },
+  });
+
+  // --- Stanza listener ---
+  xmppClient.onStanza(handleIncomingStanza);
+
+  // --- Record extension start ---
+  recordRuntimeEvent("extension-start", null, {
+    instanceId: xmppInstanceId,
+    pid: process.pid,
+  });
+
+  // --- Handle uncaught XMPP errors ---
+  xmppClient.onError((error) => {
+    recordRuntimeEvent("xmpp-error", error);
+  });
+}