@xelauvas/xela-cli 0.3.0 → 0.4.0

package/src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts

@@ -0,0 +1,301 @@
+import {
+  OUTPUT_FILE_TAG,
+  STATUS_TAG,
+  SUMMARY_TAG,
+  TASK_ID_TAG,
+  TASK_NOTIFICATION_TAG,
+  TOOL_USE_ID_TAG,
+} from '../../constants/xml.js'
+import type { AppState } from '../../state/AppState.js'
+import {
+  createTaskStateBase,
+  generateTaskId,
+  type SetAppState,
+  type Task,
+  type TaskStateBase,
+} from '../../Task.js'
+import type { AgentId } from '../../types/ids.js'
+import { registerCleanup } from '../../utils/cleanupRegistry.js'
+import { enqueuePendingNotification } from '../../utils/messageQueueManager.js'
+import {
+  appendTaskOutput,
+  getTaskOutputPath,
+  initTaskOutput,
+} from '../../utils/task/diskOutput.js'
+import { registerTask, updateTaskState } from '../../utils/task/framework.js'
+import { escapeXml } from '../../utils/xml.js'
+
+export type WorkflowAgentStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'skipped'
+
+export type WorkflowAgentRecord = {
+  id: string
+  index: number
+  label: string
+  phase?: string
+  status: WorkflowAgentStatus
+  startTime: number
+  endTime?: number
+  error?: string
+  resultPreview?: string
+  /** Set when the user asked for a retry from the task panel. */
+  retryRequested?: boolean
+}
+
+export type WorkflowPhaseRecord = {
+  title: string
+  detail?: string
+  status: 'pending' | 'running' | 'completed'
+}
+
+/**
+ * Per-agent controller, kept outside the (immutable) task state so skip/retry
+ * from the UI can reach the running agent.
+ */
+export type WorkflowAgentController = {
+  abortController: AbortController
+  retry: boolean
+}
+
+export type LocalWorkflowTaskState = TaskStateBase & {
+  type: 'local_workflow'
+  runId: string
+  name: string
+  workflowDescription: string
+  args?: unknown
+  phases: WorkflowPhaseRecord[]
+  currentPhase?: string
+  agents: WorkflowAgentRecord[]
+  result?: unknown
+  error?: string
+  abortController: AbortController
+  agentControllers: Map<string, WorkflowAgentController>
+  isBackgrounded: boolean
+  agentId?: AgentId
+  unregisterCleanup?: () => void
+}
+
+export function isLocalWorkflowTask(
+  task: unknown,
+): task is LocalWorkflowTaskState {
+  return (
+    typeof task === 'object' &&
+    task !== null &&
+    'type' in task &&
+    (task as { type: unknown }).type === 'local_workflow'
+  )
+}
+
+export const LocalWorkflowTask: Task = {
+  name: 'LocalWorkflowTask',
+  type: 'local_workflow',
+  async kill(taskId, setAppState) {
+    killWorkflowTask(taskId, setAppState)
+  },
+}
+
+export function killWorkflowTask(
+  taskId: string,
+  setAppState: SetAppState,
+): void {
+  let state: LocalWorkflowTaskState | undefined
+  setAppState(prev => {
+    const t = prev.tasks?.[taskId]
+    if (isLocalWorkflowTask(t)) state = t
+    return prev
+  })
+  if (!state) return
+  for (const ctrl of state.agentControllers.values()) ctrl.abortController.abort()
+  state.abortController.abort()
+  finishWorkflow(taskId, 'killed', undefined, 'Stopped by user', setAppState)
+}
+
+export function skipWorkflowAgent(
+  taskId: string,
+  agentId: string,
+  setAppState: SetAppState,
+): void {
+  let ctrl: WorkflowAgentController | undefined
+  setAppState(prev => {
+    const t = prev.tasks?.[taskId]
+    if (isLocalWorkflowTask(t)) ctrl = t.agentControllers.get(agentId)
+    return prev
+  })
+  if (!ctrl) return
+  ctrl.retry = false
+  ctrl.abortController.abort()
+}
+
+export function retryWorkflowAgent(
+  taskId: string,
+  agentId: string,
+  setAppState: SetAppState,
+): void {
+  let ctrl: WorkflowAgentController | undefined
+  setAppState(prev => {
+    const t = prev.tasks?.[taskId]
+    if (isLocalWorkflowTask(t)) ctrl = t.agentControllers.get(agentId)
+    return prev
+  })
+  if (!ctrl) return
+  ctrl.retry = true
+  ctrl.abortController.abort()
+}
+
+export function updateWorkflowAgent(
+  taskId: string,
+  agentId: string,
+  patch: Partial<WorkflowAgentRecord>,
+  setAppState: SetAppState,
+): void {
+  updateTaskState<LocalWorkflowTaskState>(taskId, setAppState, t => ({
+    ...t,
+    agents: t.agents.map(a => (a.id === agentId ? { ...a, ...patch } : a)),
+  }))
+}
+
+export function addWorkflowAgent(
+  taskId: string,
+  record: WorkflowAgentRecord,
+  controller: WorkflowAgentController,
+  setAppState: SetAppState,
+): void {
+  updateTaskState<LocalWorkflowTaskState>(taskId, setAppState, t => {
+    t.agentControllers.set(record.id, controller)
+    return { ...t, agents: [...t.agents, record] }
+  })
+}
+
+export function setWorkflowPhase(
+  taskId: string,
+  title: string,
+  setAppState: SetAppState,
+): void {
+  updateTaskState<LocalWorkflowTaskState>(taskId, setAppState, t => {
+    const known = t.phases.some(p => p.title === title)
+    const phases = (known ? t.phases : [...t.phases, { title, status: 'pending' as const }]).map(
+      p => {
+        if (p.title === title) return { ...p, status: 'running' as const }
+        if (p.status === 'running') return { ...p, status: 'completed' as const }
+        return p
+      },
+    )
+    return { ...t, phases, currentPhase: title }
+  })
+}
+
+export function finishWorkflow(
+  taskId: string,
+  status: 'completed' | 'failed' | 'killed',
+  result: unknown,
+  error: string | undefined,
+  setAppState: SetAppState,
+): void {
+  let snapshot: LocalWorkflowTaskState | null = null
+  updateTaskState<LocalWorkflowTaskState>(taskId, setAppState, t => {
+    if (t.status !== 'running' && t.status !== 'pending') return t
+    t.unregisterCleanup?.()
+    const next: LocalWorkflowTaskState = {
+      ...t,
+      status,
+      result,
+      error,
+      endTime: Date.now(),
+      currentPhase: undefined,
+      phases: t.phases.map(p =>
+        p.status === 'running' ? { ...p, status: 'completed' as const } : p,
+      ),
+      unregisterCleanup: undefined,
+    }
+    snapshot = next
+    return next
+  })
+  if (!snapshot) return
+  const s = snapshot as LocalWorkflowTaskState
+  let shouldEnqueue = false
+  updateTaskState<LocalWorkflowTaskState>(taskId, setAppState, t => {
+    if (t.notified) return t
+    shouldEnqueue = true
+    return { ...t, notified: true }
+  })
+  if (!shouldEnqueue) return
+  const done = s.agents.filter(a => a.status === 'completed').length
+  const summary =
+    status === 'completed'
+      ? `Workflow "${s.name}" completed (${done}/${s.agents.length} agents succeeded)`
+      : status === 'failed'
+        ? `Workflow "${s.name}" failed: ${error ?? 'unknown error'}`
+        : `Workflow "${s.name}" stopped`
+  const toolUseIdLine = s.toolUseId
+    ? `\n<${TOOL_USE_ID_TAG}>${s.toolUseId}</${TOOL_USE_ID_TAG}>`
+    : ''
+  let resultText = ''
+  if (status === 'completed') {
+    try {
+      resultText = JSON.stringify(result, null, 2) ?? ''
+    } catch {
+      resultText = String(result)
+    }
+    if (resultText.length > 20_000) {
+      resultText = resultText.slice(0, 20_000) + `\n… (truncated; full result in ${getTaskOutputPath(taskId)})`
+    }
+  }
+  enqueuePendingNotification({
+    value: `<${TASK_NOTIFICATION_TAG}>
+<${TASK_ID_TAG}>${taskId}</${TASK_ID_TAG}>${toolUseIdLine}
+<${OUTPUT_FILE_TAG}>${getTaskOutputPath(taskId)}</${OUTPUT_FILE_TAG}>
+<${STATUS_TAG}>${status}</${STATUS_TAG}>
+<${SUMMARY_TAG}>${escapeXml(summary)}</${SUMMARY_TAG}>
+</${TASK_NOTIFICATION_TAG}>${resultText ? `\nWorkflow result:\n${resultText}` : ''}`,
+    mode: 'task-notification',
+    priority: 'next',
+    agentId: s.agentId,
+  })
+}
+
+export async function registerWorkflowTask(
+  input: {
+    name: string
+    description: string
+    args?: unknown
+    phases: Array<{ title: string; detail?: string }>
+    toolUseId?: string
+    agentId?: AgentId
+    isBackgrounded: boolean
+  },
+  setAppState: SetAppState,
+): Promise<LocalWorkflowTaskState> {
+  const taskId = generateTaskId('local_workflow')
+  await initTaskOutput(taskId)
+  const abortController = new AbortController()
+  const unregisterCleanup = registerCleanup(async () => {
+    abortController.abort()
+  })
+  const state: LocalWorkflowTaskState = {
+    ...createTaskStateBase(taskId, 'local_workflow', input.description, input.toolUseId),
+    type: 'local_workflow',
+    status: 'running',
+    runId: `wf_${taskId}`,
+    name: input.name,
+    workflowDescription: input.description,
+    args: input.args,
+    phases: input.phases.map(p => ({ ...p, status: 'pending' as const })),
+    agents: [],
+    abortController,
+    agentControllers: new Map(),
+    isBackgrounded: input.isBackgrounded,
+    agentId: input.agentId,
+    unregisterCleanup,
+  }
+  registerTask(state, setAppState)
+  appendTaskOutput(taskId, `[workflow] ${input.name}: ${input.description}\n`)
+  return state
+}
+
+export function getWorkflowTasks(state: AppState): LocalWorkflowTaskState[] {
+  return Object.values(state.tasks ?? {}).filter(isLocalWorkflowTask)
+}

