@betrue/openclaw-claude-code-plugin 1.0.0

package/src/session.ts

@@ -0,0 +1,455 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type { SessionConfig, SessionStatus, PermissionMode } from "./types";
+import { pluginConfig } from "./shared";
+import { nanoid } from "nanoid";
+
+const OUTPUT_BUFFER_MAX = 200;
+
+/**
+ * AsyncIterable controller for multi-turn conversations.
+ * Allows pushing SDKUserMessage objects into the query() prompt stream.
+ */
+class MessageStream {
+  private queue: Array<{ type: "user"; message: { role: "user"; content: string }; parent_tool_use_id: null; session_id: string }> = [];
+  private resolve: (() => void) | null = null;
+  private done: boolean = false;
+
+  push(text: string, sessionId: string): void {
+    const msg = {
+      type: "user" as const,
+      message: { role: "user" as const, content: text },
+      parent_tool_use_id: null,
+      session_id: sessionId,
+    };
+    this.queue.push(msg);
+    if (this.resolve) {
+      this.resolve();
+      this.resolve = null;
+    }
+  }
+
+  end(): void {
+    this.done = true;
+    if (this.resolve) {
+      this.resolve();
+      this.resolve = null;
+    }
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<any, void, undefined> {
+    while (true) {
+      while (this.queue.length > 0) {
+        yield this.queue.shift()!;
+      }
+      if (this.done) return;
+      await new Promise<void>((r) => { this.resolve = r; });
+    }
+  }
+}
+
+export class Session {
+  readonly id: string;
+  name: string;
+  claudeSessionId?: string;
+
+  // Config
+  readonly prompt: string;
+  readonly workdir: string;
+  readonly model?: string;
+  readonly maxBudgetUsd: number;
+  private readonly systemPrompt?: string;
+  private readonly allowedTools?: string[];
+  private readonly permissionMode: PermissionMode;
+
+  // Resume/fork config (Task 16)
+  readonly resumeSessionId?: string;
+  readonly forkSession?: boolean;
+
+  // Multi-turn config (Task 15)
+  readonly multiTurn: boolean;
+  private messageStream?: MessageStream;
+  private queryHandle?: ReturnType<typeof query>;
+  private idleTimer?: ReturnType<typeof setTimeout>;
+
+  // Safety-net idle timer: fires only if NO messages (text, tool_use, result) arrive
+  // for 15 seconds. The primary "waiting for input" signal is the multi-turn
+  // end-of-turn result handler — this timer is a rare fallback for edge cases
+  // (e.g. Claude stuck waiting for permission/clarification without a result event).
+  private safetyNetTimer?: ReturnType<typeof setTimeout>;
+  private static readonly SAFETY_NET_IDLE_MS = 15_000;
+
+  // State
+  status: SessionStatus = "starting";
+  error?: string;
+  startedAt: number;
+  completedAt?: number;
+
+  // SDK handles
+  private abortController: AbortController;
+
+  // Output
+  outputBuffer: string[] = [];
+
+  // Result
+  result?: {
+    subtype: string;
+    duration_ms: number;
+    total_cost_usd: number;
+    num_turns: number;
+    result?: string;
+    is_error: boolean;
+    session_id: string;
+  };
+
+  // Cost
+  costUsd: number = 0;
+
+  // Foreground
+  foregroundChannels: Set<string> = new Set();
+
+  // Per-channel output offset: tracks the outputBuffer index last seen while foregrounded.
+  // Used by claude_fg to send "catchup" of missed output when re-foregrounding.
+  private fgOutputOffsets: Map<string, number> = new Map();
+
+  // Origin channel -- the channel that launched this session (for background notifications)
+  originChannel?: string;
+
+  // Flags
+  budgetExhausted: boolean = false;
+  private waitingForInputFired: boolean = false;
+
+  // Event callbacks
+  onOutput?: (text: string) => void;
+  onToolUse?: (toolName: string, toolInput: any) => void;
+  onBudgetExhausted?: (session: Session) => void;
+  onComplete?: (session: Session) => void;
+  onWaitingForInput?: (session: Session) => void;
+
+  constructor(config: SessionConfig, name: string) {
+    this.id = nanoid(8);
+    this.name = name;
+    this.prompt = config.prompt;
+    this.workdir = config.workdir;
+    this.model = config.model;
+    this.maxBudgetUsd = config.maxBudgetUsd;
+    this.systemPrompt = config.systemPrompt;
+    this.allowedTools = config.allowedTools;
+    this.permissionMode = config.permissionMode ?? pluginConfig.permissionMode ?? "bypassPermissions";
+    this.originChannel = config.originChannel;
+    this.resumeSessionId = config.resumeSessionId;
+    this.forkSession = config.forkSession;
+    this.multiTurn = config.multiTurn ?? false;
+    this.startedAt = Date.now();
+    this.abortController = new AbortController();
+  }
+
+  async start(): Promise<void> {
+    let q;
+    try {
+      // Build SDK options
+      const options: any = {
+        cwd: this.workdir,
+        model: this.model,
+        maxBudgetUsd: this.maxBudgetUsd,
+        permissionMode: this.permissionMode,
+        allowDangerouslySkipPermissions: this.permissionMode === "bypassPermissions",
+        allowedTools: this.allowedTools,
+        includePartialMessages: true,
+        abortController: this.abortController,
+        ...(this.systemPrompt ? { systemPrompt: this.systemPrompt } : {}),
+      };
+
+      // Resume support (Task 16): pass resume + forkSession to SDK
+      if (this.resumeSessionId) {
+        options.resume = this.resumeSessionId;
+        if (this.forkSession) {
+          options.forkSession = true;
+        }
+      }
+
+      // Determine prompt: multi-turn uses AsyncIterable, otherwise string
+      let prompt: string | AsyncIterable<any>;
+      if (this.multiTurn) {
+        // Create a message stream for multi-turn conversations
+        this.messageStream = new MessageStream();
+        // Push the initial prompt as the first message
+        // The session_id will be set once we receive the init message
+        // For now use a placeholder — the SDK handles this
+        this.messageStream.push(this.prompt, "");
+        prompt = this.messageStream;
+      } else {
+        prompt = this.prompt;
+      }
+
+      q = query({
+        prompt,
+        options,
+      });
+
+      // Store the query handle for multi-turn control (interrupt, streamInput)
+      this.queryHandle = q;
+    } catch (err: any) {
+      this.status = "failed";
+      this.error = err?.message ?? String(err);
+      this.completedAt = Date.now();
+      return;
+    }
+
+    // Run the async iteration in background (non-blocking)
+    this.consumeMessages(q).catch((err) => {
+      if (this.status === "starting" || this.status === "running") {
+        this.status = "failed";
+        this.error = err?.message ?? String(err);
+        this.completedAt = Date.now();
+      }
+    });
+  }
+
+  /**
+   * Reset the safety-net idle timer. Called on EVERY incoming message
+   * (text, tool_use, result). If no message of any kind arrives for
+   * SAFETY_NET_IDLE_MS (15s), we assume the session is stuck waiting
+   * for user input (e.g. a permission prompt without a result event).
+   *
+   * The primary "waiting for input" signal is the multi-turn end-of-turn
+   * result handler — this timer is a rare fallback for edge cases only.
+   */
+  private resetSafetyNetTimer(): void {
+    this.clearSafetyNetTimer();
+    this.safetyNetTimer = setTimeout(() => {
+      this.safetyNetTimer = undefined;
+      if (this.status === "running" && this.onWaitingForInput && !this.waitingForInputFired) {
+        console.log(`[Session] ${this.id} no messages for ${Session.SAFETY_NET_IDLE_MS / 1000}s — firing onWaitingForInput (safety-net)`);
+        this.waitingForInputFired = true;
+        this.onWaitingForInput(this);
+      }
+    }, Session.SAFETY_NET_IDLE_MS);
+  }
+
+  /**
+   * Cancel the safety-net idle timer.
+   */
+  private clearSafetyNetTimer(): void {
+    if (this.safetyNetTimer) {
+      clearTimeout(this.safetyNetTimer);
+      this.safetyNetTimer = undefined;
+    }
+  }
+
+  /**
+   * Reset (or start) the idle timer for multi-turn sessions.
+   * If no sendMessage() call arrives within the configured idle timeout, the
+   * session is automatically killed to avoid zombie sessions stuck in "running"
+   * forever. Timeout is read from pluginConfig.idleTimeoutMinutes (default 30).
+   */
+  private resetIdleTimer(): void {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    if (!this.multiTurn) return;
+    const idleTimeoutMs = (pluginConfig.idleTimeoutMinutes ?? 30) * 60 * 1000;
+    this.idleTimer = setTimeout(() => {
+      if (this.status === "running") {
+        console.log(`[Session] ${this.id} idle timeout reached (${pluginConfig.idleTimeoutMinutes ?? 30}min), auto-killing`);
+        this.kill();
+      }
+    }, idleTimeoutMs);
+  }
+
+  /**
+   * Send a follow-up message to a running multi-turn session.
+   * Uses the SDK's streamInput() method to push a new user message.
+   */
+  async sendMessage(text: string): Promise<void> {
+    if (this.status !== "running") {
+      throw new Error(`Session is not running (status: ${this.status})`);
+    }
+
+    this.resetIdleTimer();
+    this.waitingForInputFired = false;
+
+    if (this.multiTurn && this.messageStream) {
+      // Push into the AsyncIterable prompt stream
+      this.messageStream.push(text, this.claudeSessionId ?? "");
+    } else if (this.queryHandle && typeof (this.queryHandle as any).streamInput === "function") {
+      // For non-multi-turn sessions, use streamInput() to inject messages
+      const userMsg = {
+        type: "user" as const,
+        message: { role: "user" as const, content: text },
+        parent_tool_use_id: null,
+        session_id: this.claudeSessionId ?? "",
+      };
+      // Create a one-shot async iterable
+      async function* oneMessage() { yield userMsg; }
+      await (this.queryHandle as any).streamInput(oneMessage());
+    } else {
+      throw new Error("Session does not support multi-turn messaging. Launch with multiTurn: true or use the SDK streamInput.");
+    }
+  }
+
+  /**
+   * Interrupt the current turn (e.g. to send a new message mid-response).
+   */
+  async interrupt(): Promise<void> {
+    if (this.queryHandle && typeof (this.queryHandle as any).interrupt === "function") {
+      await (this.queryHandle as any).interrupt();
+    }
+  }
+
+  private async consumeMessages(q: AsyncIterable<any>): Promise<void> {
+    for await (const msg of q) {
+      // Reset the safety-net timer on every incoming message.
+      // This ensures it only fires when there is truly no activity for 15s.
+      this.resetSafetyNetTimer();
+
+      if (
+        msg.type === "system" &&
+        msg.subtype === "init"
+      ) {
+        this.claudeSessionId = msg.session_id;
+        this.status = "running";
+        this.resetIdleTimer();
+      } else if (msg.type === "assistant") {
+        this.waitingForInputFired = false;
+        const contentBlocks = msg.message?.content ?? [];
+        console.log(`[Session] ${this.id} assistant message received, blocks=${contentBlocks.length}, fgChannels=${JSON.stringify([...this.foregroundChannels])}`);
+        for (const block of contentBlocks) {
+          if (block.type === "text") {
+            const text: string = block.text;
+            this.outputBuffer.push(text);
+            if (this.outputBuffer.length > OUTPUT_BUFFER_MAX) {
+              this.outputBuffer.splice(
+                0,
+                this.outputBuffer.length - OUTPUT_BUFFER_MAX
+              );
+            }
+            if (this.onOutput) {
+              console.log(`[Session] ${this.id} calling onOutput, textLen=${text.length}`);
+              this.onOutput(text);
+            } else {
+              console.log(`[Session] ${this.id} onOutput callback NOT set`);
+            }
+          } else if (block.type === "tool_use") {
+            // Emit tool_use event for compact foreground display
+            if (this.onToolUse) {
+              console.log(`[Session] ${this.id} calling onToolUse, tool=${block.name}`);
+              this.onToolUse(block.name, block.input);
+            } else {
+              console.log(`[Session] ${this.id} onToolUse callback NOT set`);
+            }
+          }
+        }
+      } else if (msg.type === "result") {
+        this.result = {
+          subtype: msg.subtype,
+          duration_ms: msg.duration_ms,
+          total_cost_usd: msg.total_cost_usd,
+          num_turns: msg.num_turns,
+          result: msg.result,
+          is_error: msg.is_error,
+          session_id: msg.session_id,
+        };
+        this.costUsd = msg.total_cost_usd;
+
+        // In multi-turn mode, a "success" result means end-of-turn, not end-of-session.
+        // The session stays running so the user can send follow-up messages.
+        // Only close on errors (budget exhaustion, actual failures, etc.).
+        const isMultiTurnEndOfTurn = this.multiTurn && this.messageStream && msg.subtype === "success";
+
+        if (isMultiTurnEndOfTurn) {
+          // Keep session alive — just update cost and result, stay in "running" status
+          console.log(`[Session] ${this.id} multi-turn end-of-turn (turn ${msg.num_turns}), staying open`);
+          this.clearSafetyNetTimer();
+          this.resetIdleTimer();
+
+          // Notify that the session is now waiting for user input
+          if (this.onWaitingForInput && !this.waitingForInputFired) {
+            console.log(`[Session] ${this.id} calling onWaitingForInput`);
+            this.waitingForInputFired = true;
+            this.onWaitingForInput(this);
+          }
+        } else {
+          // Session is truly done — either single-turn, or multi-turn with error/budget
+          this.clearSafetyNetTimer();
+          if (this.idleTimer) clearTimeout(this.idleTimer);
+          this.status = msg.subtype === "success" ? "completed" : "failed";
+          this.completedAt = Date.now();
+
+          // End the message stream if multi-turn
+          if (this.messageStream) {
+            this.messageStream.end();
+          }
+
+          // Detect budget exhaustion
+          if (msg.subtype === "error_max_budget_usd") {
+            this.budgetExhausted = true;
+            if (this.onBudgetExhausted) {
+              this.onBudgetExhausted(this);
+            }
+          }
+
+          if (this.onComplete) {
+            console.log(`[Session] ${this.id} calling onComplete, status=${this.status}`);
+            this.onComplete(this);
+          } else {
+            console.log(`[Session] ${this.id} onComplete callback NOT set`);
+          }
+        }
+      }
+    }
+  }
+
+  kill(): void {
+    if (this.status !== "starting" && this.status !== "running") return;
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.clearSafetyNetTimer();
+    this.status = "killed";
+    this.completedAt = Date.now();
+    // End the message stream
+    if (this.messageStream) {
+      this.messageStream.end();
+    }
+    this.abortController.abort();
+  }
+
+  getOutput(lines?: number): string[] {
+    if (lines === undefined) {
+      return this.outputBuffer.slice();
+    }
+    return this.outputBuffer.slice(-lines);
+  }
+
+  /**
+   * Get all output produced since this channel was last foregrounded (or since launch).
+   * Returns the missed output lines. If this is the first time foregrounding,
+   * returns the full buffer (same as getOutput()).
+   */
+  getCatchupOutput(channelId: string): string[] {
+    const lastOffset = this.fgOutputOffsets.get(channelId) ?? 0;
+    // The buffer is capped at OUTPUT_BUFFER_MAX. If output has been trimmed,
+    // we can only return what's still in the buffer.
+    const available = this.outputBuffer.length;
+    if (lastOffset >= available) {
+      return []; // Already caught up
+    }
+    return this.outputBuffer.slice(lastOffset);
+  }
+
+  /**
+   * Record that this channel has seen all current output (call when foregrounding).
+   * Sets the offset to the current end of the buffer.
+   */
+  markFgOutputSeen(channelId: string): void {
+    this.fgOutputOffsets.set(channelId, this.outputBuffer.length);
+  }
+
+  /**
+   * Save the current output position for a channel (call when backgrounding).
+   * This records where they left off so catchup can resume from here.
+   */
+  saveFgOutputOffset(channelId: string): void {
+    this.fgOutputOffsets.set(channelId, this.outputBuffer.length);
+  }
+
+  get duration(): number {
+    return (this.completedAt ?? Date.now()) - this.startedAt;
+  }
+}

package/src/shared.ts

@@ -0,0 +1,194 @@
+import type { Session } from "./session";
+import type { SessionManager, SessionMetrics } from "./session-manager";
+import type { NotificationRouter } from "./notifications";
+import type { PluginConfig } from "./types";
+
+export let sessionManager: SessionManager | null = null;
+export let notificationRouter: NotificationRouter | null = null;
+
+/**
+ * Plugin config — populated at service start from api.getConfig().
+ * All modules should read from this instead of using hardcoded constants.
+ */
+export let pluginConfig: PluginConfig = {
+  maxSessions: 5,
+  defaultBudgetUsd: 5,
+  idleTimeoutMinutes: 30,
+  maxPersistedSessions: 50,
+};
+
+export function setPluginConfig(config: Partial<PluginConfig>): void {
+  pluginConfig = {
+    maxSessions: config.maxSessions ?? 5,
+    defaultBudgetUsd: config.defaultBudgetUsd ?? 5,
+    defaultModel: config.defaultModel,
+    defaultWorkdir: config.defaultWorkdir,
+    idleTimeoutMinutes: config.idleTimeoutMinutes ?? 30,
+    maxPersistedSessions: config.maxPersistedSessions ?? 50,
+    fallbackChannel: config.fallbackChannel,
+  };
+}
+
+export function setSessionManager(sm: SessionManager | null): void {
+  sessionManager = sm;
+}
+
+export function setNotificationRouter(nr: NotificationRouter | null): void {
+  notificationRouter = nr;
+}
+
+/**
+ * Resolve origin channel from an OpenClaw command/tool context.
+ *
+ * Attempts to build a "channel:target" string from context properties.
+ * Command context has: ctx.channel, ctx.senderId, ctx.chatId, ctx.id
+ * Tool execute receives just an _id (tool call ID like "toolu_xxx").
+ *
+ * Falls back to config.fallbackChannel when the real channel info
+ * is not available. If no fallbackChannel is configured, returns
+ * "unknown" as a safe default.
+ */
+
+export function resolveOriginChannel(ctx: any, explicitChannel?: string): string {
+  // Highest priority: explicit channel passed by caller (e.g. from tool params)
+  if (explicitChannel && String(explicitChannel).includes(":")) {
+    return String(explicitChannel);
+  }
+  // Try structured channel info from command context
+  if (ctx?.channel && ctx?.chatId) {
+    return `${ctx.channel}:${ctx.chatId}`;
+  }
+  if (ctx?.channel && ctx?.senderId) {
+    return `${ctx.channel}:${ctx.senderId}`;
+  }
+  // If the context id looks like a numeric telegram chat id
+  if (ctx?.id && /^-?\d+$/.test(String(ctx.id))) {
+    return `telegram:${ctx.id}`;
+  }
+  // If channelId is already in "channel:target" format, pass through
+  if (ctx?.channelId && String(ctx.channelId).includes(":")) {
+    return String(ctx.channelId);
+  }
+  // Log what we got for debugging
+  const fallback = pluginConfig.fallbackChannel ?? "unknown";
+  console.log(`[resolveOriginChannel] Could not resolve channel from ctx keys: ${ctx ? Object.keys(ctx).join(", ") : "null"}, using fallback=${fallback}`);
+  return fallback;
+}
+
+export function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const secs = seconds % 60;
+  if (minutes > 0) return `${minutes}m${secs}s`;
+  return `${secs}s`;
+}
+
+// Stop words filtered out when generating session names from prompts
+const STOP_WORDS = new Set([
+  "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+  "have", "has", "had", "do", "does", "did", "will", "would", "could",
+  "should", "may", "might", "shall", "can", "need", "must",
+  "i", "me", "my", "we", "our", "you", "your", "it", "its", "he", "she",
+  "to", "of", "in", "for", "on", "with", "at", "by", "from", "as",
+  "into", "through", "about", "that", "this", "these", "those",
+  "and", "or", "but", "if", "then", "so", "not", "no",
+  "please", "just", "also", "very", "all", "some", "any", "each",
+  "make", "write", "create", "build", "implement", "add", "update",
+]);
+
+/**
+ * Generate a short kebab-case name from a prompt.
+ * Extracts 2-3 meaningful keywords.
+ */
+export function generateSessionName(prompt: string): string {
+  const words = prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 1 && !STOP_WORDS.has(w));
+
+  const keywords = words.slice(0, 3);
+  if (keywords.length === 0) return "session";
+  return keywords.join("-");
+}
+
+const STATUS_ICONS: Record<string, string> = {
+  starting: "🟡",
+  running: "🟢",
+  completed: "✅",
+  failed: "❌",
+  killed: "⛔",
+};
+
+export function formatSessionListing(session: Session): string {
+  const icon = STATUS_ICONS[session.status] ?? "❓";
+  const duration = formatDuration(session.duration);
+  const fg = session.foregroundChannels.size > 0 ? "foreground" : "background";
+  const mode = session.multiTurn ? "multi-turn" : "single";
+  const promptSummary =
+    session.prompt.length > 80
+      ? session.prompt.slice(0, 80) + "..."
+      : session.prompt;
+
+  const lines = [
+    `${icon} ${session.name} [${session.id}] (${duration}) — ${fg}, ${mode}`,
+    `   📁 ${session.workdir}`,
+    `   📝 "${promptSummary}"`,
+  ];
+
+  // Show Claude session ID for resume support
+  if (session.claudeSessionId) {
+    lines.push(`   🔗 Claude ID: ${session.claudeSessionId}`);
+  }
+
+  // Show resume info if this session was resumed
+  if (session.resumeSessionId) {
+    lines.push(`   ↩️  Resumed from: ${session.resumeSessionId}${session.forkSession ? " (forked)" : ""}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format aggregated metrics into a human-readable stats report (Task 18).
+ */
+export function formatStats(metrics: SessionMetrics): string {
+  // Average duration
+  const avgDurationMs =
+    metrics.sessionsWithDuration > 0
+      ? metrics.totalDurationMs / metrics.sessionsWithDuration
+      : 0;
+
+  // Currently running sessions (live count from sessionManager)
+  const running = sessionManager
+    ? sessionManager.list("running").length
+    : 0;
+
+  const { completed, failed, killed } = metrics.sessionsByStatus;
+  const totalFinished = completed + failed + killed;
+
+  const lines = [
+    `📊 Claude Code Plugin Stats`,
+    ``,
+    `📋 Sessions`,
+    `   Launched:   ${metrics.totalLaunched}`,
+    `   Running:    ${running}`,
+    `   Completed:  ${completed}`,
+    `   Failed:     ${failed}`,
+    `   Killed:     ${killed}`,
+    ``,
+    `⏱️  Average duration: ${avgDurationMs > 0 ? formatDuration(avgDurationMs) : "n/a"}`,
+  ];
+
+  if (metrics.mostExpensive) {
+    const me = metrics.mostExpensive;
+    lines.push(
+      ``,
+      `🏆 Notable session`,
+      `   ${me.name} [${me.id}]`,
+      `   📝 "${me.prompt}"`,
+    );
+  }
+
+  return lines.join("\n");
+}