Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

15.0 KB
Raw Blame
/**
 * Muse Code JSONL → shared event vocabulary.
 *
 * Muse writes one append-only JSONL per session, but the layout is DATE-SHARDED rather than keyed by
 * project: `<MUSE_HOME>/sessions/YYYY/MM/DD/<session-uuid>/session.jsonl`, with sub-agents one level
 * deeper under `subagent/<child-uuid>/`. Nothing in the path names the project — the only link is
 * `workspace_root`, carried in the FIRST record. That is why this engine is discovered by scanning
 * rather than announced by a hook (measured: muse's hooks do not fire, in `exec` or in the TUI).
 *
 * Every line shares one envelope:
 *
 *   {schema_version, id, stream:{kind,id}, sequence, recorded_at, record_type,
 *    payload_type, payload:{kind, event?…}}
 *
 * `recorded_at` is MICROseconds. `payload_type` is mostly the useless constant `runtime.session`; the
 * real discriminator is `payload.event.kind`, of which a real session carries 27 distinct values.
 *
 * The six that matter, verified against a real session (muse 0.1.0-R708.1, 188 records) — note the
 * bundled `read-session` skill documents a DIFFERENT name for the first one (`user_prompt_display`),
 * which never appears on disk:
 *
 *   started                        {prompt}                      ← the user asked; opens a turn
 *   reasoning_committed            {text}                        → thinking
 *   assistant_message_committed    {message_id, response_id, text}
 *   assistant_tool_calls_committed {tool_calls:[{id, call_id, name, args}]}   args is a JSON *string*
 *   tool_result_batch_committed    {batch_id, results:[{tool_call_index, tool_call_id, text}]}
 *   terminal                       {terminal, reason, turn_duration_ms}      ← closes the turn
 *
 * Tool calls pair by `call_id` ↔ `results[].tool_call_id`. A failed turn carries the provider error in
 * `terminal.reason` (seen live: `API error 402 … Billing verification failed`), so unlike engines whose
 * failures are silent, no log tailing is needed to notice one.
 */

import type { EngineNormalizer } from '../types.js'
import type { LastTurnText, LiveEvent, SessionEvent } from '../../lib/normalize.js'

type JsonObject = Record<string, unknown>

const MAX_OUTPUT = 2_000
const MAX_THINKING = 500

/** Muse's tool names → the vocabulary the web/device cards already render. */
const TOOL_NAMES: Record<string, string> = {
  read_file: 'Read',
  write_file: 'Write',
  edit_file: 'Edit',
  bash: 'Bash',
  shell: 'Bash',
  grep: 'Grep',
  glob: 'Glob',
  list_dir: 'LS',
  web_search: 'WebSearch',
  web_fetch: 'WebFetch',
  // MEASURED from real sessions (`assistant_tool_calls_committed.tool_calls[].name`), not guessed from
  // what other CLIs call the same thing — muse's names differ from every one of them.
  //
  // The planning tool MUST land on the exact string `TodoWrite`: the device builds its checklist by
  // matching that name literally, so a near-miss shows no list at all and reports no error.
  write_todos: 'TodoWrite',
  // Delegation is three tools, not one: spawn starts a child, wait blocks on it, read pulls its result.
  // Only the spawn opens a sub-agent row; the other two are ordinary cards about that child.
  subagent_spawn: 'Task',
  subagent_wait: 'TaskWait',
  subagent_read_result: 'TaskResult',
  // Asking the user belongs on its own screen, not in the tool feed — the shared name routes it there.
  request_user_input: 'AskUserQuestion',
}

export function museToolName(name: string): string {
  return TOOL_NAMES[name] ?? (name ? name.charAt(0).toUpperCase() + name.slice(1) : 'Tool')
}

function obj(value: unknown): JsonObject | null {
  return value && typeof value === 'object' && !Array.isArray(value) ? (value as JsonObject) : null
}

function str(value: unknown): string {
  return typeof value === 'string' ? value : ''
}

export function clip(value: string, limit: number): string {
  return value.length > limit ? `${value.slice(0, limit)}…` : value
}

/** One record's event plus the SCOPE it belongs to. */
export interface MuseRecord {
  /** `payload.kind` — `run`, `task`, `tool_batch_effect`, … */
  scope: string
  event: JsonObject
}

/**
 * The `payload.event` of one record, or null for the envelopes that carry no event.
 *
 * The scope comes with it, and it is load-bearing: `run` and `task` are DIFFERENT lifecycles that share
 * event names. Both emit `started`, and only a run's is a turn — a `task.started` is scheduler
 * bookkeeping and several fire inside one run. This used to drop `payload.kind`, which left `started`
 * ambiguous; the only thing separating the two was that a task carries no prompt. That held right up
 * until a SCHEDULED run arrived — a real turn whose prompt is empty, because nobody typed anything.
 */
