pi-xmpp 0.1.0

package/lib/model.ts

@@ -0,0 +1,96 @@
+/**
+ * XMPP model and thinking level helpers
+ * Zones: pi agent model control, xmpp controls
+ * Owns model identity, thinking levels, and current-model state
+ */
+
+import type { ExtensionContext } from "./pi.ts";
+
+export interface MenuModel {
+  provider: string;
+  id: string;
+  name?: string;
+  reasoning?: boolean;
+}
+
+export type ThinkingLevel =
+  | "off"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+
+export interface ScopedXmppModel<TModel extends MenuModel = MenuModel> {
+  model: TModel;
+  thinkingLevel?: ThinkingLevel;
+}
+
+export const THINKING_LEVELS: readonly ThinkingLevel[] = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+];
+
+export interface CurrentModelStore<
+  TContext,
+  TModel extends MenuModel = MenuModel,
+> {
+  get: (ctx: TContext) => TModel | undefined;
+  getStored: () => TModel | undefined;
+  set: (model: TModel | undefined) => void;
+}
+
+export interface CurrentModelUpdateRuntime<
+  TContext,
+  TModel extends MenuModel = MenuModel,
+> {
+  setCurrentModel: (model: TModel | undefined, ctx: TContext) => void;
+  onModelSelect: (event: { model: TModel | undefined }, ctx: TContext) => void;
+}
+
+export type CurrentModelRuntime<
+  TContext,
+  TModel extends MenuModel = MenuModel,
+> = CurrentModelStore<TContext, TModel> &
+  CurrentModelUpdateRuntime<TContext, TModel>;
+
+export function createCurrentModelStore<
+  TContext,
+  TModel extends MenuModel = MenuModel,
+>(
+  getContextModel: (ctx: TContext) => TModel | undefined,
+): CurrentModelStore<TContext, TModel> {
+  let currentModel: TModel | undefined;
+  return {
+    get: (ctx) => currentModel ?? getContextModel(ctx),
+    getStored: () => currentModel,
+    set: (model) => {
+      currentModel = model;
+    },
+  };
+}
+
+export function createCurrentModelUpdateRuntime<
+  TContext extends ExtensionContext,
+  TModel extends MenuModel = MenuModel,
+>(
+  deps: CurrentModelStore<TContext, TModel> & {
+    setModel: (model: TModel | undefined) => void;
+  },
+): CurrentModelUpdateRuntime<TContext, TModel> {
+  return {
+    setCurrentModel(model, ctx) {
+      deps.set(model);
+      if (model) {
+        deps.setModel(model as Parameters<typeof deps.setModel>[0]);
+      }
+    },
+    onModelSelect(event, ctx) {
+      deps.set(event.model);
+    },
+  };
+}

package/lib/outbound.ts

