pi-xmpp 0.1.0

package/lib/routing.ts

@@ -0,0 +1,196 @@
+/**
+ * XMPP message routing helpers
+ * Zones: xmpp routing, stanza dispatch
+ * Owns stanza type detection, sender extraction, and routing logic for dispatching
+ * incoming stanzas to the correct handler pipeline
+ */
+
+import type { XmppStanza } from "./xmpp-api.ts";
+
+export const XMPP_PREFIX = "[xmpp";
+
+export interface XmppMessageRoute {
+  kind: "message";
+  from: string;
+  fromBare: string;
+  body: string;
+  type: string;
+  thread?: string;
+  subject?: string;
+  isGroup: boolean;
+  roomJid?: string;
+  senderNick?: string;
+}
+
+export interface XmppPresenceRoute {
+  kind: "presence";
+  from: string;
+  type?: string;
+  show?: string;
+  status?: string;
+}
+
+export interface XmppErrorRoute {
+  kind: "error";
+  from?: string;
+  body?: string;
+}
+
+export type XmppRoute = XmppMessageRoute | XmppPresenceRoute | XmppErrorRoute;
+
+/**
+ * Get the bare JID (without resource) from a full JID string
+ */
+export function getBareJid(jid: string): string {
+  const idx = jid.indexOf("/");
+  return idx >= 0 ? jid.slice(0, idx) : jid;
+}
+
+/**
+ * Extract nickname from a MUC occupant JID
+ */
+export function extractMucNick(fullJid: string): string | undefined {
+  const idx = fullJid.indexOf("/");
+  return idx >= 0 ? fullJid.slice(idx + 1) : undefined;
+}
+
+/**
+ * Determine if a bare JID looks like a MUC room
+ */
+export function isRoomJid(bareJid: string): boolean {
+  // MUC rooms typically have a conference subdomain or contain special chars
+  return bareJid.includes("conference") || bareJid.includes("chat.");
+}
+
+/**
+ * Build the XMPP prefix for Pi agent context
+ */
+export function buildXmppPrefix(route: XmppMessageRoute): string {
+  const parts = [`${XMPP_PREFIX}|from:${route.from}`];
+  if (route.isGroup && route.roomJid) {
+    parts.push(`room:${route.roomJid}`);
+    if (route.senderNick) parts.push(`nick:${route.senderNick}`);
+  }
+  return parts.join("|");
+}
+
+/**
+ * Route an incoming stanza
+ */
+export function routeStanza(stanza: XmppStanza): XmppRoute | undefined {
+  if (stanza.name === "message") {
+    return routeMessage(stanza);
+  }
+  if (stanza.name === "presence") {
+    return routePresence(stanza);
+  }
+  return undefined;
+}
+
+function routeMessage(stanza: XmppStanza): XmppMessageRoute | undefined {
+  const from = stanza.attrs.from;
+  const type = stanza.attrs.type ?? "normal";
+  if (!from) return undefined;
+
+  // Skip messages from self
+  const fromBare = getBareJid(from);
+
+  // Find body
+  const bodyChild = stanza.children.find(
+    (c) =>
+      typeof c === "object" && c !== null && (c as XmppStanza).name === "body",
+  ) as XmppStanza | undefined;
+
+  if (!bodyChild) return undefined;
+
+  const bodyText = bodyChild.children.find((c) => typeof c === "string");
+  if (typeof bodyText !== "string") return undefined;
+
+  // Find subject and thread
+  const subjectChild = stanza.children.find(
+    (c) =>
+      typeof c === "object" &&
+      c !== null &&
+      (c as XmppStanza).name === "subject",
+  ) as XmppStanza | undefined;
+
+  const threadChild = stanza.children.find(
+    (c) =>
+      typeof c === "object" &&
+      c !== null &&
+      (c as XmppStanza).name === "thread",
+  ) as XmppStanza | undefined;
+
+  const subject = subjectChild
+    ? (subjectChild.children.find((c) => typeof c === "string") as
+        | string
+        | undefined)
+    : undefined;
+
+  const thread = threadChild
+    ? (threadChild.children.find((c) => typeof c === "string") as
+        | string
+        | undefined)
+    : undefined;
+
+  const isGroup = type === "groupchat";
+  let roomJid: string | undefined;
+  let senderNick: string | undefined;
+
+  if (isGroup) {
+    roomJid = fromBare;
+    senderNick = extractMucNick(from);
+  }
+
+  return {
+    kind: "message",
+    from,
+    fromBare,
+    body: bodyText,
+    type,
+    thread,
+    subject,
+    isGroup,
+    roomJid,
+    senderNick,
+  };
+}
+
+function routePresence(
+  stanza: XmppStanza,
+): XmppPresenceRoute | undefined {
+  const from = stanza.attrs.from;
+  if (!from) return undefined;
+
+  const showChild = stanza.children.find(
+    (c) =>
+      typeof c === "object" && c !== null && (c as XmppStanza).name === "show",
+  ) as XmppStanza | undefined;
+
+  const statusChild = stanza.children.find(
+    (c) =>
+      typeof c === "object" &&
+      c !== null &&
+      (c as XmppStanza).name === "status",
+  ) as XmppStanza | undefined;
+
+  const show = showChild
+    ? (showChild.children.find((c) => typeof c === "string") as
+        | string
+        | undefined)
+    : undefined;
+
+  const status = statusChild
+    ? (statusChild.children.find((c) => typeof c === "string") as
+        | string
+        | undefined)
+    : undefined;
+
+  return {
+    kind: "presence",
+    from,
+    type: stanza.attrs.type,
+    show,
+    status,
+  };
+}

