@betrue/openclaw-claude-code-plugin 1.0.0

package/src/commands/claude.ts

@@ -0,0 +1,61 @@
+import { sessionManager, pluginConfig, resolveOriginChannel } from "../shared";
+
+export function registerClaudeCommand(api: any): void {
+  api.registerCommand({
+    name: "claude",
+    description: "Launch a Claude Code session. Usage: /claude [--name <name>] <prompt>",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: (ctx: any) => {
+      if (!sessionManager) {
+        return {
+          text: "Error: SessionManager not initialized. The claude-code service must be running.",
+        };
+      }
+
+      let args = (ctx.args ?? "").trim();
+      if (!args) {
+        return { text: "Usage: /claude [--name <name>] <prompt>" };
+      }
+
+      // Parse optional --name flag
+      let name: string | undefined;
+      const nameMatch = args.match(/^--name\s+(\S+)\s+/);
+      if (nameMatch) {
+        name = nameMatch[1];
+        args = args.slice(nameMatch[0].length).trim();
+      }
+
+      const prompt = args;
+      if (!prompt) {
+        return { text: "Usage: /claude [--name <name>] <prompt>" };
+      }
+
+      try {
+        const session = sessionManager.spawn({
+          prompt,
+          name,
+          workdir: pluginConfig.defaultWorkdir || process.cwd(),
+          model: pluginConfig.defaultModel,
+          maxBudgetUsd: pluginConfig.defaultBudgetUsd ?? 5,
+          originChannel: resolveOriginChannel(ctx),
+        });
+
+        const promptSummary =
+          prompt.length > 80 ? prompt.slice(0, 80) + "..." : prompt;
+
+        return {
+          text: [
+            `Session launched.`,
+            `  Name: ${session.name}`,
+            `  ID: ${session.id}`,
+            `  Prompt: "${promptSummary}"`,
+            `  Status: ${session.status}`,
+          ].join("\n"),
+        };
+      } catch (err: any) {
+        return { text: `Error: ${err.message}` };
+      }
+    },
+  });
+}

package/src/gateway.ts