@@ -0,0 +1,138 @@
+/**
+ * XMPP outbound surface helpers
+ * Zones: xmpp outbound, message delivery
+ * Owns configured outbound handler execution, text transforms, and direct message sending
+ */
+
+import type { XmppClientInstance } from "./xmpp-api.ts";
+import { getBareJid } from "./routing.ts";
+
+const OUTBOUND_HANDLER_REGISTRY_KEY = "__piXmppOutboundHandlers__";
+
+export interface XmppOutboundProgrammaticHandlerInput {
+  body: string;
+  to: string;
+  toBare: string;
+  type: string;
+  isGroup: boolean;
+}
+
+export interface XmppOutboundProgrammaticHandlerResult {
+  handled: boolean;
+  body?: string;
+}
+
+export interface XmppOutboundProgrammaticHandler {
+  (
+    input: XmppOutboundProgrammaticHandlerInput,
+  ):
+    | XmppOutboundProgrammaticHandlerResult
+    | Promise<XmppOutboundProgrammaticHandlerResult>;
+}
+
+/**
+ * Register a programmatic outbound handler.
+ * Handlers can transform or intercept outgoing messages.
+ */
+export function registerXmppOutboundHandler(
+  handler: XmppOutboundProgrammaticHandler,
+): void {
+  const registry = getOutboundHandlerRegistry();
+  registry.push(handler);
+}
+
+function getOutboundHandlerRegistry(): XmppOutboundProgrammaticHandler[] {
+  const globals = globalThis as Record<string, unknown>;
+  if (!globals[OUTBOUND_HANDLER_REGISTRY_KEY]) {
+    globals[OUTBOUND_HANDLER_REGISTRY_KEY] = [];
+  }
+  return globals[OUTBOUND_HANDLER_REGISTRY_KEY] as XmppOutboundProgrammaticHandler[];
+}
+
+export function getXmppOutboundHandlers(): XmppOutboundProgrammaticHandler[] {
+  return getOutboundHandlerRegistry();
+}
+
+export interface XmppSendMessageOptions {
+  type?: string;
+  subject?: string;
+  thread?: string;
+}
+
+/**
+ * Send a message via the XMPP client.
+ * Runs through the outbound handler pipeline before sending.
+ */
+export async function sendXmppMessage(
+  client: XmppClientInstance,
+  to: string,
+  body: string,
+  options?: XmppSendMessageOptions,
+): Promise<void> {
+  const toBare = getBareJid(to);
+  const isGroup = options?.type === "groupchat";
+  let finalBody = body;
+  let handled = false;
+
+  // Run through outbound handler pipeline
+  const handlers = getXmppOutboundHandlers();
+  for (const handler of handlers) {
+    try {
+      const result = await handler({
+        body: finalBody,
+        to,
+        toBare,
+        type: options?.type ?? "chat",
+        isGroup,
+      });
+      if (result.handled) {
+        handled = true;
+        if (result.body !== undefined) {
+          finalBody = result.body;
+        }
+        break;
+      }
+    } catch {
+      // Silently continue
+    }
+  }
+
+  if (!handled) {
+    await client.sendMessage(to, finalBody, {
+      type: options?.type,
+      subject: options?.subject,
+      thread: options?.thread,
+    });
+  }
+}
+
+/**
+ * Record a runtime event for diagnostics.
+ * Companion extensions can call this to surface diagnostics.
+ */
+export type XmppRuntimeEventRecorder = (
+  category: string,
+  error: unknown,
+  details?: Record<string, unknown>,
+) => void;
+
+const EVENT_RECORDER_KEY = "__piXmppEventRecorder__";
+
+export function bindXmppRuntimeEventRecorder(
+  recorder: XmppRuntimeEventRecorder,
+): void {
+  (globalThis as Record<string, unknown>)[EVENT_RECORDER_KEY] = recorder;
+}
+
+export function recordXmppRuntimeEvent(
+  category: string,
+  error: unknown,
+  details?: Record<string, unknown>,
+): void {
+  const recorder = (globalThis as Record<string, unknown>)[
+    EVENT_RECORDER_KEY
+  ] as XmppRuntimeEventRecorder | undefined;
+  if (typeof recorder === "function") {
+    recorder(category, error, details);
+  }
+}

package/lib/pi.ts