export function museEvent(line: string): MuseRecord | null {
  let raw: JsonObject | null
  try { raw = obj(JSON.parse(line)) } catch { return null }
  if (!raw) return null
  const payload = obj(raw.payload)
  if (!payload) return null
  const event = obj(payload.event)
  if (!event || !str(event.kind)) return null
  return { scope: str(payload.kind), event }
}

/** `workspace_root` from a session's first record — the only thing tying a session to a directory. */
export function museWorkspaceRoot(firstLine: string): string | null {
  let raw: JsonObject | null
  try { raw = obj(JSON.parse(firstLine)) } catch { return null }
  const record = obj(obj(raw?.payload)?.record)
  const root = str(record?.workspace_root)
  return root || null
}

export interface MuseTurnState {
  open: boolean
  /** call_id → tool name, so a result can be reported under the name that opened it. */
  toolNames: Map<string, string>
  /** `subagent_id` → the tool_start id of its sub-agent row, learned from the SPAWN'S RESULT. */
  subagentRows: Map<string, string>
  /** Rows opened this turn and not yet closed. A row left open holds `turn_ended` forever. */
  openRows: Set<string>
  pendingTools: Set<string>
  thinkingCounter: number
}

export function newMuseTurnState(): MuseTurnState {
  return {
    open: false, toolNames: new Map(), subagentRows: new Map(), openRows: new Set(),
    pendingTools: new Set(), thinkingCounter: 0,
  }
}

/** A sub-agent tool's result text is itself JSON (`{status, subagent_id, …}`). */
function resultBody(text: string): JsonObject | null {
  try { return obj(JSON.parse(text)) } catch { return null }
}

/** One record → events. `mode: 'replay'` emits `user_message` instead of deriving the turn lifecycle. */
export function museEventToEvents(record: MuseRecord, state: MuseTurnState, mode: 'live' | 'replay'): LiveEvent[] {
  const { scope, event } = record
  const kind = str(event.kind)
  const events: LiveEvent[] = []

  if (kind === 'started') {
    // ONLY a run start is a turn. `task.started` fires several times inside a single run — taking it for
    // a turn would open, and immediately re-open, one per task.
    if (scope !== 'run') return []
    const prompt = str(event.prompt).trim()
    // An EMPTY prompt is normal and still opens the turn: a SCHEDULED run has no typed message, because
    // the scheduler triggered it rather than a person. Bailing here is why a reminder's output never
    // reached the device — no turn opened, so the assistant text belonged to nothing and `terminal`
    // closed a turn that was never there. Replay is the exception: an empty prompt would draw an empty
    // user bubble, so it contributes no message and simply renders the assistant side.
    if (mode === 'replay') return prompt ? [{ type: 'user_message', payload: { content: prompt } }] : []
    if (state.open) events.push({ type: 'turn_ended', payload: {} })
    state.open = true
    state.pendingTools.clear()
    events.push({ type: 'turn_started', payload: { userMessage: prompt } })
    return events
  }

  if (kind === 'reasoning_committed') {
    const text = str(event.text).trim()
    if (!text) return []
    return [{
      type: 'thinking_delta',
      payload: { content: clip(text, MAX_THINKING), thinkingId: `thinking-muse-${state.thinkingCounter++}` },
    }]
  }

  if (kind === 'assistant_message_committed') {
    const text = str(event.text)
    return text ? [{ type: 'text_delta', payload: { content: text } }] : []
  }

  if (kind === 'assistant_tool_calls_committed') {
    const calls = Array.isArray(event.tool_calls) ? event.tool_calls : []
    for (const entry of calls) {
      const call = obj(entry)
      if (!call) continue
      const id = str(call.call_id) || str(call.id)
      if (!id) continue
      const tool = museToolName(str(call.name))
      state.toolNames.set(id, tool)
      state.pendingTools.add(id)
      // `args` arrives as a JSON string; hand the parsed object over so the cards can show real
      // arguments rather than a quoted blob.
      let input: unknown = str(call.args)
      try { input = JSON.parse(str(call.args)) } catch { /* keep the raw string */ }
      const args = obj(input) ?? {}
      // The device reads `input.todos[{content|subject, status}]` literally. Muse names the field `text`
      // (measured: {"todos":[{"text":"…","status":"in_progress"}]}), so without this reshape the tool
      // name matches, the card renders — and the checklist is silently empty.
      if (tool === 'TodoWrite' && Array.isArray(args.todos)) {
        input = {
          ...args,
          todos: args.todos.map((entry) => {
            const todo = obj(entry) ?? {}
            return { ...todo, content: str(todo.content) || str(todo.text) || str(todo.subject) }
          }),
        }
      }
      // A spawn's arguments name the child (`task_name`/`role`) but NOT its id. MEASURED: the id is
      // handed back in the spawn's RESULT (`{"status":"accepted","subagent_id":…}`), so the row can only
      // be tied to a child once that result arrives — see the result branch below.
      if (tool === 'Task') {
        state.openRows.add(id)
        // `description` is what the sub-agent row shows; muse calls it task_name.
        input = { ...args, description: str(args.task_name) || str(args.role) || 'sub-agent' }
      }
      events.push({ type: 'tool_start', payload: { id, tool, input } })
    }
    return events
  }

  if (kind === 'tool_result_batch_committed') {
    const results = Array.isArray(event.results) ? event.results : []
    for (const entry of results) {
      const result = obj(entry)
      if (!result) continue
      const id = str(result.tool_call_id)
      if (!id) continue
      const tool = state.toolNames.get(id) ?? 'Tool'
      state.toolNames.delete(id)
      state.pendingTools.delete(id)
      const output = str(result.text)
      const isError = result.is_error === true
      // The spawn's result is where the child's id is revealed — and where a spawn can be turned down
      // outright (`{"status":"rejected","reason":"command_id_reused"}`). A rejected spawn never runs, so
      // its row must close here or it holds the turn open for a child that does not exist.
      if (tool === 'Task') {
        const body = resultBody(output)
        const child = str(body?.subagent_id)
        if (str(body?.status) === 'accepted' && child) state.subagentRows.set(child, id)
        else if (state.openRows.delete(id)) {
          events.push({ type: 'subagent_finished', payload: { id, status: 'failed' } })
        }
      }
      // MEASURED: `subagent_wait` returning `{"status":"ready", …, "summary":…}` is muse's "this child is
      // done" signal. `subagent_read_result` — which an earlier reading of the tool list assumed was the
      // completion marker — is never called at all in real sessions.
      if (tool === 'TaskWait') {
        const body = resultBody(output)
        const rowId = state.subagentRows.get(str(body?.subagent_id))
        if (rowId && str(body?.status) === 'ready' && state.openRows.delete(rowId)) {
          state.subagentRows.delete(str(body?.subagent_id))
          events.push({ type: 'subagent_finished', payload: { id: rowId, status: 'completed' } })
        }
      }
      events.push({
        type: 'tool_end',
        payload: { id, tool, output: clip(output, MAX_OUTPUT), isError, summary: isError ? 'error' : '' },
      })
    }
    return events
  }

  if (kind === 'terminal') {
    if (mode === 'replay' || !state.open) return []
    state.open = false
    state.pendingTools.clear()
    // Muse spawns children it never waits on (measured: 7 spawns, 4 waits in one session), and the main
    // turn ends anyway. `turn_ended` is HELD while any sub-agent row is open, so a row nobody closed
    // pins the device tile on "Processing" forever with no recap — the exact bug this backstop fixes.
    for (const rowId of state.openRows) {
      events.push({ type: 'subagent_finished', payload: { id: rowId, status: 'completed' } })
    }
    state.openRows.clear()
    state.subagentRows.clear()
    // A failed turn is not a finished one: the device must clear its tile without a recap of nothing,
    // and the reason muse puts here is the provider's own error text.
    const failed = str(event.terminal) === 'failed'
    events.push({ type: 'turn_ended', payload: failed ? { aborted: true } : {} })
    return events
  }

  return []
}