package/lib/runtime.ts

@@ -0,0 +1,148 @@
+/**
+ * XMPP bridge runtime-state helpers
+ * Zones: pi agent runtime state, xmpp session, shared coordination
+ * Owns small session-local runtime primitives shared by orchestration
+ */
+
+const XMPP_TYPING_LABEL_INTERVAL_MS = 2500;
+
+export interface XmppRuntimeQueueCounters {
+  nextQueuedXmppItemOrder: number;
+  nextQueuedXmppControlOrder: number;
+}
+
+export interface XmppRuntimeLifecycleFlags {
+  activeXmppToolExecutions: number;
+  xmppTurnDispatchPending: boolean;
+  compactionInProgress: boolean;
+}
+
+export interface XmppBridgeRuntimeState
+  extends XmppRuntimeQueueCounters, XmppRuntimeLifecycleFlags {
+  abortHandler?: () => void;
+  chatStateInterval?: ReturnType<typeof setInterval>;
+}
+
+export interface XmppRuntimeQueuePort {
+  allocateItemOrder: () => number;
+  allocateControlOrder: () => number;
+}
+
+export interface XmppRuntimeLifecyclePort {
+  getActiveToolExecutions: () => number;
+  setActiveToolExecutions: (count: number) => void;
+  resetActiveToolExecutions: () => void;
+  hasDispatchPending: () => boolean;
+  setDispatchPending: (pending: boolean) => void;
+  clearDispatchPending: () => void;
+  isCompactionInProgress: () => boolean;
+  setCompactionInProgress: (inProgress: boolean) => void;
+}
+
+export interface XmppRuntimeAbortPort {
+  hasHandler: () => boolean;
+  setHandler: (abortHandler: () => void) => void;
+  clearHandler: () => void;
+  getHandler: () => (() => void) | undefined;
+  abortTurn: () => boolean;
+}
+
+export interface XmppBridgeRuntime {
+  state: XmppBridgeRuntimeState;
+  queue: XmppRuntimeQueuePort;
+  lifecycle: XmppRuntimeLifecyclePort;
+  abort: XmppRuntimeAbortPort;
+}
+
+export function createXmppBridgeRuntimeState(): XmppBridgeRuntimeState {
+  return {
+    nextQueuedXmppItemOrder: 0,
+    nextQueuedXmppControlOrder: 0,
+    activeXmppToolExecutions: 0,
+    xmppTurnDispatchPending: false,
+    compactionInProgress: false,
+  };
+}
+
+export function createXmppBridgeRuntime(
+  state = createXmppBridgeRuntimeState(),
+): XmppBridgeRuntime {
+  return {
+    state,
+    queue: {
+      allocateItemOrder: () => state.nextQueuedXmppItemOrder++,
+      allocateControlOrder: () => state.nextQueuedXmppControlOrder++,
+    },
+    lifecycle: {
+      getActiveToolExecutions: () => state.activeXmppToolExecutions,
+      setActiveToolExecutions: (count) => {
+        state.activeXmppToolExecutions = count;
+      },
+      resetActiveToolExecutions: () => {
+        state.activeXmppToolExecutions = 0;
+      },
+      hasDispatchPending: () => state.xmppTurnDispatchPending,
+      setDispatchPending: (pending) => {
+        state.xmppTurnDispatchPending = pending;
+      },
+      clearDispatchPending: () => {
+        state.xmppTurnDispatchPending = false;
+      },
+      isCompactionInProgress: () => state.compactionInProgress,
+      setCompactionInProgress: (inProgress) => {
+        state.compactionInProgress = inProgress;
+      },
+    },
+    abort: {
+      hasHandler: () => typeof state.abortHandler === "function",
+      setHandler: (abortHandler) => {
+        state.abortHandler = abortHandler;
+      },
+      clearHandler: () => {
+        state.abortHandler = undefined;
+      },
+      getHandler: () => state.abortHandler,
+      abortTurn: () => {
+        if (typeof state.abortHandler === "function") {
+          state.abortHandler();
+          state.abortHandler = undefined;
+          return true;
+        }
+        return false;
+      },
+    },
+  };
+}
+
+export function createXmppChatStateSender(
+  sendChatState: (to: string, state: string) => void,
+  getActiveTurnTarget: () => string | undefined,
+) {
+  let interval: ReturnType<typeof setInterval> | undefined;
+
+  return {
+    start: (jid: string) => {
+      sendChatState(jid, "active");
+      interval = setInterval(() => {
+        const target = getActiveTurnTarget();
+        if (target) sendChatState(target, "active");
+      }, XMPP_TYPING_LABEL_INTERVAL_MS);
+    },
+    stop: () => {
+      const target = getActiveTurnTarget();
+      if (target) sendChatState(target, "inactive");
+      if (interval) {
+        clearInterval(interval);
+        interval = undefined;
+      }
+    },
+    pause: () => {
+      const target = getActiveTurnTarget();
+      if (target) sendChatState(target, "paused");
+      if (interval) {
+        clearInterval(interval);
+        interval = undefined;
+      }
+    },
+  };
+}

