@xelauvas/xela-cli 0.3.1 → 0.4.0

package/src/tools/CtxInspectTool/CtxInspectTool.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod/v4'
+import {
+  getStore,
+  renderMessageForSummary,
+} from '../../services/contextCollapse/operations.js'
+import { buildTool } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+
+export const CTX_INSPECT_TOOL_NAME = 'CtxInspect'
+
+const DESCRIPTION = `Look inside the context window's collapsed spans. Earlier parts of this conversation may have been replaced by <collapsed id="..."> summaries to save space. Call with no id to list the collapsed spans (id, size, first line of the summary); call with an id to read that span's full summary, or with id and detail "messages" to read the original messages verbatim (large — only when the summary is not enough). Also lists spans that are staged (summarized, not yet swapped in).`
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    id: z.string().optional().describe('Collapse id from a <collapsed id="..."> placeholder'),
+    detail: z.enum(['summary', 'messages']).optional().describe('What to return for an id (default summary)'),
+    limit: z.number().int().positive().max(200_000).optional().describe('Max characters of original messages to return (default 30000)'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    text: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export const CtxInspectTool = buildTool({
+  name: CTX_INSPECT_TOOL_NAME,
+  searchHint: 'read summaries or originals of collapsed conversation spans',
+  maxResultSizeChars: 250_000,
+  userFacingName: () => 'Context inspect',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  async checkPermissions(input) {
+    return { behavior: 'allow', updatedInput: input }
+  },
+  async description({ id }) {
+    return id ? `Inspect collapsed span ${id}` : 'List collapsed spans'
+  },
+  async prompt() {
+    return DESCRIPTION
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return { tool_use_id: toolUseID, type: 'tool_result', content: output.text }
+  },
+  renderToolUseMessage(input: { id?: string; detail?: string }) {
+    return input.id ? `${input.id}${input.detail === 'messages' ? ' (messages)' : ''}` : 'list'
+  },
+  renderToolResultMessage(output: Output) {
+    return output.text.split('\n')[0]?.slice(0, 100) ?? ''
+  },
+  async call({ id, detail, limit }) {
+    const store = getStore()
+    if (!id) {
+      const lines: string[] = []
+      if (store.commits.length === 0 && store.staged.length === 0) {
+        lines.push('No collapsed spans yet. The conversation is still fully in context.')
+      }
+      if (store.commits.length > 0) {
+        lines.push(`Collapsed spans (${store.commits.length}):`)
+        for (const c of store.commits) {
+          const first = c.summary.split('\n').find(l => l.trim()) ?? ''
+          lines.push(`- id ${c.collapseId}: ${c.archived.length} messages — ${first.slice(0, 140)}`)
+        }
+      }
+      if (store.staged.length > 0) {
+        lines.push(`Staged (summarized, not yet swapped in): ${store.staged.length}`)
+        for (const s of store.staged) {
+          lines.push(`- ${s.startUuid.slice(0, 8)}..${s.endUuid.slice(0, 8)}: ${s.summary.split('\n')[0]?.slice(0, 120) ?? ''}`)
+        }
+      }
+      return { data: { text: lines.join('\n') } }
+    }
+    const commit = store.commits.find(c => c.collapseId === id || c.collapseId === id.padStart(16, '0'))
+    if (!commit) {
+      return { data: { text: `No collapsed span with id ${id}. Call without an id to list them.` } }
+    }
+    if (detail === 'messages') {
+      if (commit.archived.length === 0) {
+        return { data: { text: `The original messages of span ${id} are not loaded in this session (they live in the transcript). Summary:\n\n${commit.summary}` } }
+      }
+      const max = limit ?? 30_000
+      let text = commit.archived.map(renderMessageForSummary).join('\n\n')
+      if (text.length > max) text = text.slice(0, max) + `\n… (${text.length - max} more characters)`
+      return { data: { text: `Original messages of span ${id} (${commit.archived.length}):\n\n${text}` } }
+    }
+    return { data: { text: `Summary of span ${id} (${commit.archived.length} messages):\n\n${commit.summary}` } }
+  },
+})

package/src/tools/DiscoverSkillsTool/DiscoverSkillsTool.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod/v4'
+import type { Command } from '../../commands.js'
+import { searchSkills } from '../../services/skillSearch/localSearch.js'
+import { buildTool } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { DESCRIPTION, DISCOVER_SKILLS_TOOL_NAME } from './prompt.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    description: z.string().describe('What you are about to do, specifically'),
+    limit: z.number().int().positive().max(10).optional().describe('Max results (default 5)'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    skills: z.array(z.object({ name: z.string(), description: z.string() })),
+    message: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export const DiscoverSkillsTool = buildTool({
+  name: DISCOVER_SKILLS_TOOL_NAME,
+  searchHint: 'find installed skills relevant to a task',
+  maxResultSizeChars: 20_000,
+  userFacingName: () => 'Discover skills',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  async checkPermissions(input) {
+    return { behavior: 'allow', updatedInput: input }
+  },
+  async description({ description }) {
+    return `Find skills for: ${description.slice(0, 60)}`
+  },
+  async prompt() {
+    return DESCRIPTION
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content:
+        output.skills.length === 0
+          ? output.message
+          : output.skills.map(s => `- ${s.name}: ${s.description}`).join('\n') + `\n\nInvoke with Skill("<name>").`,
+    }
+  },
+  renderToolUseMessage(input: { description?: string }) {
+    return input.description ?? ''
+  },
+  renderToolResultMessage(output: Output) {
+    return output.skills.length ? output.skills.map(s => s.name).join(', ') : 'no matching skills'
+  },
+  async call({ description, limit }, context) {
+    const commands = ((context.options as { commands?: Command[] } | undefined)?.commands ?? []).filter(c => c.type === 'prompt')
+    const hits = searchSkills(description, commands, { limit: limit ?? 5, minScore: 1.5 })
+    for (const h of hits) context.discoveredSkillNames?.add(h.name)
+    return {
+      data: {
+        skills: hits.map(h => ({ name: h.name, description: h.description })),
+        message: hits.length ? `${hits.length} skills match.` : 'No installed skill matches that description.',
+      },
+    }
+  },
+})

package/src/tools/DiscoverSkillsTool/prompt.ts

@@ -0,0 +1,3 @@
+export const DISCOVER_SKILLS_TOOL_NAME = 'DiscoverSkills'
+
+export const DESCRIPTION = `Find installed skills relevant to what you are about to do. Relevant skills are surfaced automatically each turn as "Skills relevant to your task" reminders; call this when you are starting something those did not cover (a mid-task pivot, an unusual workflow, a multi-step plan) with a specific description of the work. Returns skill names and descriptions; invoke one with Skill("<name>").`

package/src/tools/ListPeersTool/ListPeersTool.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod/v4'
+import { buildTool } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { listAllLiveSessions, type LiveSession } from '../../utils/udsClient.js'
+
+export const LIST_PEERS_TOOL_NAME = 'ListPeers'
+
+const DESCRIPTION = `List the other Xela sessions running on this machine that can receive messages. Each peer has a socket address; send to it with SendMessage({ to: "uds:<socket path>", message: "..." }). The message arrives in that session as a user prompt wrapped in <cross-session-message from="uds:...">; the peer replies by sending to the from address. Use it to coordinate work across projects or hand a question to a session that has the right context.`
+
+const inputSchema = lazySchema(() => z.strictObject({}))
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    peers: z.array(
+      z.object({
+        address: z.string(),
+        pid: z.number(),
+        cwd: z.string().optional(),
+        name: z.string().optional(),
+        kind: z.string().optional(),
+        startedAt: z.number().optional(),
+      }),
+    ),
+    self: z.string().optional(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export const ListPeersTool = buildTool({
+  name: LIST_PEERS_TOOL_NAME,
+  searchHint: 'discover other local sessions to message',
+  maxResultSizeChars: 20_000,
+  userFacingName: () => 'List peers',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  async checkPermissions(input) {
+    return { behavior: 'allow', updatedInput: input }
+  },
+  async description() {
+    return 'List other local sessions'
+  },
+  async prompt() {
+    return DESCRIPTION
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    const lines =
+      output.peers.length === 0
+        ? ['No other reachable sessions on this machine.']
+        : output.peers.map(
+            p =>
+              `- ${p.address}  pid ${p.pid}${p.name ? `  name ${p.name}` : ''}${p.cwd ? `  cwd ${p.cwd}` : ''}${p.kind && p.kind !== 'interactive' ? `  (${p.kind})` : ''}`,
+          )
+    if (output.self) lines.push(`(this session: uds:${output.self})`)
+    return { tool_use_id: toolUseID, type: 'tool_result', content: lines.join('\n') }
+  },
+  renderToolUseMessage() {
+    return ''
+  },
+  renderToolResultMessage(output: Output) {
+    return `${output.peers.length} peer${output.peers.length === 1 ? '' : 's'}`
+  },
+  async call() {
+    const sessions = await listAllLiveSessions()
+    const self = sessions.find(s => s.isSelf)
+    const peers = sessions
+      .filter((s): s is LiveSession & { messagingSocketPath: string } => !s.isSelf && s.reachable && !!s.messagingSocketPath)
+      .map(s => ({
+        address: `uds:${s.messagingSocketPath}`,
+        pid: s.pid,
+        cwd: s.cwd,
+        name: s.name,
+        kind: s.kind,
+        startedAt: s.startedAt,
+      }))
+    return { data: { peers, self: self?.messagingSocketPath } }
+  },
+})

package/src/tools/MCPTool/MCPTool.ts

@@ -59,6 +59,12 @@ export const MCPTool = buildTool({
       message: 'MCPTool requires permission.',
     }
   },
+  // MCP tools can do anything (context-mode's ctx_execute runs shell commands),
+  // so auto mode must classify them instead of skipping them as irrelevant
+  toAutoClassifierInput(input) {
+    const text = JSON.stringify(input)
+    return text.length > 4000 ? text.slice(0, 4000) + '…' : text
+  },
   renderToolUseMessage,
   // Overridden in mcpClient.ts
   userFacingName: () => 'mcp',

package/src/tools/MonitorTool/MonitorTool.ts

@@ -0,0 +1,273 @@
+import { z } from 'zod/v4'
+import { spawnShellTask } from '../../tasks/LocalShellTask/LocalShellTask.js'
+import { killTask } from '../../tasks/LocalShellTask/killShellTasks.js'
+import { spawnMonitorMcpTask } from '../../tasks/MonitorMcpTask/MonitorMcpTask.js'
+import { buildTool } from '../../Tool.js'
+import type { AgentId } from '../../types/ids.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { enqueuePendingNotification } from '../../utils/messageQueueManager.js'
+import { exec } from '../../utils/Shell.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+import { getTaskOutputPath } from '../../utils/task/diskOutput.js'
+import { TaskOutput } from '../../utils/task/TaskOutput.js'
+import { tailFile } from '../../utils/fsOperations.js'
+import { bashToolHasPermission } from '../BashTool/bashPermissions.js'
+import { createEventEmitter, MAX_EVENTS_PER_MINUTE } from './events.js'
+import { DESCRIPTION, MONITOR_TOOL_NAME } from './prompt.js'
+import { renderToolResultMessage, renderToolUseMessage } from './UI.js'
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000
+const MAX_TIMEOUT_MS = 30 * 60 * 1000
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    command: z
+      .string()
+      .optional()
+      .describe(
+        'Shell command or script. Each stdout line is an event; exit ends the watch.',
+      ),
+    ws: z
+      .object({
+        url: z.string(),
+        protocols: z.array(z.string()).optional(),
+      })
+      .optional()
+      .describe(
+        'WebSocket to open. Each text frame is an event; socket close ends the watch. Cannot be combined with command.',
+      ),
+    description: z
+      .string()
+      .describe(
+        'Short human-readable description of what you are monitoring (shown in notifications).',
+      ),
+    timeout_ms: z
+      .number()
+      .optional()
+      .describe(
+        'Kill the monitor after this deadline. Default 300000ms, at most 1800000ms. You are notified at expiry and can re-arm.',
+      ),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+export type MonitorInput = z.infer<InputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    taskId: z.string(),
+    description: z.string(),
+    source: z.enum(['command', 'ws']),
+    outputFile: z.string(),
+    timeoutMs: z.number(),
+    message: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export function clampTimeout(timeoutMs: number | undefined): number {
+  if (!timeoutMs || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return DEFAULT_TIMEOUT_MS
+  }
+  return Math.min(timeoutMs, MAX_TIMEOUT_MS)
+}
+
+export const MonitorTool = buildTool({
+  name: MONITOR_TOOL_NAME,
+  searchHint: 'watch a log, process or socket and get notified on each event',
+  maxResultSizeChars: 100_000,
+  userFacingName: () => 'Monitor',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return false
+  },
+  toAutoClassifierInput(input) {
+    return input.command ?? (input.ws ? `ws ${input.ws.url}` : '')
+  },
+  async validateInput({ command, ws, timeout_ms }) {
+    if (!command && !ws) {
+      return {
+        result: false,
+        message: 'Provide either command or ws',
+        errorCode: 1,
+      }
+    }
+    if (command && ws) {
+      return {
+        result: false,
+        message: 'command and ws cannot be combined',
+        errorCode: 1,
+      }
+    }
+    if (ws && !/^wss?:\/\//.test(ws.url)) {
+      return {
+        result: false,
+        message: 'ws.url must start with ws:// or wss://',
+        errorCode: 1,
+      }
+    }
+    if (timeout_ms !== undefined && timeout_ms < 1000) {
+      return {
+        result: false,
+        message: 'timeout_ms must be at least 1000',
+        errorCode: 1,
+      }
+    }
+    return { result: true }
+  },
+  async checkPermissions(input, context) {
+    // A shell monitor is a Bash command: same rules, same prompts
+    if (input.command) {
+      const result = await bashToolHasPermission(
+        { command: input.command, description: input.description },
+        context,
+      )
+      // Pass the monitor input through, not the Bash-shaped input
+      if (result.behavior === 'allow') {
+        return { ...result, updatedInput: input }
+      }
+      return result
+    }
+    return {
+      behavior: 'ask',
+      message: `Open WebSocket ${input.ws?.url ?? ''}`,
+    }
+  },
+  async description({ description }) {
+    return description
+  },
+  async prompt() {
+    return DESCRIPTION
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: jsonStringify(output),
+    }
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  async call(input, context) {
+    const { abortController, getAppState, setAppState } = context
+    const toolUseId = (context as { toolUseId?: string }).toolUseId
+    const agentId = (context as { agentId?: AgentId }).agentId
+    const timeoutMs = clampTimeout(input.timeout_ms)
+    const description = input.description
+
+    if (input.ws) {
+      const handle = await spawnMonitorMcpTask(
+        {
+          url: input.ws.url,
+          protocols: input.ws.protocols,
+          description,
+          timeoutMs,
+          toolUseId,
+          agentId,
+        },
+        { abortController, getAppState, setAppState },
+      )
+      return {
+        data: {
+          taskId: handle.taskId,
+          description,
+          source: 'ws' as const,
+          outputFile: getTaskOutputPath(handle.taskId),
+          timeoutMs,
+          message: `Monitor "${description}" armed on ${input.ws.url} (task ${handle.taskId}, expires in ${Math.round(timeoutMs / 1000)}s). Each text frame arrives as a notification.`,
+        },
+      }
+    }
+
+    const command = input.command!
+    let emitter: ReturnType<typeof createEventEmitter> | null = null
+    let seenLines = 0
+    let taskId: string | null = null
+
+    // The poller hands over the last ~100 lines plus the total line count, so
+    // new lines are the tail slice beyond what was already delivered.
+    function deliver(content: string, totalLines: number): void {
+      if (!emitter || totalLines <= seenLines) return
+      const lines = content.split('\n')
+      if (lines[lines.length - 1] === '') lines.pop()
+      const fresh = lines.slice(Math.max(0, lines.length - (totalLines - seenLines)))
+      seenLines = totalLines
+      for (const line of fresh) {
+        if (line.trim() === '') continue
+        if (!emitter.push(line)) break
+      }
+    }
+
+    const shellCommand = await exec(command, abortController.signal, 'bash', {
+      timeout: timeoutMs,
+      onProgress(_lastLines, allLines, totalLines) {
+        if (process.env.XELA_MONITOR_DEBUG) process.stderr.write(`[monitor] progress total=${totalLines} seen=${seenLines}\n`)
+        deliver(allLines, totalLines)
+      },
+    })
+
+    const handle = await spawnShellTask(
+      {
+        command,
+        description,
+        shellCommand,
+        toolUseId,
+        agentId,
+        kind: 'monitor',
+        timeout: timeoutMs,
+      },
+      { abortController, getAppState, setAppState },
+    )
+    taskId = handle.taskId
+    emitter = createEventEmitter({
+      taskId,
+      description,
+      toolUseId,
+      agentId,
+      onFlood: () => {
+        enqueuePendingNotification({
+          value: `Monitor "${description}" (task ${taskId}) produced more than ${MAX_EVENTS_PER_MINUTE} events per minute and was stopped. Restart it with a tighter filter.`,
+          mode: 'task-notification',
+          priority: 'next',
+          agentId,
+        })
+        if (taskId) killTask(taskId, setAppState)
+      },
+    })
+
+    // Progress callbacks only fire while the shared poller watches this task
+    const outputId = shellCommand.taskOutput.taskId
+    TaskOutput.startPolling(outputId)
+    void shellCommand.result.then(async () => {
+      TaskOutput.stopPolling(outputId)
+      // The script may exit between two polls: deliver whatever the last
+      // tick missed, then flush so the events precede the "stream ended" notice
+      try {
+        const { content } = await tailFile(getTaskOutputPath(outputId), 256 * 1024)
+        const total = content.split('\n').filter((l, i, a) => !(i === a.length - 1 && l === '')).length
+        deliver(content, Math.max(total, seenLines))
+      } catch {
+        // output file may be gone already
+      }
+      emitter?.flush()
+    })
+
+    return {
+      data: {
+        taskId,
+        description,
+        source: 'command' as const,
+        outputFile: getTaskOutputPath(taskId),
+        timeoutMs,
+        message: `Monitor "${description}" armed (task ${taskId}, expires in ${Math.round(timeoutMs / 1000)}s). Each stdout line arrives as a notification; the script exiting ends the watch.`,
+      },
+    }
+  },
+})

package/src/tools/MonitorTool/UI.tsx

@@ -0,0 +1,25 @@
+import React from 'react'
+import { MessageResponse } from '../../components/MessageResponse.js'
+import { Text } from '../../ink.js'
+import type { MonitorInput, Output } from './MonitorTool.js'
+
+export function renderToolUseMessage(
+  input: Partial<MonitorInput>,
+  { verbose }: { verbose: boolean },
+): React.ReactNode {
+  const source = input.command ?? input.ws?.url ?? ''
+  const shown =
+    verbose || source.length <= 80 ? source : source.slice(0, 77) + '…'
+  return input.description ? `${input.description} · ${shown}` : shown
+}
+
+export function renderToolResultMessage(output: Output): React.ReactNode {
+  return (
+    <MessageResponse>
+      <Text>
+        Monitor armed · {output.description} · task {output.taskId} · expires
+        in {Math.round(output.timeoutMs / 1000)}s
+      </Text>
+    </MessageResponse>
+  )
+}

package/src/tools/MonitorTool/events.ts

@@ -0,0 +1,84 @@
+import {
+  OUTPUT_FILE_TAG,
+  SUMMARY_TAG,
+  TASK_ID_TAG,
+  TASK_NOTIFICATION_TAG,
+  TOOL_USE_ID_TAG,
+} from '../../constants/xml.js'
+import type { AgentId } from '../../types/ids.js'
+import { enqueuePendingNotification } from '../../utils/messageQueueManager.js'
+import { getTaskOutputPath } from '../../utils/task/diskOutput.js'
+import { escapeXml } from '../../utils/xml.js'
+
+// Lines arriving within this window are delivered as one notification
+export const EVENT_BATCH_MS = 200
+// A monitor emitting more than this many notifications per minute is stopped:
+// the filter is too wide and would flood the conversation
+export const MAX_EVENTS_PER_MINUTE = 30
+
+/**
+ * Builds the batching event emitter shared by the shell and WebSocket
+ * monitors. Lines pushed within EVENT_BATCH_MS become one task notification
+ * (no <status> tag, so the task stays open). Returns `false` from push() once
+ * the rate limit tripped, so the caller can stop the source.
+ */
+export function createEventEmitter(opts: {
+  taskId: string
+  description: string
+  toolUseId?: string
+  agentId?: AgentId
+  onFlood: () => void
+}): { push: (line: string) => boolean; flush: () => void } {
+  const { taskId, description, toolUseId, agentId, onFlood } = opts
+  const outputPath = getTaskOutputPath(taskId)
+  const toolUseIdLine = toolUseId
+    ? `\n<${TOOL_USE_ID_TAG}>${toolUseId}</${TOOL_USE_ID_TAG}>`
+    : ''
+  let pending: string[] = []
+  let timer: NodeJS.Timeout | null = null
+  let flooded = false
+  const recent: number[] = []
+
+  function flush(): void {
+    timer = null
+    if (pending.length === 0) return
+    const lines = pending
+    pending = []
+    const now = Date.now()
+    recent.push(now)
+    while (recent.length > 0 && now - recent[0]! > 60_000) recent.shift()
+    if (recent.length > MAX_EVENTS_PER_MINUTE && !flooded) {
+      flooded = true
+      onFlood()
+      return
+    }
+    const summary = `Monitor "${description}": ${lines.length === 1 ? '1 event' : `${lines.length} events`}`
+    const message = `<${TASK_NOTIFICATION_TAG}>
+<${TASK_ID_TAG}>${taskId}</${TASK_ID_TAG}>${toolUseIdLine}
+<${OUTPUT_FILE_TAG}>${outputPath}</${OUTPUT_FILE_TAG}>
+<${SUMMARY_TAG}>${escapeXml(summary)}</${SUMMARY_TAG}>
+</${TASK_NOTIFICATION_TAG}>
+${lines.join('\n')}`
+    if (process.env.XELA_MONITOR_DEBUG) process.stderr.write(`[monitor] flush ${lines.length} lines -> notification\n`)
+    enqueuePendingNotification({
+      value: message,
+      mode: 'task-notification',
+      priority: 'next',
+      agentId,
+    })
+  }
+
+  return {
+    push(line: string): boolean {
+      if (flooded) return false
+      pending.push(line)
+      if (!timer) {
+        timer = setTimeout(flush, EVENT_BATCH_MS)
+        timer.unref()
+      }
+      return true
+    },
+    flush,
+  }
+}
+