package/src/tasks/MonitorMcpTask/MonitorMcpTask.ts

@@ -0,0 +1,273 @@
+import WebSocket from 'ws'
+import {
+  OUTPUT_FILE_TAG,
+  STATUS_TAG,
+  SUMMARY_TAG,
+  TASK_ID_TAG,
+  TASK_NOTIFICATION_TAG,
+  TOOL_USE_ID_TAG,
+} from '../../constants/xml.js'
+import type { AppState } from '../../state/AppState.js'
+import {
+  createTaskStateBase,
+  generateTaskId,
+  type SetAppState,
+  type Task,
+  type TaskContext,
+  type TaskHandle,
+  type TaskStateBase,
+} from '../../Task.js'
+import { createEventEmitter } from '../../tools/MonitorTool/events.js'
+import type { AgentId } from '../../types/ids.js'
+import { registerCleanup } from '../../utils/cleanupRegistry.js'
+import { enqueuePendingNotification } from '../../utils/messageQueueManager.js'
+import {
+  appendTaskOutput,
+  getTaskOutputPath,
+  initTaskOutput,
+} from '../../utils/task/diskOutput.js'
+import { registerTask, updateTaskState } from '../../utils/task/framework.js'
+import { escapeXml } from '../../utils/xml.js'
+
+/**
+ * WebSocket monitor: each text frame is an event, socket close ends the
+ * watch. Called "monitor_mcp" for compatibility with the task type the rest
+ * of the app knows about (dialogs, pills, kill paths).
+ */
+export type MonitorMcpTaskState = TaskStateBase & {
+  type: 'monitor_mcp'
+  url: string
+  eventCount: number
+  closeCode?: number
+  error?: string
+  agentId?: AgentId
+  socket?: WebSocket | null
+  timeoutId?: NodeJS.Timeout
+  unregisterCleanup?: () => void
+}
+
+export function isMonitorMcpTask(task: unknown): task is MonitorMcpTaskState {
+  return (
+    typeof task === 'object' &&
+    task !== null &&
+    'type' in task &&
+    (task as { type: unknown }).type === 'monitor_mcp'
+  )
+}
+
+export const MonitorMcpTask: Task = {
+  name: 'MonitorMcpTask',
+  type: 'monitor_mcp',
+  async kill(taskId, setAppState) {
+    killMonitorMcp(taskId, setAppState)
+  },
+}
+
+function notifyTerminal(
+  task: MonitorMcpTaskState,
+  status: 'completed' | 'failed' | 'killed',
+  summary: string,
+  setAppState: SetAppState,
+): void {
+  let shouldEnqueue = false
+  updateTaskState<MonitorMcpTaskState>(task.id, setAppState, t => {
+    if (t.notified) return t
+    shouldEnqueue = true
+    return { ...t, notified: true }
+  })
+  if (!shouldEnqueue) return
+  const toolUseIdLine = task.toolUseId
+    ? `\n<${TOOL_USE_ID_TAG}>${task.toolUseId}</${TOOL_USE_ID_TAG}>`
+    : ''
+  enqueuePendingNotification({
+    value: `<${TASK_NOTIFICATION_TAG}>
+<${TASK_ID_TAG}>${task.id}</${TASK_ID_TAG}>${toolUseIdLine}
+<${OUTPUT_FILE_TAG}>${getTaskOutputPath(task.id)}</${OUTPUT_FILE_TAG}>
+<${STATUS_TAG}>${status}</${STATUS_TAG}>
+<${SUMMARY_TAG}>${escapeXml(summary)}</${SUMMARY_TAG}>
+</${TASK_NOTIFICATION_TAG}>`,
+    mode: 'task-notification',
+    priority: 'next',
+    agentId: task.agentId,
+  })
+}
+
+function finish(
+  taskId: string,
+  status: 'completed' | 'failed' | 'killed',
+  summaryFor: (t: MonitorMcpTaskState) => string,
+  patch: Partial<MonitorMcpTaskState>,
+  setAppState: SetAppState,
+): void {
+  let snapshot: MonitorMcpTaskState | null = null
+  updateTaskState<MonitorMcpTaskState>(taskId, setAppState, t => {
+    if (t.status !== 'running' && t.status !== 'pending') return t
+    if (t.timeoutId) clearTimeout(t.timeoutId)
+    t.unregisterCleanup?.()
+    const next: MonitorMcpTaskState = {
+      ...t,
+      ...patch,
+      status,
+      endTime: Date.now(),
+      socket: null,
+      timeoutId: undefined,
+      unregisterCleanup: undefined,
+    }
+    snapshot = next
+    return next
+  })
+  if (snapshot) {
+    const s = snapshot as MonitorMcpTaskState
+    notifyTerminal(s, status, summaryFor(s), setAppState)
+  }
+}
+
+export function killMonitorMcp(taskId: string, setAppState: SetAppState): void {
+  let socket: WebSocket | null | undefined
+  setAppState(prev => {
+    const t = prev.tasks?.[taskId]
+    if (isMonitorMcpTask(t)) socket = t.socket
+    return prev
+  })
+  try {
+    socket?.close(1000, 'stopped')
+  } catch {
+    // already closed
+  }
+  finish(
+    taskId,
+    'killed',
+    t => `Monitor "${t.description}" stopped`,
+    {},
+    setAppState,
+  )
+}
+
+export function killMonitorMcpTasksForAgent(
+  agentId: AgentId,
+  getAppState: () => AppState,
+  setAppState: SetAppState,
+): void {
+  const tasks = getAppState().tasks ?? {}
+  for (const task of Object.values(tasks)) {
+    if (
+      isMonitorMcpTask(task) &&
+      task.agentId === agentId &&
+      (task.status === 'running' || task.status === 'pending')
+    ) {
+      killMonitorMcp(task.id, setAppState)
+    }
+  }
+}
+
+export async function spawnMonitorMcpTask(
+  input: {
+    url: string
+    protocols?: string[]
+    description: string
+    timeoutMs: number
+    toolUseId?: string
+    agentId?: AgentId
+  },
+  context: TaskContext,
+): Promise<TaskHandle> {
+  const { url, protocols, description, timeoutMs, toolUseId, agentId } = input
+  const { setAppState } = context
+  const taskId = generateTaskId('monitor_mcp')
+  await initTaskOutput(taskId)
+
+  const unregisterCleanup = registerCleanup(async () => {
+    killMonitorMcp(taskId, setAppState)
+  })
+
+  const socket = new WebSocket(url, protocols)
+  const timeoutId = setTimeout(() => {
+    try {
+      socket.close(1000, 'timeout')
+    } catch {
+      // ignore
+    }
+    finish(
+      taskId,
+      'completed',
+      t =>
+        `Monitor "${t.description}" expired after ${Math.round(timeoutMs / 1000)}s (${t.eventCount} events)`,
+      {},
+      setAppState,
+    )
+  }, timeoutMs)
+  timeoutId.unref()
+
+  const taskState: MonitorMcpTaskState = {
+    ...createTaskStateBase(taskId, 'monitor_mcp', description, toolUseId),
+    type: 'monitor_mcp',
+    status: 'running',
+    url,
+    eventCount: 0,
+    agentId,
+    socket,
+    timeoutId,
+    unregisterCleanup,
+  }
+  registerTask(taskState, setAppState)
+
+  const emitter = createEventEmitter({
+    taskId,
+    description,
+    toolUseId,
+    agentId,
+    onFlood: () => {
+      enqueuePendingNotification({
+        value: `Monitor "${description}" (task ${taskId}) produced too many events per minute and was stopped. Subscribe to a filtered feed where one exists.`,
+        mode: 'task-notification',
+        priority: 'next',
+        agentId,
+      })
+      killMonitorMcp(taskId, setAppState)
+    },
+  })
+
+  socket.on('message', (data, isBinary) => {
+    const line = isBinary
+      ? `[binary frame, ${Buffer.byteLength(data as Buffer)} bytes]`
+      : data.toString()
+    appendTaskOutput(taskId, line + '\n')
+    updateTaskState<MonitorMcpTaskState>(taskId, setAppState, t => ({
+      ...t,
+      eventCount: t.eventCount + 1,
+    }))
+    emitter.push(line)
+  })
+  socket.on('error', err => {
+    appendTaskOutput(taskId, `[error] ${err.message}\n`)
+    finish(
+      taskId,
+      'failed',
+      t => `Monitor "${t.description}" socket error: ${err.message}`,
+      { error: err.message },
+      setAppState,
+    )
+  })
+  socket.on('close', (code, reason) => {
+    emitter.flush()
+    appendTaskOutput(
+      taskId,
+      `[closed] code ${code}${reason?.length ? ` ${reason.toString()}` : ''}\n`,
+    )
+    finish(
+      taskId,
+      'completed',
+      t =>
+        `Monitor "${t.description}" socket closed (code ${code}, ${t.eventCount} events)`,
+      { closeCode: code },
+      setAppState,
+    )
+  })
+
+  return {
+    taskId,
+    cleanup: () => {
+      unregisterCleanup()
+    },
+  }
+}

