pi-xmpp 0.1.0

package/lib/commands.ts

@@ -0,0 +1,245 @@
+/**
+ * XMPP extension slash commands
+ * Zones: pi agent commands, xmpp specific
+ * Owns /xmpp slash commands for connection management, status, and control
+ */
+
+import type { ExtensionAPI } from "./pi.ts";
+import type { XmppClientInstance, XmppConnectionStatus } from "./xmpp-api.ts";
+import type { XmppConfig, XmppConfigStore } from "./config.ts";
+import type { XmppBridgeRuntime } from "./runtime.ts";
+
+export interface XmppExtensionCommandContext {
+  args: string[];
+  rawArgs: string;
+}
+
+export interface XmppExtensionCommandRegistration {
+  name: string;
+  description: string;
+  handler: (ctx: XmppExtensionCommandContext) => Promise<void>;
+}
+
+const COMMAND_REGISTRY_KEY = "__piXmppCommands__";
+
+/**
+ * Register an extension slash command.
+ */
+export function registerXmppCommand(
+  registration: XmppExtensionCommandRegistration,
+): void {
+  const registry = getCommandRegistry();
+  registry.push(registration);
+}
+
+function getCommandRegistry(): XmppExtensionCommandRegistration[] {
+  const globals = globalThis as Record<string, unknown>;
+  if (!globals[COMMAND_REGISTRY_KEY]) {
+    globals[COMMAND_REGISTRY_KEY] = [];
+  }
+  return globals[COMMAND_REGISTRY_KEY] as XmppExtensionCommandRegistration[];
+}
+
+export function createXmppSlashCommands(deps: {
+  client: XmppClientInstance;
+  configStore: XmppConfigStore;
+  runtime: XmppBridgeRuntime;
+  getConnectionStatus: () => string;
+  sendMessageToActiveTurn: (body: string) => Promise<void>;
+  updateStatus: () => void;
+  getAllowedJid: () => string | undefined;
+}) {
+  return [
+    {
+      name: "xmpp-connect",
+      description:
+        "Connect the XMPP client to your server. Provide --jid, --password, and --service options.",
+      handler: async (ctx: XmppExtensionCommandContext) => {
+        const args = parseArgs(ctx.rawArgs);
+        const jid = args.jid ?? args.J;
+        const password = args.password ?? args.p;
+        const service = args.service ?? args.s;
+        const domain = args.domain ?? args.d;
+
+        if (!jid || !password) {
+          await deps.sendMessageToActiveTurn(
+            "Usage: /xmpp-connect --jid user@domain.tld --password <your_password> [--service xmpp://server.tld] [--domain domain.tld]",
+          );
+          return;
+        }
+
+        const config = deps.configStore.get();
+        config.jid = jid;
+        config.password = password;
+        config.service = service || config.service;
+        config.domain = domain || config.domain;
+        deps.configStore.set(config);
+        await deps.configStore.persist();
+
+        try {
+          await deps.client.connect(config);
+          deps.updateStatus();
+          await deps.sendMessageToActiveTurn(
+            `✅ Connected as ${jid}`,
+          );
+        } catch (error) {
+          await deps.sendMessageToActiveTurn(
+            `❌ Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      },
+    },
+    {
+      name: "xmpp-disconnect",
+      description: "Disconnect the XMPP client.",
+      handler: async () => {
+        await deps.client.disconnect();
+        deps.updateStatus();
+        await deps.sendMessageToActiveTurn("🔌 Disconnected from XMPP server.");
+      },
+    },
+    {
+      name: "xmpp-status",
+      description: "Show XMPP connection status and configuration info.",
+      handler: async () => {
+        const config = deps.configStore.get();
+        const status = deps.client.status;
+        const jid = deps.client.jid;
+        const allowedJid = deps.getAllowedJid();
+
+        const lines = [
+          `**XMPP Bridge Status**`,
+          ``,
+          `**Connection:** ${status}`,
+          `**JID:** ${jid ?? "not connected"}`,
+          `**Configured JID:** ${config.jid ?? "not configured"}`,
+          `**Service:** ${config.service ?? "auto"}`,
+          `**Allowed JID:** ${allowedJid ?? "not paired"}`,
+          `**Auto-reconnect:** ${config.autoReconnect ?? true}`,
+        ];
+
+        if (config.autoJoinRooms?.length) {
+          lines.push(`**Auto-join rooms:** ${config.autoJoinRooms.join(", ")}`);
+        }
+
+        await deps.sendMessageToActiveTurn(lines.join("\n"));
+      },
+    },
+    {
+      name: "xmpp-join",
+      description:
+        "Join a MUC room. Usage: /xmpp-join --room room@conference.tld --nick your_nick",
+      handler: async (ctx: XmppExtensionCommandContext) => {
+        const args = parseArgs(ctx.rawArgs);
+        const room = args.room ?? args.r;
+        const nick = args.nick ?? args.n;
+
+        if (!room) {
+          await deps.sendMessageToActiveTurn(
+            "Usage: /xmpp-join --room room@conference.tld [--nick your_nick]",
+          );
+          return;
+        }
+
+        const nickname = nick ?? deps.client.jid?.split("@")[0] ?? "pi";
+        deps.client.joinRoom(room, nickname);
+
+        const config = deps.configStore.get();
+        const rooms = config.autoJoinRooms ?? [];
+        if (!rooms.includes(room)) {
+          rooms.push(room);
+          config.autoJoinRooms = rooms;
+          deps.configStore.set(config);
+          await deps.configStore.persist();
+        }
+
+        await deps.sendMessageToActiveTurn(
+          `🚪 Joined room ${room} as ${nickname}`,
+        );
+      },
+    },
+    {
+      name: "xmpp-leave",
+      description:
+        "Leave a MUC room. Usage: /xmpp-leave --room room@conference.tld",
+      handler: async (ctx: XmppExtensionCommandContext) => {
+        const args = parseArgs(ctx.rawArgs);
+        const room = args.room ?? args.r;
+
+        if (!room) {
+          await deps.sendMessageToActiveTurn(
+            "Usage: /xmpp-leave --room room@conference.tld",
+          );
+          return;
+        }
+
+        deps.client.leaveRoom(room);
+
+        const config = deps.configStore.get();
+        if (config.autoJoinRooms) {
+          config.autoJoinRooms = config.autoJoinRooms.filter(
+            (r) => r !== room,
+          );
+          deps.configStore.set(config);
+          await deps.configStore.persist();
+        }
+
+        await deps.sendMessageToActiveTurn(`🚪 Left room ${room}`);
+      },
+    },
+    {
+      name: "xmpp-set-presence",
+      description:
+        "Set your presence. Usage: /xmpp-set-presence [--show chat|away|dnd|xa] [--status message]",
+      handler: async (ctx: XmppExtensionCommandContext) => {
+        const args = parseArgs(ctx.rawArgs);
+        const show = args.show ?? args.s;
+        const status = args.status ?? args.m;
+
+        deps.client.sendPresence({
+          show: show || undefined,
+          status: status || undefined,
+        });
+
+        await deps.sendMessageToActiveTurn(
+          `🟢 Presence updated: ${show ?? "available"}${status ? ` (${status})` : ""}`,
+        );
+      },
+    },
+  ];
+}
+
+function parseArgs(raw: string): Record<string, string> {
+  const args: Record<string, string> = {};
+  const tokens = raw.match(/(?:--?\w+(?:=\S+|\s+\S+)?|"[^"]*"|'[^']*'|\S+)/g) ?? [];
+  let i = 0;
+  while (i < tokens.length) {
+    const token = tokens[i];
+    if (token.startsWith("--")) {
+      const eqIdx = token.indexOf("=");
+      if (eqIdx >= 0) {
+        args[token.slice(2, eqIdx)] = token.slice(eqIdx + 1);
+      } else {
+        const key = token.slice(2);
+        const next = tokens[i + 1];
+        if (next && !next.startsWith("-")) {
+          args[key] = next.replace(/^["']|["']$/g, "");
+          i++;
+        } else {
+          args[key] = "true";
+        }
+      }
+    } else if (token.startsWith("-") && token.length === 2) {
+      const key = token.slice(1);
+      const next = tokens[i + 1];
+      if (next && !next.startsWith("-")) {
+        args[key] = next.replace(/^["']|["']$/g, "");
+        i++;
+      } else {
+        args[key] = "true";
+      }
+    }
+    i++;
+  }
+  return args;
+}

package/lib/config.ts

@@ -0,0 +1,221 @@
+/**
+ * XMPP bridge config and pairing helpers
+ * Zones: xmpp config, pairing, filesystem
+ * Owns persisted JID/session pairing state, local config storage, live config controls, and first-user pairing side effects
+ */
+
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+function getAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR
+    ? resolve(process.env.PI_CODING_AGENT_DIR)
+    : join(homedir(), ".pi", "agent");
+}
+
+function getConfigPath(): string {
+  return join(getAgentDir(), "xmpp.json");
+}
+
+export interface XmppTimeConfig {
+  injectionMode?: "hidden" | "always" | "interval";
+  interval?: number;
+}
+
+export interface ResolvedXmppTimeConfig {
+  injectionMode: "hidden" | "always" | "interval";
+  interval: number;
+  timezone: string;
+}
+
+export interface XmppConfig {
+  jid?: string;
+  password?: string;
+  service?: string;
+  domain?: string;
+  resource?: string;
+  allowedJid?: string;
+  autoReconnect?: boolean;
+  autoJoinRooms?: string[];
+  inboundHandlers?: XmppInboundHandlerConfig[];
+  outboundHandlers?: XmppOutboundHandlerConfig[];
+  time?: XmppTimeConfig;
+}
+
+export interface XmppInboundHandlerConfig {
+  match?: string | string[];
+  type?: string | string[];
+  template?: string | string[];
+  args?: string[];
+  defaults?: Record<string, unknown>;
+  timeout?: number | string;
+}
+
+export interface XmppOutboundHandlerConfig {
+  type?: string;
+  match?: string | string[];
+  output?: string;
+  timeout?: number | string;
+}
+
+export interface XmppConfigStore {
+  get: () => XmppConfig;
+  set: (config: XmppConfig) => void;
+  update: (mutate: (config: XmppConfig) => void) => void;
+  getJid: () => string | undefined;
+  hasJid: () => boolean;
+  getAllowedJid: () => string | undefined;
+  getInboundHandlers: () => XmppInboundHandlerConfig[] | undefined;
+  getOutboundHandlers: () => XmppOutboundHandlerConfig[] | undefined;
+  setAllowedJid: (jid: string) => void;
+  load: () => Promise<void>;
+  persist: (config?: XmppConfig) => Promise<void>;
+}
+
+export interface XmppConfigStoreOptions {
+  initialConfig?: XmppConfig;
+  agentDir?: string;
+  configPath?: string;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
+export interface XmppInvalidConfigRecovery {
+  configPath: string;
+  recoveryPath: string;
+  error: unknown;
+}
+
+function isEmptyXmppConfig(config: XmppConfig): boolean {
+  return Object.keys(config).length === 0;
+}
+
+function getInvalidXmppConfigRecoveryPath(configPath: string): string {
+  return `${configPath}.invalid-${process.pid}-${Date.now()}`;
+}
+
+export async function readXmppConfig(
+  configPath: string,
+  options: {
+    onInvalidConfig?: (recovery: XmppInvalidConfigRecovery) => void;
+  } = {},
+): Promise<XmppConfig> {
+  if (!existsSync(configPath)) return {};
+  const content = await readFile(configPath, "utf8");
+  try {
+    return JSON.parse(content) as XmppConfig;
+  } catch (error) {
+    const recoveryPath = getInvalidXmppConfigRecoveryPath(configPath);
+    await rename(configPath, recoveryPath);
+    options.onInvalidConfig?.({ configPath, recoveryPath, error });
+    return {};
+  }
+}
+
+export async function writeXmppConfig(
+  agentDir: string,
+  configPath: string,
+  config: XmppConfig,
+): Promise<void> {
+  await mkdir(agentDir, { recursive: true });
+  const tempConfigPath = `${configPath}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tempConfigPath, JSON.stringify(config, null, "\t") + "\n", {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await chmod(tempConfigPath, 0o600);
+  await rename(tempConfigPath, configPath);
+  await chmod(configPath, 0o600);
+}
+
+export function createXmppConfigStore(
+  options: XmppConfigStoreOptions = {},
+): XmppConfigStore {
+  let config: XmppConfig = options.initialConfig ?? {};
+  const agentDir = options.agentDir ?? getAgentDir();
+  const configPath = options.configPath ?? getConfigPath();
+  return {
+    get: () => config,
+    set: (nextConfig) => {
+      config = nextConfig;
+    },
+    update: (mutate) => {
+      mutate(config);
+    },
+    getJid: () => config.jid,
+    hasJid: () => !!config.jid,
+    getAllowedJid: () => config.allowedJid,
+    getInboundHandlers: () => config.inboundHandlers,
+    getOutboundHandlers: () => config.outboundHandlers,
+    setAllowedJid: (jid) => {
+      config.allowedJid = jid;
+    },
+    load: async () => {
+      config = await readXmppConfig(configPath, {
+        onInvalidConfig: (recovery) => {
+          options.recordRuntimeEvent?.("config", recovery.error, {
+            phase: "load",
+            configPath: recovery.configPath,
+            recoveryPath: recovery.recoveryPath,
+          });
+        },
+      });
+    },
+    persist: async (nextConfig = config) => {
+      await writeXmppConfig(agentDir, configPath, nextConfig);
+    },
+  };
+}
+
+function getSystemTimezone(): string {
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return tz && tz.length > 0 ? tz : "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+export function resolveXmppTimeConfig(
+  raw: XmppTimeConfig | undefined,
+): ResolvedXmppTimeConfig {
+  const injectionMode: "hidden" | "always" | "interval" =
+    raw?.injectionMode === "always" || raw?.injectionMode === "interval"
+      ? raw.injectionMode
+      : "hidden";
+  const interval =
+    typeof raw?.interval === "number" && raw.interval > 0
+      ? raw.interval
+      : 60 * 60 * 1000;
+  const timezone = getSystemTimezone();
+  return { injectionMode, interval, timezone };
+}
+
+export interface XmppAuthorizationState {
+  kind: "pair" | "allow" | "deny";
+  jid?: string;
+}
+
+export function getXmppAuthorizationState(
+  fromJid: string,
+  allowedJid?: string,
+): XmppAuthorizationState {
+  if (allowedJid === undefined) {
+    return { kind: "pair", jid: fromJid };
+  }
+  if (fromJid === allowedJid) {
+    return { kind: "allow" };
+  }
+  return { kind: "deny" };
+}
+
+export function normalizeJid(jid: string): string {
+  // Remove resource part for comparison
+  const idx = jid.indexOf("/");
+  return idx >= 0 ? jid.slice(0, idx) : jid;
+}

package/lib/inbound.ts

@@ -0,0 +1,143 @@
+/**
+ * XMPP inbound handler pipeline
+ * Zones: xmpp inbound, message processing, prompt preparation
+ * Owns stanza dispatch, handler matching, and prompt injection before enqueueing
+ */
+
+import type { XmppConfig, XmppInboundHandlerConfig } from "./config.ts";
+import type { XmppMessageRoute } from "./routing.ts";
+
+const INBOUND_HANDLER_REGISTRY_KEY = "__piXmppInboundHandlers__";
+
+export interface XmppInboundFile {
+  path: string;
+  fileName?: string;
+  mimeType?: string;
+  kind?: string;
+}
+
+export interface XmppInboundHandlerOutput {
+  file: XmppInboundFile;
+  output: string;
+  handler: XmppInboundHandlerConfig;
+}
+
+export interface XmppInboundHandlerProcessResult {
+  rawText: string;
+  handlerOutputs: string[];
+  handled: boolean;
+}
+
+export interface XmppInboundProgrammaticHandlerInput {
+  body: string;
+  from: string;
+  fromBare: string;
+  type: string;
+  isGroup: boolean;
+  roomJid?: string;
+  senderNick?: string;
+  config: XmppConfig;
+}
+
+export interface XmppInboundProgrammaticHandlerResult {
+  handled: boolean;
+  prompt?: string;
+  output?: string;
+}
+
+export interface XmppInboundProgrammaticHandler {
+  (
+    input: XmppInboundProgrammaticHandlerInput,
+  ): XmppInboundProgrammaticHandlerResult | Promise<XmppInboundProgrammaticHandlerResult>;
+}
+
+// Re-export for api surface compatibility
+export type { XmppInboundHandlerConfig };
+
+/**
+ * Register a programmatic inbound handler.
+ * Handlers are called in registration order. The first handler that returns
+ * `{ handled: true }` wins and its prompt replaces the default message prompt.
+ */
+export function registerXmppInboundHandler(
+  handler: XmppInboundProgrammaticHandler,
+): void {
+  const registry = getInboundHandlerRegistry();
+  registry.push(handler);
+}
+
+function getInboundHandlerRegistry(): XmppInboundProgrammaticHandler[] {
+  const globals = globalThis as Record<string, unknown>;
+  if (!globals[INBOUND_HANDLER_REGISTRY_KEY]) {
+    globals[INBOUND_HANDLER_REGISTRY_KEY] = [];
+  }
+  return globals[INBOUND_HANDLER_REGISTRY_KEY] as XmppInboundProgrammaticHandler[];
+}
+
+export function getXmppInboundHandlers(): XmppInboundProgrammaticHandler[] {
+  return getInboundHandlerRegistry();
+}
+
+/**
+ * Process an incoming message through the inbound handler pipeline.
+ * Returns the prompt text and any handler outputs.
+ */
+export async function processXmppInbound(
+  route: XmppMessageRoute,
+  config: XmppConfig,
+): Promise<XmppInboundHandlerProcessResult> {
+  const handlers = getXmppInboundHandlers();
+
+  for (const handler of handlers) {
+    try {
+      const result = await handler({
+        body: route.body,
+        from: route.from,
+        fromBare: route.fromBare,
+        type: route.type,
+        isGroup: route.isGroup,
+        roomJid: route.roomJid,
+        senderNick: route.senderNick,
+        config,
+      });
+
+      if (result.handled) {
+        return {
+          rawText: result.prompt ?? route.body,
+          handlerOutputs: result.output ? [result.output] : [],
+          handled: true,
+        };
+      }
+    } catch (error) {
+      // Handler error, continue to next
+      continue;
+    }
+  }
+
+  // Default handling: use the message body as prompt
+  return {
+    rawText: route.body,
+    handlerOutputs: [],
+    handled: false,
+  };
+}
+
+/**
+ * Check if a message body matches an inbound handler config
+ */
+export function matchesInboundHandler(
+  body: string,
+  handler: XmppInboundHandlerConfig,
+): boolean {
+  if (!handler.match) return true; // Match all if no pattern
+  const patterns = Array.isArray(handler.match) ? handler.match : [handler.match];
+  return patterns.some((pattern) => {
+    if (pattern.startsWith("/") && pattern.endsWith("/")) {
+      // Regex pattern
+      const regex = new RegExp(pattern.slice(1, -1));
+      return regex.test(body);
+    }
+    // Glob/simple match
+    return body.includes(pattern);
+  });
+}

package/lib/lifecycle.ts

@@ -0,0 +1,105 @@
+/**
+ * XMPP lifecycle hook registration helpers
+ * Zones: pi agent lifecycle, xmpp session
+ * Binds prepared XMPP lifecycle runtimes to pi extension lifecycle events
+ */
+
+import type {
+  AgentEndEvent,
+  AgentStartEvent,
+  BeforeAgentStartEvent,
+  ExtensionAPI,
+  ExtensionContext,
+  SessionBeforeCompactEvent,
+  SessionCompactEvent,
+  SessionShutdownEvent,
+  SessionStartEvent,
+} from "./pi.ts";
+
+export interface XmppBeforeAgentStartResult {
+  systemPrompt?: string;
+}
+
+type XmppBeforeAgentStartReturn =
+  | Promise<XmppBeforeAgentStartResult | undefined>
+  | XmppBeforeAgentStartResult
+  | undefined;
+
+export interface XmppLifecycleRegistrationDeps {
+  onSessionStart: (
+    event: SessionStartEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+  onSessionShutdown: (
+    event: SessionShutdownEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+  onSessionBeforeCompact?: (
+    event: SessionBeforeCompactEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void> | void;
+  onSessionCompact?: (
+    event: SessionCompactEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void> | void;
+  onBeforeAgentStart: (
+    event: BeforeAgentStartEvent,
+    ctx: ExtensionContext,
+  ) => XmppBeforeAgentStartReturn;
+  onAgentStart: (
+    event: AgentStartEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+  onAgentEnd: (
+    event: AgentEndEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+}
+
+export interface XmppSessionContextStore<TContext> {
+  get: () => TContext | undefined;
+  set: (ctx: TContext) => void;
+  clear: () => void;
+}
+
+export function createXmppSessionContextStore<
+  TContext,
+>(): XmppSessionContextStore<TContext> {
+  let currentContext: TContext | undefined;
+  return {
+    get: () => currentContext,
+    set: (ctx) => {
+      currentContext = ctx;
+    },
+    clear: () => {
+      currentContext = undefined;
+    },
+  };
+}
+
+export function registerXmppLifecycleHooks(
+  pi: ExtensionAPI,
+  deps: XmppLifecycleRegistrationDeps,
+): void {
+  pi.on("session_start", async (event, ctx) => {
+    await deps.onSessionStart(event, ctx);
+  });
+  pi.on("session_shutdown", async (event, ctx) => {
+    await deps.onSessionShutdown(event, ctx);
+  });
+  pi.on("session_before_compact", async (event, ctx) => {
+    await deps.onSessionBeforeCompact?.(event, ctx);
+  });
+  pi.on("session_compact", async (event, ctx) => {
+    await deps.onSessionCompact?.(event, ctx);
+  });
+  pi.on("before_agent_start", async (event, ctx) => {
+    return deps.onBeforeAgentStart(event, ctx);
+  });
+  pi.on("agent_start", async (event, ctx) => {
+    await deps.onAgentStart(event, ctx);
+  });
+  pi.on("agent_end", async (event, ctx) => {
+    await deps.onAgentEnd(event, ctx);
+  });
+}