@@ -0,0 +1,185 @@
+import { sessionManager, pluginConfig, formatSessionListing, formatDuration, formatStats, resolveOriginChannel } from "./shared";
+
+/**
+ * Task 17 — Gateway RPC methods
+ *
+ * Registers RPC methods so external clients (dashboard, API, other plugins)
+ * can control Claude Code Plugin sessions programmatically.
+ *
+ * Methods:
+ *   claude-code.sessions — list sessions (optionally filtered by status)
+ *   claude-code.launch   — launch a new session
+ *   claude-code.kill     — kill a running session
+ *   claude-code.output   — get output from a session
+ *   claude-code.stats    — return aggregated metrics
+ */
+export function registerGatewayMethods(api: any): void {
+
+  // ── claude-code.sessions ────────────────────────────────────────
+  api.registerGatewayMethod("claude-code.sessions", ({ respond, params }: any) => {
+    if (!sessionManager) {
+      return respond(false, { error: "SessionManager not initialized" });
+    }
+
+    const filter = params?.status ?? "all";
+    const sessions = sessionManager.list(filter);
+
+    const result = sessions.map((s) => ({
+      id: s.id,
+      name: s.name,
+      status: s.status,
+      prompt: s.prompt,
+      workdir: s.workdir,
+      model: s.model,
+      costUsd: s.costUsd,
+      startedAt: s.startedAt,
+      completedAt: s.completedAt,
+      durationMs: s.duration,
+      claudeSessionId: s.claudeSessionId,
+      foreground: s.foregroundChannels.size > 0,
+      multiTurn: s.multiTurn,
+      // Also include human-readable listing
+      display: formatSessionListing(s),
+    }));
+
+    respond(true, { sessions: result, count: result.length });
+  });
+
+  // ── claude-code.launch ──────────────────────────────────────────
+  api.registerGatewayMethod("claude-code.launch", ({ respond, params }: any) => {
+    if (!sessionManager) {
+      return respond(false, { error: "SessionManager not initialized" });
+    }
+
+    if (!params?.prompt) {
+      return respond(false, { error: "Missing required parameter: prompt" });
+    }
+
+    try {
+      const session = sessionManager.spawn({
+        prompt: params.prompt,
+        name: params.name,
+        workdir: params.workdir || pluginConfig.defaultWorkdir || process.cwd(),
+        model: params.model || pluginConfig.defaultModel,
+        maxBudgetUsd: params.maxBudgetUsd ?? params.max_budget_usd ?? pluginConfig.defaultBudgetUsd ?? 5,
+        systemPrompt: params.systemPrompt ?? params.system_prompt,
+        allowedTools: params.allowedTools ?? params.allowed_tools,
+        resumeSessionId: params.resumeSessionId ?? params.resume_session_id,
+        forkSession: params.forkSession ?? params.fork_session,
+        multiTurn: params.multiTurn ?? params.multi_turn,
+        originChannel: params.originChannel ?? "gateway",
+      });
+
+      respond(true, {
+        id: session.id,
+        name: session.name,
+        status: session.status,
+        workdir: session.workdir,
+        model: session.model,
+      });
+    } catch (err: any) {
+      respond(false, { error: err.message });
+    }
+  });
+
+  // ── claude-code.kill ────────────────────────────────────────────
+  api.registerGatewayMethod("claude-code.kill", ({ respond, params }: any) => {
+    if (!sessionManager) {
+      return respond(false, { error: "SessionManager not initialized" });
+    }
+
+    const ref = params?.session ?? params?.id;
+    if (!ref) {
+      return respond(false, { error: "Missing required parameter: session (name or ID)" });
+    }
+
+    const session = sessionManager.resolve(ref);
+    if (!session) {
+      return respond(false, { error: `Session "${ref}" not found` });
+    }
+
+    if (session.status === "completed" || session.status === "failed" || session.status === "killed") {
+      return respond(true, {
+        id: session.id,
+        name: session.name,
+        status: session.status,
+        message: `Session already ${session.status}`,
+      });
+    }
+
+    sessionManager.kill(session.id);
+
+    respond(true, {
+      id: session.id,
+      name: session.name,
+      status: "killed",
+      message: `Session ${session.name} [${session.id}] terminated`,
+    });
+  });
+
+  // ── claude-code.output ──────────────────────────────────────────
+  api.registerGatewayMethod("claude-code.output", ({ respond, params }: any) => {
+    if (!sessionManager) {
+      return respond(false, { error: "SessionManager not initialized" });
+    }
+
+    const ref = params?.session ?? params?.id;
+    if (!ref) {
+      return respond(false, { error: "Missing required parameter: session (name or ID)" });
+    }
+
+    const session = sessionManager.resolve(ref);
+    if (!session) {
+      return respond(false, { error: `Session "${ref}" not found` });
+    }
+
+    const lines = params?.full
+      ? session.getOutput()
+      : session.getOutput(params?.lines ?? 50);
+
+    respond(true, {
+      id: session.id,
+      name: session.name,
+      status: session.status,
+      costUsd: session.costUsd,
+      durationMs: session.duration,
+      duration: formatDuration(session.duration),
+      lines,
+      lineCount: lines.length,
+      result: session.result ?? null,
+    });
+  });
+
+  // ── claude-code.stats ───────────────────────────────────────────
+  api.registerGatewayMethod("claude-code.stats", ({ respond, params }: any) => {
+    if (!sessionManager) {
+      return respond(false, { error: "SessionManager not initialized" });
+    }
+
+    const metrics = sessionManager.getMetrics();
+
+    // Build a serializable version (Map → Object)
+    const costPerDay: Record<string, number> = {};
+    for (const [key, val] of metrics.costPerDay) {
+      costPerDay[key] = val;
+    }
+
+    const running = sessionManager.list("running").length;
+
+    respond(true, {
+      totalCostUsd: metrics.totalCostUsd,
+      costPerDay,
+      sessionsByStatus: {
+        ...metrics.sessionsByStatus,
+        running,
+      },
+      totalLaunched: metrics.totalLaunched,
+      averageDurationMs: metrics.sessionsWithDuration > 0
+        ? metrics.totalDurationMs / metrics.sessionsWithDuration
+        : 0,
+      mostExpensive: metrics.mostExpensive,
+      // Human-readable version too
+      display: formatStats(metrics),
+    });
+  });
+}