/** Live tail: one JSONL line → events. */
export class MuseNormalizer implements EngineNormalizer {
  private state = newMuseTurnState()

  get turnOpen(): boolean { return this.state.open }

  closeTurn(): void {
    this.state.open = false
    this.state.pendingTools.clear()
    // Same reason as the `terminal` backstop: a row left open outlives the turn and holds the tile busy.
    this.state.openRows.clear()
    this.state.subagentRows.clear()
  }

  ingest(line: string): LiveEvent[] {
    const record = museEvent(line)
    return record ? museEventToEvents(record, this.state, 'live') : []
  }

  finishReplay(): LiveEvent[] {
    return []
  }
}

/** Full-session replay (`session_get`) — the same render path as the live stream. */
export function museMessagesToEvents(lines: string[]): SessionEvent[] {
  const state = newMuseTurnState()
  const events: SessionEvent[] = []
  for (const line of lines) {
    const record = museEvent(line)
    if (record) events.push(...museEventToEvents(record, state, 'replay') as SessionEvent[])
  }
  events.push({ type: 'done', payload: { result: 'success' } })
  return events
}

/** Last user prompt + the assistant text that followed it — the recap's source of truth. */
export function lastMuseTurnText(lines: string[]): LastTurnText | null {
  let userMessage = ''
  let assistantText = ''
  for (const line of lines) {
    const record = museEvent(line)
    if (!record) continue
    const event = record.event
    const kind = str(event.kind)
    if (kind === 'started' && record.scope === 'run') {
      // Reset on EVERY run start, prompt or not. Keying the reset on a non-empty prompt meant a series of
      // scheduled runs never reset it, so the recap of the 4th five-minute reminder carried all four
      // answers glued together instead of the latest one.
      userMessage = str(event.prompt).trim()
      assistantText = ''
    } else if (kind === 'assistant_message_committed') {
      const text = str(event.text).trim()
      if (text) assistantText += `${assistantText ? '\n\n' : ''}${text}`
    }
  }
  return assistantText ? { userMessage, assistantText } : null
}