package/src/tasks.ts

@@ -3,15 +3,30 @@ import type { Task, TaskType } from './Task.js'
 import { DreamTask } from './tasks/DreamTask/DreamTask.js'
 import { LocalAgentTask } from './tasks/LocalAgentTask/LocalAgentTask.js'
 import { LocalShellTask } from './tasks/LocalShellTask/LocalShellTask.js'
+import { MonitorMcpTask as MonitorMcpTaskImpl } from './tasks/MonitorMcpTask/MonitorMcpTask.js'
+import { LocalWorkflowTask as LocalWorkflowTaskImpl } from './tasks/LocalWorkflowTask/LocalWorkflowTask.js'
 import { RemoteAgentTask } from './tasks/RemoteAgentTask/RemoteAgentTask.js'
 
 /* eslint-disable @typescript-eslint/no-require-imports */
-const LocalWorkflowTask: Task | null = feature('WORKFLOW_SCRIPTS')
-  ? require('./tasks/LocalWorkflowTask/LocalWorkflowTask.js').LocalWorkflowTask
-  : null
-const MonitorMcpTask: Task | null = feature('MONITOR_TOOL')
-  ? require('./tasks/MonitorMcpTask/MonitorMcpTask.js').MonitorMcpTask
-  : null
+// Resolved lazily: these task modules import the task framework, which
+// imports this file. Reading the export at top level during a CJS require
+// hits the temporal dead zone ("Cannot access before initialization").
+let LocalWorkflowTask: Task | null | undefined
+let MonitorMcpTask: Task | null | undefined
+function getOptionalTasks(): Task[] {
+  if (LocalWorkflowTask === undefined) {
+    LocalWorkflowTask = feature('WORKFLOW_SCRIPTS') ? LocalWorkflowTaskImpl : null
+  }
+  if (MonitorMcpTask === undefined) {
+    // Static import: the WebSocket monitor shares the task registry and
+    // notification queue with the app, so it must not be a CJS copy
+    MonitorMcpTask = feature('MONITOR_TOOL') ? MonitorMcpTaskImpl : null
+  }
+  const tasks: Task[] = []
+  if (LocalWorkflowTask) tasks.push(LocalWorkflowTask)
+  if (MonitorMcpTask) tasks.push(MonitorMcpTask)
+  return tasks
+}
 /* eslint-enable @typescript-eslint/no-require-imports */
 
 /**
@@ -26,8 +41,7 @@ export function getAllTasks(): Task[] {
     RemoteAgentTask,
     DreamTask,
   ]
-  if (LocalWorkflowTask) tasks.push(LocalWorkflowTask)
-  if (MonitorMcpTask) tasks.push(MonitorMcpTask)
+  tasks.push(...getOptionalTasks())
   return tasks
 }
 

package/src/tools/AgentTool/runAgent.ts

@@ -756,6 +756,17 @@ export async function* runAgent({
       maxTurns: maxTurns ?? agentDefinition.maxTurns,
     })) {
       onQueryProgress?.()
+      if (process.env.XELA_LOADER_DEBUG) {
+        const kinds =
+          message.type === 'assistant' || message.type === 'user'
+            ? (Array.isArray(message.message.content)
+                ? message.message.content.map(b => b.type).join(',')
+                : typeof message.message.content)
+            : message.type === 'stream_event'
+              ? message.event.type
+              : ''
+        process.stderr.write(`[runAgent ${agentDefinition.agentType}] ${message.type} ${kinds}\n`)
+      }
       // Forward subagent API request starts to parent's metrics display
       // so TTFT/OTPS update during subagent execution.
       if (

package/src/tools/BriefTool/BriefTool.ts

@@ -91,6 +91,8 @@ export function isBriefEntitled(): boolean {
   return feature('KAIROS') || feature('KAIROS_BRIEF')
     ? getKairosActive() ||
         isEnvTruthy(process.env.CLAUDE_CODE_BRIEF) ||
+        // Local/OpenAI-compatible backends: nobody to ask for entitlement
+        !!process.env.OPENAI_API_KEY ||
         getFeatureValue_CACHED_WITH_REFRESH(
           'tengu_kairos_brief',
           false,