package/src/notifications.ts

@@ -0,0 +1,405 @@
+import type { Session } from "./session";
+import { formatDuration } from "./shared";
+
+/**
+ * NotificationRouter — Phase 2
+ *
+ * Decides when and what to notify on active channels.
+ * Implements the notification matrix from the plan (section 7.2):
+ *
+ * | Event                      | Background       | Foreground        |
+ * |----------------------------|------------------|-------------------|
+ * | Session started            | silent           | silent (stream)   |
+ * | Assistant output (text)    | silent           | stream to chat    |
+ * | Tool call (name + params)  | silent           | compact indicator |
+ * | Tool result                | silent           | silent (verbose)  |
+ * | Session completed (success)| notify           | notify            |
+ * | Session completed (error)  | notify           | notify            |
+ * | Budget exhausted           | notify           | notify            |
+ * | Session > 10min            | reminder (once)  | silent (user sees)|
+ */
+
+// Callback type: the plugin must provide a way to send messages to a channel
+export type SendMessageFn = (channelId: string, text: string) => void;
+
+// Debounce state per channel per session
+interface DebounceEntry {
+  buffer: string;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const DEBOUNCE_MS = 500;
+const LONG_RUNNING_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
+
+export class NotificationRouter {
+  private sendMessage: SendMessageFn;
+
+  // Track debounced foreground streaming: key = `${sessionId}|${channelId}`
+  private debounceMap: Map<string, DebounceEntry> = new Map();
+
+  // Track which sessions have already sent the 10min reminder
+  private longRunningReminded: Set<string> = new Set();
+
+  // Interval for checking long-running sessions
+  private reminderInterval: ReturnType<typeof setInterval> | null = null;
+
+  // Reference to get all sessions for reminder checks
+  private getActiveSessions: (() => Session[]) | null = null;
+
+  constructor(sendMessage: SendMessageFn) {
+    this.sendMessage = (channelId: string, text: string) => {
+      console.log(`[NotificationRouter] sendMessage -> channel=${channelId}, textLen=${text.length}, preview=${text.slice(0, 120)}`);
+      sendMessage(channelId, text);
+    };
+    console.log("[NotificationRouter] Initialized");
+  }
+
+  /**
+   * Start the reminder check interval.
+   * Pass a function that returns currently active sessions.
+   */
+  startReminderCheck(getActiveSessions: () => Session[]): void {
+    this.getActiveSessions = getActiveSessions;
+    // Check every 60 seconds for long-running sessions
+    this.reminderInterval = setInterval(() => this.checkLongRunning(), 60_000);
+  }
+
+  /**
+   * Stop the reminder check interval and flush all debounce timers.
+   */
+  stop(): void {
+    if (this.reminderInterval) {
+      clearInterval(this.reminderInterval);
+      this.reminderInterval = null;
+    }
+    // Flush all pending debounce buffers
+    for (const [key, entry] of this.debounceMap) {
+      clearTimeout(entry.timer);
+      if (entry.buffer) {
+        const [_sessionId, channelId] = key.split("|", 2);
+        this.sendMessage(channelId, entry.buffer);
+      }
+    }
+    this.debounceMap.clear();
+    this.longRunningReminded.clear();
+  }
+
+  // ─── Foreground streaming ──────────────────────────────────────────
+
+  /**
+   * Called when an assistant text block arrives on a session.
+   * If the session has foreground channels, debounce and stream to them.
+   */
+  onAssistantText(session: Session, text: string): void {
+    console.log(`[NotificationRouter] onAssistantText session=${session.id} (${session.name}), fgChannels=${JSON.stringify([...session.foregroundChannels])}, textLen=${text.length}`);
+    if (session.foregroundChannels.size === 0) {
+      console.log(`[NotificationRouter] onAssistantText SKIPPED — no foreground channels`);
+      return;
+    }
+
+    for (const channelId of session.foregroundChannels) {
+      console.log(`[NotificationRouter] appendDebounced -> session=${session.id}, channel=${channelId}`);
+      this.appendDebounced(session.id, channelId, text);
+    }
+  }
+
+  /**
+   * Called when a tool_use block arrives on an assistant message.
+   * Shows a compact one-line indicator on foreground channels.
+   */
+  onToolUse(session: Session, toolName: string, toolInput: any): void {
+    console.log(`[NotificationRouter] onToolUse session=${session.id}, tool=${toolName}, fgChannels=${JSON.stringify([...session.foregroundChannels])}`);
+    if (session.foregroundChannels.size === 0) return;
+
+    const inputSummary = summarizeToolInput(toolInput);
+    const line = `🔧 ${toolName}${inputSummary ? ` — ${inputSummary}` : ""}`;
+
+    for (const channelId of session.foregroundChannels) {
+      // Flush any pending text first, then send tool indicator immediately
+      this.flushDebounced(session.id, channelId);
+      this.sendMessage(channelId, line);
+    }
+  }
+
+  // ─── Completion notifications ──────────────────────────────────────
+
+  /**
+   * Called when a session completes (success or failure).
+   * Notifies ALL channels that have ever been associated with this session:
+   * - Foreground channels get a notification
+   * - If no foreground channels, notify via a "last known" channel if available
+   *
+   * For background sessions, we store the originating channel in session metadata.
+   */
+  onSessionComplete(session: Session, originChannel?: string): void {
+    console.log(`[NotificationRouter] onSessionComplete session=${session.id} (${session.name}), status=${session.status}, originChannel=${originChannel}, fgChannels=${JSON.stringify([...session.foregroundChannels])}`);
+    // Flush any pending foreground output first
+    for (const channelId of session.foregroundChannels) {
+      this.flushDebounced(session.id, channelId);
+    }
+
+    const msg = formatCompletionNotification(session);
+
+    // Collect all channels to notify (foreground + origin)
+    const channels = new Set(session.foregroundChannels);
+    if (originChannel) channels.add(originChannel);
+
+    for (const channelId of channels) {
+      this.sendMessage(channelId, msg);
+    }
+
+    // Clean up debounce state for this session
+    this.cleanupSession(session.id);
+  }
+
+  /**
+   * Called when budget is exhausted (subtype: "error_max_budget_usd").
+   * This is effectively handled by onSessionComplete since it's a result event,
+   * but we expose it separately for clarity and custom formatting.
+   */
+  onBudgetExhausted(session: Session, originChannel?: string): void {
+    for (const channelId of session.foregroundChannels) {
+      this.flushDebounced(session.id, channelId);
+    }
+
+    const duration = formatDuration(session.duration);
+    const msg = [
+      `⛔ Session limit reached — ${session.name} [${session.id}] (${duration})`,
+      `   📁 ${session.workdir}`,
+    ].join("\n");
+
+    const channels = new Set(session.foregroundChannels);
+    if (originChannel) channels.add(originChannel);
+
+    for (const channelId of channels) {
+      this.sendMessage(channelId, msg);
+    }
+
+    this.cleanupSession(session.id);
+  }
+
+  // ─── Waiting for input (all session types) ─────────────────────────
+
+  /**
+   * Called when any session is waiting for user input (e.g. Claude asked a question,
+   * needs a permission decision, or finished a turn in multi-turn mode).
+   * Notifies foreground and origin channels so the user knows Claude needs a response.
+   */
+  onWaitingForInput(session: Session, originChannel?: string): void {
+    console.log(`[NotificationRouter] onWaitingForInput session=${session.id} (${session.name}), originChannel=${originChannel}, fgChannels=${JSON.stringify([...session.foregroundChannels])}`);
+
+    // Flush any pending foreground output first
+    for (const channelId of session.foregroundChannels) {
+      this.flushDebounced(session.id, channelId);
+    }
+
+    // Build notification message with last output as context
+    const lastOutput = session.getOutput(5);
+    let preview = lastOutput.join("\n");
+    if (preview.length > 500) {
+      preview = preview.slice(-500);
+    }
+
+    // Determine which channels are background-only (origin but not foreground)
+    const fgChannels = new Set(session.foregroundChannels);
+    const allChannels = new Set(session.foregroundChannels);
+    if (originChannel) allChannels.add(originChannel);
+
+    for (const channelId of allChannels) {
+      const isBg = !fgChannels.has(channelId);
+      if (isBg) {
+        // Background channel: show the full question so user can follow along
+        const msg = [
+          `🔔 [${session.name}] Claude asks:`,
+          preview || "(no output captured)",
+        ].join("\n");
+        this.sendMessage(channelId, msg);
+      } else {
+        // Foreground channel: compact notification (output already streamed)
+        const duration = formatDuration(session.duration);
+        const msg = [
+          `💬 Session ${session.name} [${session.id}] is waiting for input (${duration})`,
+          `   Use claude_respond to reply.`,
+        ].join("\n");
+        this.sendMessage(channelId, msg);
+      }
+    }
+  }
+
+  // ─── Public message passthrough ─────────────────────────────────────
+
+  /**
+   * Emit a message to a specific channel. Used by tools (e.g. claude_respond)
+   * to display messages in the conversation thread without going through
+   * the foreground streaming / debounce logic.
+   */
+  emitToChannel(channelId: string, text: string): void {
+    this.sendMessage(channelId, text);
+  }
+
+  // ─── Long-running reminder ─────────────────────────────────────────
+
+  /**
+   * Periodic check: notify if a background session (no foreground channels)
+   * has been running for more than 10 minutes. Only once per session.
+   */
+  private checkLongRunning(): void {
+    if (!this.getActiveSessions) return;
+
+    const sessions = this.getActiveSessions();
+    const now = Date.now();
+
+    for (const session of sessions) {
+      if (
+        (session.status === "running" || session.status === "starting") &&
+        session.foregroundChannels.size === 0 &&
+        !this.longRunningReminded.has(session.id) &&
+        now - session.startedAt > LONG_RUNNING_THRESHOLD_MS
+      ) {
+        this.longRunningReminded.add(session.id);
+
+        const duration = formatDuration(now - session.startedAt);
+        const msg = [
+          `⏱️ Session ${session.name} [${session.id}] running for ${duration}`,
+          `   📁 ${session.workdir}`,
+          `   Use claude_fg to check on it, or claude_kill to stop it.`,
+        ].join("\n");
+
+        // Try to notify the origin channel if available
+        if (session.originChannel) {
+          this.sendMessage(session.originChannel, msg);
+        }
+      }
+    }
+  }
+
+  // ─── Debounce internals ────────────────────────────────────────────
+
+  private debounceKey(sessionId: string, channelId: string): string {
+    return `${sessionId}|${channelId}`;
+  }
+
+  private appendDebounced(
+    sessionId: string,
+    channelId: string,
+    text: string,
+  ): void {
+    const key = this.debounceKey(sessionId, channelId);
+    const existing = this.debounceMap.get(key);
+
+    if (existing) {
+      clearTimeout(existing.timer);
+      existing.buffer += text;
+      existing.timer = setTimeout(() => {
+        this.flushDebounced(sessionId, channelId);
+      }, DEBOUNCE_MS);
+    } else {
+      const timer = setTimeout(() => {
+        this.flushDebounced(sessionId, channelId);
+      }, DEBOUNCE_MS);
+      this.debounceMap.set(key, { buffer: text, timer });
+    }
+  }
+
+  private flushDebounced(sessionId: string, channelId: string): void {
+    const key = this.debounceKey(sessionId, channelId);
+    const entry = this.debounceMap.get(key);
+    if (!entry) return;
+
+    clearTimeout(entry.timer);
+    if (entry.buffer) {
+      console.log(`[NotificationRouter] flushDebounced -> session=${sessionId}, channel=${channelId}, bufferLen=${entry.buffer.length}`);
+      this.sendMessage(channelId, entry.buffer);
+    }
+    this.debounceMap.delete(key);
+  }
+
+  private cleanupSession(sessionId: string): void {
+    // Remove all debounce entries for this session
+    for (const key of this.debounceMap.keys()) {
+      if (key.startsWith(`${sessionId}|`)) {
+        const entry = this.debounceMap.get(key)!;
+        clearTimeout(entry.timer);
+        this.debounceMap.delete(key);
+      }
+    }
+    this.longRunningReminded.delete(sessionId);
+  }
+}
+
+// ─── Formatting helpers ──────────────────────────────────────────────
+
+function formatCompletionNotification(session: Session): string {
+  const duration = formatDuration(session.duration);
+  const promptSummary =
+    session.prompt.length > 60
+      ? session.prompt.slice(0, 60) + "..."
+      : session.prompt;
+
+  if (session.status === "completed") {
+    return [
+      `✅ Claude Code [${session.id}] completed (${duration})`,
+      `   📁 ${session.workdir}`,
+      `   📝 "${promptSummary}"`,
+    ].join("\n");
+  }
+
+  if (session.status === "failed") {
+    const errorDetail = session.error
+      ? `   ⚠️ ${session.error}`
+      : session.result?.subtype
+        ? `   ⚠️ ${session.result.subtype}`
+        : "";
+    return [
+      `❌ Claude Code [${session.id}] failed (${duration})`,
+      `   📁 ${session.workdir}`,
+      `   📝 "${promptSummary}"`,
+      ...(errorDetail ? [errorDetail] : []),
+    ].join("\n");
+  }
+
+  if (session.status === "killed") {
+    return [
+      `⛔ Claude Code [${session.id}] killed (${duration})`,
+      `   📁 ${session.workdir}`,
+      `   📝 "${promptSummary}"`,
+    ].join("\n");
+  }
+
+  // Fallback
+  return `Session [${session.id}] finished with status: ${session.status}`;
+}
+
+/**
+ * Summarize tool input into a short string for compact display.
+ * Handles common Claude Code tools.
+ */
+function summarizeToolInput(input: any): string {
+  if (!input || typeof input !== "object") return "";
+
+  // File operations: show the path
+  if (input.file_path) return truncate(input.file_path, 60);
+  if (input.path) return truncate(input.path, 60);
+
+  // Bash: show the command
+  if (input.command) return truncate(input.command, 80);
+
+  // Search: show the pattern
+  if (input.pattern) return truncate(input.pattern, 60);
+
+  // Glob
+  if (input.glob) return truncate(input.glob, 60);
+
+  // Generic: show first string value
+  const firstValue = Object.values(input).find(
+    (v) => typeof v === "string" && v.length > 0,
+  );
+  if (firstValue) return truncate(String(firstValue), 60);
+
+  return "";
+}
+
+function truncate(s: string, maxLen: number): string {
+  if (s.length <= maxLen) return s;
+  return s.slice(0, maxLen - 3) + "...";
+}