package/lib/status.ts

@@ -0,0 +1,144 @@
+/**
+ * XMPP bridge status and diagnostics
+ * Zones: xmpp status, diagnostics
+ * Owns runtime event recording, status-line providers, and status rendering
+ */
+
+import type { XmppConfig } from "./config.ts";
+import type { XmppConnectionStatus } from "./xmpp-api.ts";
+
+const STATUS_LINE_PROVIDER_KEY = "__piXmppStatusLineProviders__";
+
+export interface XmppStatusLineProviderContext {
+  config: XmppConfig;
+  connectionStatus: XmppConnectionStatus;
+  connectedJid?: string;
+  allowedJid?: string;
+  activeTurnFrom?: string;
+  queuedCount: number;
+}
+
+export interface XmppStatusLineProviderResult {
+  label: string;
+  value: string;
+  priority?: number;
+}
+
+export interface XmppStatusLineProvider {
+  (
+    ctx: XmppStatusLineProviderContext,
+  ):
+    | XmppStatusLineProviderResult
+    | Promise<XmppStatusLineProviderResult>;
+}
+
+/**
+ * Register a status line provider for extension diagnostics.
+ * Companion extensions can add custom status lines to `/xmpp-status`.
+ */
+export function registerXmppStatusLineProvider(
+  provider: XmppStatusLineProvider,
+): void {
+  const registry = getStatusLineRegistry();
+  registry.push(provider);
+}
+
+function getStatusLineRegistry(): XmppStatusLineProvider[] {
+  const globals = globalThis as Record<string, unknown>;
+  if (!globals[STATUS_LINE_PROVIDER_KEY]) {
+    globals[STATUS_LINE_PROVIDER_KEY] = [];
+  }
+  return globals[STATUS_LINE_PROVIDER_KEY] as XmppStatusLineProvider[];
+}
+
+export interface XmppRuntimeEventEntry {
+  timestamp: number;
+  category: string;
+  error?: string;
+  details?: Record<string, unknown>;
+}
+
+export function createXmppRuntimeEventRecorder(
+  options?: { maxEntries?: number },
+) {
+  const maxEntries = options?.maxEntries ?? 100;
+  const events: XmppRuntimeEventEntry[] = [];
+
+  return {
+    record: (
+      category: string,
+      error: unknown,
+      details?: Record<string, unknown>,
+    ) => {
+      let errorStr: string | undefined;
+      if (error instanceof Error) {
+        errorStr = error.message;
+      } else if (error != null) {
+        errorStr = String(error);
+      }
+      events.push({
+        timestamp: Date.now(),
+        category,
+        error: errorStr,
+        details,
+      });
+      if (events.length > maxEntries) {
+        events.splice(0, events.length - maxEntries);
+      }
+    },
+    getEvents: () => [...events],
+    clear: () => {
+      events.length = 0;
+    },
+  };
+}
+
+export function formatXmppStatusSummary(deps: {
+  config: XmppConfig;
+  connectionStatus: XmppConnectionStatus;
+  connectedJid?: string;
+  allowedJid?: string;
+  activeTurnFrom?: string;
+  queuedCount: number;
+  runtimeEvents: XmppRuntimeEventEntry[];
+  recentErrors?: string[];
+}): string {
+  const lines: string[] = [
+    "## XMPP Bridge Status",
+    "",
+    `**Connection:** ${deps.connectionStatus}`,
+    `**JID:** ${deps.connectedJid ?? "not connected"}`,
+    `**Configured JID:** ${deps.config.jid ?? "not configured"}`,
+    `**Allowed JID:** ${deps.allowedJid ?? "not paired"}`,
+    `**Active turn:** ${deps.activeTurnFrom ?? "none"}`,
+    `**Queued messages:** ${deps.queuedCount}`,
+    `**Service:** ${deps.config.service ?? "auto"}`,
+    `**Domain:** ${deps.config.domain ?? "auto"}`,
+  ];
+
+  if (deps.config.autoJoinRooms?.length) {
+    lines.push(`**Auto-join rooms:** ${deps.config.autoJoinRooms.join(", ")}`);
+  }
+
+  if (deps.recentErrors?.length) {
+    lines.push("");
+    lines.push("### Recent Errors");
+    for (const err of deps.recentErrors) {
+      lines.push(`- ${err}`);
+    }
+  }
+
+  if (deps.runtimeEvents.length > 0) {
+    lines.push("");
+    lines.push("### Runtime Events");
+    const recent = deps.runtimeEvents.slice(-10);
+    for (const event of recent) {
+      const time = new Date(event.timestamp).toISOString();
+      lines.push(
+        `- [${time}] ${event.category}: ${event.error ?? "ok"}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}