@yeaft/webchat-agent 0.1.250 → 0.1.252

package/claude.js

@@ -1,6 +1,7 @@
 import { query, Stream } from './sdk/index.js';
 import ctx from './context.js';
 import { sendConversationList, sendOutput, sendError, handleAskUserQuestion } from './conversation.js';
+import { startSubagentWatcher, stopSubagentWatcher, cleanupSubagentWatchers } from './subagent.js';
 
 /**
  * Determine maxContextTokens and autoCompactThreshold from model name.
@@ -40,6 +41,7 @@ export async function startClaudeQuery(conversationId, workDir, resumeSessionId)
     if (existing.abortController) {
       existing.abortController.abort();
     }
+    cleanupSubagentWatchers(conversationId);
     ctx.conversations.delete(conversationId);
   }
 
@@ -211,6 +213,9 @@ function detectAndTrackBackgroundTask(conversationId, state, message) {
             conversationId,
             task: taskInfo
           });
+
+          // Start watching subagent JSONL files for this Task
+          startSubagentWatcher(conversationId, state, toolUseId);
         }
       }
     }
@@ -241,6 +246,11 @@ function detectAndTrackBackgroundTask(conversationId, state, message) {
           taskId: toolUseId,
           task: taskInfo
         });
+
+        // Stop subagent watcher if this was a Task (Agent) tool_use
+        if (taskInfo.type === 'agent') {
+          stopSubagentWatcher(conversationId, toolUseId);
+        }
       }
     }
   }
@@ -310,7 +320,8 @@ async function processClaudeOutput(conversationId, claudeQuery, state) {
             ctx.sendToServer({
               type: 'slash_commands_update',
               conversationId,
-              slashCommands: state.slashCommands
+              slashCommands: state.slashCommands,
+              slashCommandDescriptions: ctx.slashCommandDescriptions
             });
           }
         }
@@ -563,6 +574,7 @@ async function processClaudeOutput(conversationId, claudeQuery, state) {
       console.log(`[SDK] Stale processClaudeOutput for ${conversationId}, skipping cleanup`);
     } else if (!wasCancelled && (wasTurnActive || !resultHandled)) {
       // 进程异常退出：要么 turn 正在进行中，要么从未成功完成过任何 turn
+      cleanupSubagentWatchers(conversationId);
       ctx.sendToServer({
         type: 'conversation_closed',
         conversationId,

package/connection/buffer.js

@@ -7,6 +7,7 @@ export const BUFFERABLE_TYPES = new Set([
   'claude_output', 'turn_completed', 'conversation_closed',
   'session_id_update', 'compact_status', 'slash_commands_update',
   'background_task_started', 'background_task_output',
+  'subagent_started', 'subagent_message', 'subagent_completed',
   'crew_output', 'crew_status', 'crew_turn_completed',
   'crew_session_created', 'crew_session_restored', 'crew_human_needed',
   'crew_role_added', 'crew_role_removed',

package/context.js

@@ -14,6 +14,8 @@ export default {
   agentCapabilities: [],
   // Agent 级别的 slash commands 缓存（所有 conversation 共用）
   slashCommands: [],
+  // Slash command 描述映射: { commandName: description } — 从 plugin commands/*.md 提取
+  slashCommandDescriptions: {},
   // MCP servers 列表 (从 ~/.claude.json 读取): [{ name, enabled, source }]
   mcpServers: [],
   // 连接相关

package/conversation.js

@@ -1,3 +1,6 @@
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
 import ctx from './context.js';
 import { query } from './sdk/index.js';
 import { loadSessionHistory } from './history.js';
@@ -7,6 +10,114 @@ import { crewSessions, loadCrewIndex } from './crew.js';
 // 不支持的斜杠命令（真正需要交互式 CLI 的命令）
 const UNSUPPORTED_SLASH_COMMANDS = ['/help', '/bug', '/login', '/logout', '/terminal-setup', '/vim', '/config'];
 
+// 内置命令的描述（作为 fallback，这些命令 CLI 不提供 frontmatter 描述）
+const BUILTIN_COMMAND_DESCRIPTIONS = {
+  compact: 'Compact conversation context',
+  context: 'Show context usage',
+  cost: 'Show token costs',
+  init: 'Reinitialize session',
+  review: 'Code review',
+  insights: 'Session insights',
+  'pr-comments': 'PR comment review',
+  'release-notes': 'Generate release notes',
+  'security-review': 'Security review',
+  heapdump: 'Heap dump (debug)',
+};
+
+/**
+ * Load command descriptions from installed plugin commands/*.md files.
+ * Parses YAML frontmatter to extract name and description fields.
+ * Results are cached in ctx.slashCommandDescriptions.
+ */
+export function loadPluginCommandDescriptions() {
+  if (Object.keys(ctx.slashCommandDescriptions).length > 0) return; // already loaded
+
+  try {
+    const installedPath = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
+    const installed = JSON.parse(readFileSync(installedPath, 'utf-8'));
+
+    for (const [pluginKey, entries] of Object.entries(installed.plugins || {})) {
+      // pluginKey: "yeaft-skills@yeaft-skills-dev"
+      const pluginName = pluginKey.split('@')[0]; // "yeaft-skills"
+      for (const entry of entries) {
+        const commandsDir = join(entry.installPath, 'commands');
+        let files;
+        try {
+          files = readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+        } catch { continue; }
+
+        for (const file of files) {
+          try {
+            const content = readFileSync(join(commandsDir, file), 'utf-8');
+            const fm = parseFrontmatter(content);
+            if (fm.name && fm.description) {
+              // CLI uses pluginName:commandName format (e.g. "yeaft-skills:sprint")
+              const cliName = `${pluginName}:${fm.name}`;
+              // Take first line of description only
+              const desc = fm.description.split('\n')[0].trim();
+              ctx.slashCommandDescriptions[cliName] = desc;
+            }
+          } catch { /* skip unparseable files */ }
+        }
+      }
+    }
+
+    // Add builtin descriptions
+    for (const [name, desc] of Object.entries(BUILTIN_COMMAND_DESCRIPTIONS)) {
+      if (!ctx.slashCommandDescriptions[name]) {
+        ctx.slashCommandDescriptions[name] = desc;
+      }
+    }
+
+    console.log(`[Preload] Loaded ${Object.keys(ctx.slashCommandDescriptions).length} command descriptions`);
+  } catch (err) {
+    console.warn('[Preload] Failed to load plugin command descriptions:', err.message);
+  }
+}
+
+/**
+ * Minimal YAML frontmatter parser for commands/*.md files.
+ * Extracts name and description from --- delimited frontmatter.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const fm = {};
+  const lines = match[1].split('\n');
+  let currentKey = null;
+  let multilineValue = '';
+
+  for (const line of lines) {
+    // New key: value pair
+    const kvMatch = line.match(/^(\w+):\s*(.*)/);
+    if (kvMatch) {
+      // Save previous multiline value
+      if (currentKey && multilineValue) {
+        fm[currentKey] = multilineValue.trim();
+      }
+      currentKey = kvMatch[1];
+      const val = kvMatch[2].trim();
+      if (val === '|' || val === '>') {
+        multilineValue = '';
+      } else {
+        fm[currentKey] = val;
+        currentKey = null;
+        multilineValue = '';
+      }
+    } else if (currentKey && (line.startsWith('  ') || line.trim() === '')) {
+      // Continuation of multiline value
+      multilineValue += (multilineValue ? '\n' : '') + line.trimStart();
+    }
+  }
+  // Save last multiline value
+  if (currentKey && multilineValue) {
+    fm[currentKey] = multilineValue.trim();
+  }
+
+  return fm;
+}
+
 /**
  * Prestart Claude CLI process in background (fire-and-forget).
  * When the query starts, processClaudeOutput will receive the system init message
@@ -33,6 +144,10 @@ function prestartClaude(conversationId, workDir, resumeSessionId) {
  */
 export async function preloadSlashCommands(workDir, targetId = '__preload__') {
   const effectiveWorkDir = workDir || ctx.CONFIG.workDir;
+
+  // Eagerly load plugin command descriptions (cached, runs once)
+  loadPluginCommandDescriptions();
+
   try {
     const abortController = new AbortController();
     // Use --print with a cheap built-in command to trigger system init.
@@ -58,7 +173,8 @@ export async function preloadSlashCommands(workDir, targetId = '__preload__') {
           ctx.sendToServer({
             type: 'slash_commands_update',
             conversationId: targetId,
-            slashCommands
+            slashCommands,
+            slashCommandDescriptions: ctx.slashCommandDescriptions
           });
           console.log(`[Preload] ${targetId}: loaded ${slashCommands.length} slash commands from ${effectiveWorkDir}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.250",
+  "version": "0.1.252",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/subagent.js

@@ -0,0 +1,323 @@
+/**
+ * Sub-Agent JSONL Watcher
+ *
+ * Watches the Claude CLI subagent JSONL session files for real-time messages.
+ * When a Task tool_use is detected in claude.js, this module starts watching
+ * the `{sessionId}/subagents/` directory. New JSONL files are tail-read line
+ * by line, extracting assistant text and tool_use summaries, then forwarded
+ * to the server as `subagent_message` events.
+ *
+ * JSONL location: ~/.claude/projects/{projectFolder}/{sessionId}/subagents/agent-{id}.jsonl
+ * Meta location:  ~/.claude/projects/{projectFolder}/{sessionId}/subagents/agent-{id}.meta.json
+ */
+import { watch, readFileSync, openSync, readSync, closeSync, statSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import ctx from './context.js';
+import { getClaudeProjectsDir, pathToProjectFolder } from './history.js';
+
+// Active watchers: conversationId -> { dirWatcher, fileWatchers: Map<filePath, { bytesRead, watcher }> }
+const activeWatchers = new Map();
+
+/**
+ * Get the subagents directory for a given conversation state.
+ */
+function getSubagentsDir(state) {
+  if (!state.claudeSessionId || !state.workDir) return null;
+  const projectFolder = pathToProjectFolder(state.workDir);
+  return join(getClaudeProjectsDir(), projectFolder, state.claudeSessionId, 'subagents');
+}
+
+/**
+ * Parse agent ID from filename (e.g. "agent-a12015b.jsonl" → "a12015b")
+ */
+function parseAgentId(filename) {
+  const match = filename.match(/^agent-([^.]+)\.jsonl$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Read meta.json for a subagent to get its type (e.g. "Explore")
+ */
+function readAgentMeta(subagentsDir, agentId) {
+  try {
+    const metaPath = join(subagentsDir, `agent-${agentId}.meta.json`);
+    if (existsSync(metaPath)) {
+      const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
+      return { agentType: meta.agentType || 'Task' };
+    }
+  } catch { /* ignore */ }
+  return { agentType: 'Task' };
+}
+
+/**
+ * Extract displayable content from a JSONL message line.
+ * Returns null if the message should be skipped.
+ */
+function parseJsonlLine(line) {
+  try {
+    const data = JSON.parse(line);
+
+    // Only process assistant messages
+    if (data.type !== 'assistant' || !data.message?.content) return null;
+
+    const content = data.message.content;
+    const messages = [];
+
+    // Handle string content (simple text)
+    if (typeof content === 'string') {
+      if (content.trim()) {
+        messages.push({ type: 'text', content: content.trim(), timestamp: data.timestamp });
+      }
+      return messages.length > 0 ? messages : null;
+    }
+
+    // Handle array content (text blocks + tool_use blocks)
+    if (Array.isArray(content)) {
+      for (const block of content) {
+        if (block.type === 'text' && block.text?.trim()) {
+          messages.push({ type: 'text', content: block.text.trim(), timestamp: data.timestamp });
+        } else if (block.type === 'tool_use') {
+          const toolName = block.name || 'Unknown';
+          const summary = formatToolSummary(toolName, block.input);
+          messages.push({ type: 'tool', content: summary, timestamp: data.timestamp, toolName });
+        }
+      }
+      return messages.length > 0 ? messages : null;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a one-liner summary for a tool_use block.
+ */
+function formatToolSummary(toolName, input) {
+  if (!input) return toolName;
+  switch (toolName) {
+    case 'Read':
+      return `Read ${input.file_path || ''}`;
+    case 'Write':
+      return `Write ${input.file_path || ''}`;
+    case 'Edit':
+      return `Edit ${input.file_path || ''}`;
+    case 'Bash':
+      return `Bash: ${(input.command || '').substring(0, 80)}`;
+    case 'Glob':
+      return `Glob ${input.pattern || ''}`;
+    case 'Grep':
+      return `Grep ${input.pattern || ''}`;
+    case 'WebFetch':
+      return `WebFetch ${input.url || ''}`;
+    case 'WebSearch':
+      return `WebSearch: ${input.query || ''}`;
+    default:
+      return toolName;
+  }
+}
+
+/**
+ * Start tail-reading a JSONL file for new lines.
+ */
+function startFileWatcher(filePath, agentId, conversationId, watcherState) {
+  let bytesRead = 0;
+
+  // Read existing content first
+  try {
+    const stat = statSync(filePath);
+    if (stat.size > 0) {
+      const content = readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n').filter(l => l.trim());
+      for (const line of lines) {
+        const parsed = parseJsonlLine(line);
+        if (parsed) {
+          for (const msg of parsed) {
+            ctx.sendToServer({
+              type: 'subagent_message',
+              conversationId,
+              subagentId: agentId,
+              message: msg
+            });
+          }
+        }
+      }
+      bytesRead = stat.size;
+    }
+  } catch { /* file might not be ready yet */ }
+
+  // Watch for new content
+  let pendingPartial = '';
+  const watcher = watch(filePath, () => {
+    try {
+      const stat = statSync(filePath);
+      if (stat.size <= bytesRead) return;
+
+      const fd = openSync(filePath, 'r');
+      const buffer = Buffer.alloc(stat.size - bytesRead);
+      readSync(fd, buffer, 0, buffer.length, bytesRead);
+      closeSync(fd);
+
+      const newContent = pendingPartial + buffer.toString('utf-8');
+
+      // Split into lines; the last element may be a partial line
+      const parts = newContent.split('\n');
+      const maybePartial = parts.pop(); // last element ('' if content ended with \n, or partial line)
+      pendingPartial = maybePartial || '';
+
+      // Advance bytesRead by what we consumed (total read minus what we're holding back)
+      bytesRead = stat.size - Buffer.byteLength(pendingPartial, 'utf-8');
+
+      for (const line of parts) {
+        if (!line.trim()) continue;
+        const parsed = parseJsonlLine(line);
+        if (parsed) {
+          for (const msg of parsed) {
+            ctx.sendToServer({
+              type: 'subagent_message',
+              conversationId,
+              subagentId: agentId,
+              message: msg
+            });
+          }
+        }
+      }
+    } catch { /* ignore read errors during active writes */ }
+  });
+
+  watcherState.fileWatchers.set(filePath, { watcher });
+}
+
+/**
+ * Start watching the subagents directory for a conversation.
+ * Called when a Task tool_use is detected.
+ */
+export function startSubagentWatcher(conversationId, state, toolUseId) {
+  const subagentsDir = getSubagentsDir(state);
+  if (!subagentsDir) return;
+
+  // If already watching this conversation, just record the mapping
+  if (activeWatchers.has(conversationId)) {
+    return;
+  }
+
+  const watcherState = {
+    dirWatcher: null,
+    fileWatchers: new Map(),
+    knownAgents: new Set(),
+    toolUseId,
+    subagentsDir
+  };
+
+  // Function to discover and start watching a new agent JSONL file
+  const discoverAgentFile = (filename) => {
+    const agentId = parseAgentId(filename);
+    if (!agentId || watcherState.knownAgents.has(agentId)) return;
+    watcherState.knownAgents.add(agentId);
+
+    const filePath = join(subagentsDir, filename);
+    const meta = readAgentMeta(subagentsDir, agentId);
+
+    // Read slug from first line of JSONL if available
+    let slug = agentId;
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const firstLine = content.split('\n')[0];
+      if (firstLine) {
+        const data = JSON.parse(firstLine);
+        if (data.slug) slug = data.slug;
+      }
+    } catch { /* use agentId as fallback slug */ }
+
+    // Send subagent_started
+    ctx.sendToServer({
+      type: 'subagent_started',
+      conversationId,
+      subagentId: agentId,
+      slug,
+      subagentType: meta.agentType,
+      parentToolUseId: toolUseId,
+      description: `${meta.agentType} agent`
+    });
+
+    startFileWatcher(filePath, agentId, conversationId, watcherState);
+  };
+
+  // Check for existing files first
+  try {
+    if (existsSync(subagentsDir)) {
+      const files = readdirSync(subagentsDir);
+      for (const file of files) {
+        if (file.endsWith('.jsonl')) {
+          discoverAgentFile(file);
+        }
+      }
+    }
+  } catch { /* dir might not exist yet */ }
+
+  // Watch for new files in the subagents directory
+  // Use an interval-based check because fs.watch on directories can be unreliable
+  const pollInterval = setInterval(() => {
+    try {
+      if (!existsSync(subagentsDir)) return;
+      const files = readdirSync(subagentsDir);
+      for (const file of files) {
+        if (file.endsWith('.jsonl')) {
+          discoverAgentFile(file);
+        }
+      }
+    } catch { /* ignore */ }
+  }, 500);
+
+  watcherState.dirWatcher = pollInterval;
+  activeWatchers.set(conversationId, watcherState);
+}
+
+/**
+ * Stop watching subagents for a conversation's Task tool_use.
+ * Called when the Task tool_result is received.
+ */
+export function stopSubagentWatcher(conversationId, toolUseId) {
+  const watcherState = activeWatchers.get(conversationId);
+  if (!watcherState) return;
+
+  // Only stop if this is the matching tool_use
+  if (watcherState.toolUseId !== toolUseId) return;
+
+  // Send completion for all known agents
+  for (const agentId of watcherState.knownAgents) {
+    ctx.sendToServer({
+      type: 'subagent_completed',
+      conversationId,
+      subagentId: agentId
+    });
+  }
+
+  // Clean up watchers
+  if (watcherState.dirWatcher) {
+    clearInterval(watcherState.dirWatcher);
+  }
+  for (const { watcher } of watcherState.fileWatchers.values()) {
+    try { watcher.close(); } catch { /* ignore */ }
+  }
+
+  activeWatchers.delete(conversationId);
+}
+
+/**
+ * Clean up all watchers for a conversation (e.g. on conversation close).
+ */
+export function cleanupSubagentWatchers(conversationId) {
+  const watcherState = activeWatchers.get(conversationId);
+  if (!watcherState) return;
+
+  if (watcherState.dirWatcher) {
+    clearInterval(watcherState.dirWatcher);
+  }
+  for (const { watcher } of watcherState.fileWatchers.values()) {
+    try { watcher.close(); } catch { /* ignore */ }
+  }
+
+  activeWatchers.delete(conversationId);
+}