@@ -0,0 +1,165 @@
+/**
+ * Pi SDK adapter boundary
+ * Zones: pi agent sdk boundary, shared adapters
+ * Owns direct pi SDK imports and exposes narrow bridge-facing helpers/types for the extension composition layer
+ */
+
+import {
+  type AgentEndEvent,
+  type AgentStartEvent,
+  type BeforeAgentStartEvent,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+  type ExtensionContext,
+  type SessionBeforeCompactEvent,
+  type SessionCompactEvent,
+  type SessionShutdownEvent,
+  type SessionStartEvent,
+  type SlashCommandInfo,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+export type {
+  AgentEndEvent,
+  AgentStartEvent,
+  BeforeAgentStartEvent,
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  SessionBeforeCompactEvent,
+  SessionCompactEvent,
+  SessionShutdownEvent,
+  SessionStartEvent,
+  SlashCommandInfo,
+};
+
+export interface ToolExecutionStartEvent {
+  type: "tool_execution_start";
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+}
+
+export interface ToolExecutionUpdateEvent {
+  type: "tool_execution_update";
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+  partialResult: unknown;
+}
+
+export interface ToolExecutionEndEvent {
+  type: "tool_execution_end";
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+  isError: boolean;
+}
+
+export interface PiSettingsManager {
+  reload: () => Promise<void>;
+  flush: () => Promise<void>;
+  getEnabledModels: () => string[] | undefined;
+  setEnabledModels: (patterns: string[] | undefined) => void;
+}
+
+export type PiSlashCommandInfo = SlashCommandInfo;
+export type PiRunMode = "tui" | "rpc" | "json" | "print";
+
+function isPiRunMode(value: unknown): value is PiRunMode {
+  return (
+    value === "tui" ||
+    value === "rpc" ||
+    value === "json" ||
+    value === "print"
+  );
+}
+
+export function getExtensionContextMode(ctx: unknown): PiRunMode | undefined {
+  const mode =
+    typeof ctx === "object" && ctx !== null
+      ? (ctx as { mode?: unknown }).mode
+      : undefined;
+  return isPiRunMode(mode) ? mode : undefined;
+}
+
+export function isExtensionContextPassiveRunMode(ctx: unknown): boolean {
+  const mode = getExtensionContextMode(ctx);
+  return mode === "print" || mode === "json";
+}
+
+export function canStartPollingInExtensionContext(ctx: unknown): boolean {
+  return !isExtensionContextPassiveRunMode(ctx);
+}
+
+export function formatPollingStartBlockedByRunMode(ctx: unknown): string {
+  const mode = getExtensionContextMode(ctx);
+  return mode
+    ? `XMPP connection is unavailable in Pi ${mode} mode. Use /xmpp-connect from a long-lived Pi session.`
+    : "XMPP connection is unavailable in this Pi run mode.";
+}
+
+export type PiSendUserMessageOptions = NonNullable<
+  Parameters<ExtensionAPI["sendUserMessage"]>[1]
+>;
+
+export interface PiExtensionApiRuntimePorts {
+  sendUserMessage: ExtensionAPI["sendUserMessage"];
+  exec: ExtensionAPI["exec"];
+  getCommands: ExtensionAPI["getCommands"];
+  getThinkingLevel: ExtensionAPI["getThinkingLevel"];
+  setThinkingLevel: ExtensionAPI["setThinkingLevel"];
+  setModel: ExtensionAPI["setModel"];
+}
+
+export function createExtensionApiRuntimePorts(
+  api: Pick<
+    ExtensionAPI,
+    | "sendUserMessage"
+    | "exec"
+    | "getCommands"
+    | "getThinkingLevel"
+    | "setThinkingLevel"
+    | "setModel"
+  >,
+): PiExtensionApiRuntimePorts {
+  return {
+    sendUserMessage: (content, options) => api.sendUserMessage(content, options),
+    exec: (command, args, options) => api.exec(command, args, options),
+    getCommands: () => api.getCommands(),
+    getThinkingLevel: () => api.getThinkingLevel(),
+    setThinkingLevel: (level) => api.setThinkingLevel(level),
+    setModel: (model) => api.setModel(model),
+  };
+}
+
+export function createSettingsManager(cwd: string): PiSettingsManager {
+  return SettingsManager.create(cwd);
+}
+
+export function getExtensionContextModel(
+  ctx: ExtensionContext,
+): ExtensionContext["model"] {
+  return ctx.model;
+}
+
+export function getExtensionContextCwd(ctx: ExtensionContext): string {
+  return ctx.cwd;
+}
+
+export function isExtensionContextIdle(ctx: ExtensionContext): boolean {
+  return ctx.isIdle();
+}
+
+export function hasExtensionContextPendingMessages(
+  ctx: ExtensionContext,
+): boolean {
+  return ctx.hasPendingMessages();
+}
+
+export function compactExtensionContext(
+  ctx: ExtensionContext,
+  callbacks: Parameters<ExtensionContext["compact"]>[0],
+): ReturnType<ExtensionContext["compact"]> {
+  return ctx.compact(callbacks);
+}

package/lib/prompts.ts

@@ -0,0 +1,95 @@
+/**
+ * XMPP prompt injection helpers
+ * Zones: pi agent prompts, xmpp guidance
+ * Owns XMPP-specific system prompt suffixes injected into pi agent turns
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { BeforeAgentStartEvent, ExtensionAPI } from "./pi.ts";
+import { XMPP_PREFIX } from "./routing.ts";
+
+const LOCAL_SYSTEM_PROMPT_SUFFIX = `
+
+XMPP bridge available. Do not use it from local/TUI prompts unless explicitly asked.`;
+
+const XMPP_TURN_SYSTEM_PROMPT_SUFFIX = `
+
+XMPP turn note: If context was compacted or you need the pi-xmpp bridge contract, call tool \`xmpp_help\`.`;
+
+const XMPP_HELP_TEXT = `--- XMPP BRIDGE HELP ---
+
+How to understand XMPP turns:
+- \`[xmpp|from:user@domain]\` marks XMPP origin and sender.
+- \`[room:room@conference]\` indicates a groupchat (MUC) message.
+- \`[nick:nickname]\` is the sender's nickname in a MUC room.
+- Reply to the user's current instruction, not quoted context.
+
+How to answer XMPP turns:
+- Reply in concise, scannable text.
+- For generated/requested files, mention the local path.
+
+Assistant-authored XMPP actions:
+- Use the \`xmpp_send\` tool to send direct messages or groupchat replies.
+
+Debugging pi-xmpp:
+- Inspect \`~/.pi/agent/tmp/xmpp/state.json\` for runtime state and diagnostics.
+- Use \`/xmpp-status\` for compact health information.`;
+
+export function getXmppHelpText(): string {
+  return XMPP_HELP_TEXT;
+}
+
+export function registerXmppHelpTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "xmpp_help",
+    label: "XMPP Help",
+    description:
+      "Read pi-xmpp usage guidance for delivery actions, formatting, and debugging.",
+    parameters: Type.Object({}),
+    async execute() {
+      return {
+        content: [{ type: "text", text: getXmppHelpText() }],
+        details: {},
+      };
+    },
+  });
+}
+
+export function buildXmppBridgeSystemPrompt(options: {
+  prompt: string;
+  systemPrompt: string;
+  xmppPrefix?: string;
+  localSystemPromptSuffix: string;
+  xmppTurnSystemPromptSuffix: string;
+}): { systemPrompt: string } {
+  const xmppPrefix = options.xmppPrefix ?? XMPP_PREFIX;
+  const trimmedPrompt = options.prompt.trimStart();
+  const isXmppTurn = trimmedPrompt.startsWith(xmppPrefix);
+
+  const suffix = isXmppTurn
+    ? `${options.xmppTurnSystemPromptSuffix}\n- The current user message came from XMPP.`
+    : options.localSystemPromptSuffix;
+
+  return {
+    systemPrompt: options.systemPrompt + suffix,
+  };
+}
+
+export function createXmppBeforeAgentStartHook(
+  options: {
+    xmppPrefix?: string;
+    localSystemPromptSuffix?: string;
+    xmppTurnSystemPromptSuffix?: string;
+  } = {},
+): (event: BeforeAgentStartEvent) => { systemPrompt: string } {
+  return (event) =>
+    buildXmppBridgeSystemPrompt({
+      prompt: event.prompt,
+      systemPrompt: event.systemPrompt,
+      xmppPrefix: options.xmppPrefix,
+      localSystemPromptSuffix:
+        options.localSystemPromptSuffix ?? LOCAL_SYSTEM_PROMPT_SUFFIX,
+      xmppTurnSystemPromptSuffix:
+        options.xmppTurnSystemPromptSuffix ?? XMPP_TURN_SYSTEM_PROMPT_SUFFIX,
+    });
+}

package/lib/queue.ts

@@ -0,0 +1,129 @@
+/**
+ * XMPP message queue and turn management
+ * Zones: xmpp queue, turn lifecycle, prompt injection
+ * Owns incoming message queuing, turn tracking, and deferred prompt dispatch
+ */
+
+import type { ExtensionContext } from "./pi.ts";
+import type { XmppMessageRoute } from "./routing.ts";
+
+export interface XmppTurnContext {
+  from: string;
+  fromBare: string;
+  body: string;
+  type: string;
+  thread?: string;
+  subject?: string;
+  isGroup: boolean;
+  roomJid?: string;
+  senderNick?: string;
+  timestamp: number;
+}
+
+export interface XmppQueueItem<TContext> {
+  id: string;
+  order: number;
+  turn: XmppTurnContext;
+  prompt: string;
+  ctx: TContext;
+  status: "queued" | "dispatching" | "active" | "done";
+}
+
+export interface XmppActiveTurnStore {
+  has: () => boolean;
+  get: () => XmppTurnContext | undefined;
+  getChatId: () => string | undefined;
+  set: (turn: XmppTurnContext | undefined) => void;
+  clear: () => void;
+}
+
+export function createXmppActiveTurnStore(): XmppActiveTurnStore {
+  let current: XmppTurnContext | undefined;
+  return {
+    has: () => current !== undefined,
+    get: () => current,
+    getChatId: () => current?.fromBare,
+    set: (turn) => {
+      current = turn;
+    },
+    clear: () => {
+      current = undefined;
+    },
+  };
+}
+
+export interface XmppQueueStore<TContext> {
+  enqueue: (item: XmppQueueItem<TContext>) => void;
+  dequeue: () => XmppQueueItem<TContext> | undefined;
+  peek: () => XmppQueueItem<TContext> | undefined;
+  getQueuedItems: () => XmppQueueItem<TContext>[];
+  remove: (id: string) => void;
+  clear: () => void;
+  size: () => number;
+}
+
+export function createXmppQueueStore<TContext>(): XmppQueueStore<TContext> {
+  const items: XmppQueueItem<TContext>[] = [];
+  return {
+    enqueue: (item) => {
+      items.push(item);
+      items.sort((a, b) => a.order - b.order);
+    },
+    dequeue: () => items.shift(),
+    peek: () => items[0],
+    getQueuedItems: () => [...items],
+    remove: (id) => {
+      const idx = items.findIndex((i) => i.id === id);
+      if (idx >= 0) items.splice(idx, 1);
+    },
+    clear: () => {
+      items.length = 0;
+    },
+    size: () => items.length,
+  };
+}
+
+export function formatQueuedXmppItemsStatus<TContext>(
+  items: XmppQueueItem<TContext>[],
+): string {
+  if (items.length === 0) return "0 queued";
+  return items
+    .map(
+      (i) =>
+        `${i.status}: from=${i.turn.fromBare} body="${i.turn.body.slice(0, 40)}"`,
+    )
+    .join("; ");
+}
+
+export function buildXmppTurnPrompt(
+  turn: XmppTurnContext,
+  options?: {
+    includeThread?: boolean;
+    extraContext?: string;
+  },
+): string {
+  const parts: string[] = [];
+  parts.push(`[xmpp|from:${turn.from}]`);
+
+  if (turn.isGroup && turn.roomJid) {
+    parts.push(`[room:${turn.roomJid}]`);
+    if (turn.senderNick) parts.push(`[nick:${turn.senderNick}]`);
+  }
+
+  if (turn.subject) {
+    parts.push(`[subject:${turn.subject}]`);
+  }
+
+  if (options?.includeThread && turn.thread) {
+    parts.push(`[thread:${turn.thread}]`);
+  }
+
+  if (options?.extraContext) {
+    parts.push(`[context:${options.extraContext}]`);
+  }
+
+  parts.push("");
+  parts.push(turn.body);
+
+  return parts.join("\n");
+}