Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

20.5 KB
Raw Blame
import { useEffect, useMemo, useRef, useState } from 'react'
import type { BoardLogEntry, BoardLogEvent } from '@shared/types'
import {
  BOARD_COMMENT_MENTION_MAX,
  boardCommentOutcomeText,
  commentIdOfSource,
  commentSegments,
  parseMentions
} from '@shared/board-comment'
import { formatTimeAgo } from '../../lib/usageFormat'
import { useSession } from '../../session/session'
import { useOwningProjectId } from '../../session/owning-project'
import { useProjects } from '../../state/projects'
import { useBoardLog } from '../../state/boardLog'
import { useBoardCommentDelivery } from '../../state/boardCommentDelivery'
import { collapseFeed } from '../../lib/boardLogCollapse'
import {
  boardCommentTraces,
  isBoardCommentTrace,
  mentionStatuses,
  type MentionStatus
} from '../../lib/boardCommentStatus'
import { canDeliverBoardComments, deliverCommentMentions } from '../../lib/boardCommentDelivery'
import {
  insertMention,
  mentionOptions,
  mentionQueryAt,
  type MentionCandidate
} from '../../lib/boardMentions'
import { isBrowserRuntime } from '../../bridge/runtime'
import { stationTrigger } from '@shared/station-notice'
import type { KanbanSession } from './KanbanView'

interface BoardLogPanelProps {
  /** The card/node whose activity this panel shows — feed + composer are scoped to `card.id`.
   *  Only the id is needed, so the canvas node flyout can use this panel without building a
   *  full KanbanSession. A GitHub issue card passes its synthetic board-log id (`issueLogId`). */
  card: Pick<KanbanSession, 'id'>
  /** Panel heading. Defaults to the session card's "Comments & activity". */
  title?: string
  /** Hide the comment composer — the issue card's run history is read-only, because a comment box
   *  under a GitHub issue reads as "post to GitHub", and this log never leaves the project. */
  readOnly?: boolean
  /** Shown when the feed is empty (defaults to nothing). */
  emptyText?: string
  /** The agent sessions on this board a comment may @mention (`mentionCandidatesFrom`). Also what a
   *  mention renders as — the node's CURRENT title. Absent ⇒ no @ picker. */
  mentionables?: readonly MentionCandidate[]
}

/** The activity sentence WITHOUT the leading author name — the name is rendered separately in
 *  the author's color, so the feed reads like Trello (colored actor + muted action). column-*
 *  events carry no nodeId and so never reach a card-scoped feed; kept for completeness. */
export function eventBody(e: BoardLogEvent): string {
  switch (e.type) {
    case 'card-created':
      return `created this card in ${e.to ?? 'Ungrouped'}`
    case 'card-moved':
      // `title` is the reason when the board moved the card itself ("PR #12 merged").
      return `moved this card ${e.from ?? 'Ungrouped'} → ${e.to ?? 'Ungrouped'}${e.title ? ` (${e.title})` : ''}`
    case 'column-added':
      return `added column ${e.title ?? ''}`.trimEnd()
    case 'column-renamed':
      return `renamed column ${e.from ?? ''} → ${e.to ?? ''}`
    case 'column-deleted':
      return `deleted column ${e.title ?? ''}`.trimEnd()
    case 'member-assigned':
      return `assigned ${e.to ?? 'someone'}`
    case 'member-unassigned':
      return `removed ${e.to ?? 'someone'}`
    case 'due-set':
      return `set the due date → ${e.to ? formatStamp(Date.parse(e.to)) : ''}`.trimEnd()
    case 'due-cleared':
      return `removed the due date`
    case 'priority-set':
      return `set priority → ${e.to ?? ''}`.trimEnd()
    case 'priority-cleared':
      return `removed the priority`
    case 'agent-message':
      // A board comment's delivery line: normally shown ON its comment's row (and hidden as a row of
      // its own); it stands alone only where the comment itself is not — a comment written on
      // another card that mentioned this session.
      if (commentIdOfSource(e.from))
        return `routed a board comment here: ${boardCommentOutcomeText(String(e.title ?? ''), e.reason).text}`
      return `sent a message to ${e.to ?? 'another node'} (${e.title ?? 'unknown outcome'})`
    case 'agent-read-cookies':
      // A loud, human-visible line for a cookie read (the whole point of the trace). `from` names the
      // agent, `to` the domain it read; `title` names the browser node it drove.
      return `read cookies for ${e.to ?? 'a site'}${e.title ? ` via ${e.title}` : ''}`
    case 'run-started':
      // The run's fields come from a git-shared file like everything else here: rendered as text
      // only (React escapes it), and never turned into an action.
      return `started ${runName(e)} on this issue`
    case 'run-ended':
      return `closed ${runName(e)}${e.run?.end ? ` (last state: ${e.run.end})` : ''}`
    case 'station-failed':
      // Rendered from the closed reason table, never from anything the station wrote: `to` is a
      // reason CODE, and an unknown one (a newer peer, a hand edit) reads as a plain "stopped".
      return `told this agent that station ${stationName(e)} stopped: ${stationTrigger(e.to)?.label ?? 'it stopped'}`
    case 'station-reported':
      // `to` is the outcome CODE and `title` the station's note — from a shared file, so text only
      // (React escapes it); an outcome this build does not know reads as a plain report.
      return `recorded this session's report: ${
        e.to === 'succeeded' ? 'its task succeeded' : e.to === 'failed' ? 'its task failed' : 'an outcome'
      }${typeof e.title === 'string' && e.title ? ` — "${e.title}"` : ''}`
    default:
      // A newer peer may write event types this build doesn't know — show them neutrally.
      return `updated this card`
  }
}

/** `"Build UI" (term-1a2b)` — the station as the notice named it. Text only, like `runName`. */
function stationName(e: BoardLogEvent): string {
  const id = typeof e.from === 'string' && e.from ? ` (${e.from})` : ''
  return typeof e.title === 'string' && e.title ? `"${e.title}"${id}` : `${e.from ?? 'a station'}`
}

/** "Claude session term-1a2b" — the node title when the event recorded one, else the node id. */
function runName(e: BoardLogEvent): string {
  const who = typeof e.title === 'string' && e.title ? e.title : 'a session'
  const id = typeof e.run?.nodeId === 'string' ? ` (${e.run.nodeId})` : ''
  return `${who}${id}`
}

/** Absolute, Trello-style stamp ("19 Jul 2026, 22:50") — the feed shows dates, not "2h ago"
 *  (the relative form stays in the row's tooltip). */
function formatStamp(ts: number): string {
  if (!Number.isFinite(ts)) return ''
  return new Date(ts).toLocaleString(undefined, {
    day: 'numeric',
    month: 'short',
    year: 'numeric',
    hour: '2-digit',
    minute: '2-digit'
  })
}

/** Right panel of the card modal (all card kinds): a composer on top and the card's own
 *  comments + activity feed newest-first. Reads/writes the board log of the project that OWNS the
 *  card (`OwningProjectContext`: the card's project under the card modal's `ProjectSessionScope`,
 *  the store-held project on the canvas), falling back to the active project, through the session
 *  api resolved for that same project. Keying it on the active project paired an Omni lane's api
 *  with another project's id: the lane's comments read blank and a comment typed there was saved
 *  nowhere. Subscribes on mount, so a teammate's comment or a board change lands live;
 *  unsubscribes on unmount / card swap.
 *
 *  A comment that @mentions a session (the composer's @ picker) is also delivered to that agent —
 *  ONLY from this composer's send, with the text just typed, and only in the desktop app's own
 *  window (`canDeliverBoardComments`). A comment that arrives in the log (git pull, another
 *  instance, a relay peer, a team-presence guest) renders its mentions and types nowhere. */
export function BoardLogPanel({ card, title, readOnly, emptyText, mentionables }: BoardLogPanelProps) {
  const { api, source } = useSession()
  const owningProjectId = useOwningProjectId()
  const activeProjectId = useProjects((s) => s.activeProjectId)
  const projectId = owningProjectId ?? activeProjectId
  const entries = useBoardLog((s) => s.entriesFor(projectId))
  const unsupported = useBoardLog((s) => !!s.unsupportedByProject[projectId])
  const error = useBoardLog((s) => !!s.errorByProject[projectId])
  const deliveries = useBoardCommentDelivery((s) => s.byComment)
  const sent = useBoardCommentDelivery((s) => s.sent)
  const [draft, setDraft] = useState('')
  const [composeError, setComposeError] = useState<string | null>(null)
  const [picker, setPicker] = useState<{ start: number; caret: number; query: string } | null>(null)
  const [pick, setPick] = useState(0)
  const composerRef = useRef<HTMLTextAreaElement>(null)
  const canDeliver = canDeliverBoardComments(source, isBrowserRuntime())
  const candidates = canDeliver ? (mentionables ?? []) : []
  const options = picker ? mentionOptions(candidates, picker.query) : []

  useEffect(() => {
    if (!projectId) return
    void useBoardLog.getState().load(api, projectId)
    const unsub = useBoardLog.getState().subscribeChanged(api, projectId)
    return unsub
  }, [api, projectId])

  const send = () => {
    const text = draft.trim()
    if (!text) return
    const mentions = canDeliver ? parseMentions(text) : []
    if (mentions.length > BOARD_COMMENT_MENTION_MAX) {
      setComposeError(`A comment can mention at most ${BOARD_COMMENT_MENTION_MAX} sessions.`)
      return
    }
    const entry = useBoardLog.getState().append(api, projectId, { kind: 'comment', nodeId: card.id, text })
    setDraft('')
    setPicker(null)
    setComposeError(null)
    // The one place a delivery starts: this send, this text. Mentions are re-parsed from the text
    // as it was stored (clamped), which is exactly what main will parse them from.
    if (mentions.length && entry.text)
      void deliverCommentMentions(
        { projectId, commentId: entry.id, author: entry.author.name, text: entry.text },
        parseMentions(entry.text)
      )
  }

  const choose = (c: MentionCandidate): void => {
    if (!picker) return
    const next = insertMention(draft, picker.start, picker.caret, c)
    setDraft(next.text)
    setPicker(null)
    requestAnimationFrame(() => {
      const el = composerRef.current
      if (!el) return
      el.focus()
      el.setSelectionRange(next.caret, next.caret)
    })
  }

  /** Re-read the @query at the caret — on every edit, and whenever the caret moves (a click, an
   *  arrow key), so the picker never inserts at a place the user has left. */
  const syncPicker = (value: string, caret: number): void => {
    const q = candidates.length ? mentionQueryAt(value, caret) : null
    setPicker((cur) => {
      if (!q) return null
      if (cur && cur.start === q.start && cur.query === q.query && cur.caret === caret) return cur
      return { ...q, caret }
    })
  }

  const onDraftChange = (value: string, caret: number): void => {
    setDraft(value)
    setComposeError(null)
    syncPicker(value, caret)
    setPick(0)
  }

  // Card-scoped: this card's comments + its own events. Column events (no nodeId) never match. A
  // board comment's delivery line is shown ON its comment's row — so it is not also a row of its own
  // when that comment is on THIS card and is one this machine sent (the only comments whose row
  // shows a status). Everywhere else — the mentioned session's own card, a teammate's comment — it
  // stays a line. `traces` reads the WHOLE log: a line is filed under the session it went to.
  const all = entries ?? []
  const ownHere = new Set(
    all.filter((e) => e.kind === 'comment' && e.nodeId === card.id && sent[e.id] !== undefined).map((e) => e.id)
  )
  const traces = useMemo(() => boardCommentTraces(all), [all])
  const feed = all.filter(
    (e) =>
      e.nodeId === card.id &&
      !(isBoardCommentTrace(e) && ownHere.has(commentIdOfSource(e.event?.from) ?? ''))
  )
  const titles = useMemo(() => new Map((mentionables ?? []).map((m) => [m.id, m.title])), [mentionables])
  const pending = canDeliver ? parseMentions(draft) : []

  return (
    <div className="board-log">
      <div className="board-log__title">{title ?? 'Comments & activity'}</div>
      {unsupported ? (
        <div className="board-log__hint">Board history needs a project folder</div>
      ) : readOnly ? null : (
        <div className="board-log__compose">
          <textarea
            ref={composerRef}
            className="board-log__composer"
            value={draft}
            placeholder={candidates.length ? 'Write a comment… (@ to mention a session)' : 'Write a comment…'}
            aria-autocomplete={candidates.length ? 'list' : undefined}
            aria-expanded={options.length > 0 ? true : undefined}
            onChange={(e) => onDraftChange(e.target.value, e.target.selectionStart ?? e.target.value.length)}
            onKeyUp={(e) => {
              // A caret move (arrows, Home/End) — the keys that edit already went through onChange.
              if (!picker || e.nativeEvent.isComposing) return
              const el = e.currentTarget
              syncPicker(el.value, el.selectionStart ?? el.value.length)
            }}
            onClick={(e) => {
              const el = e.currentTarget
              syncPicker(el.value, el.selectionStart ?? el.value.length)
            }}
            onBlur={() => setPicker(null)}
            onKeyDown={(e) => {
              // Never act mid-IME-composition (e.g. selecting a kanji candidate with Enter).
              if (e.nativeEvent.isComposing) return
              if (picker && options.length) {
                if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
                  e.preventDefault()
                  const d = e.key === 'ArrowDown' ? 1 : -1
                  setPick((i) => (i + d + options.length) % options.length)
                  return
                }
                if (e.key === 'Enter' || e.key === 'Tab') {
                  e.preventDefault()
                  choose(options[Math.min(pick, options.length - 1)])
                  return
                }
              }
              if (picker && e.key === 'Escape') {
                e.preventDefault()
                e.stopPropagation()
                setPicker(null)
                return
              }
              // Enter sends; Shift+Enter inserts a newline (default textarea behavior).
              if (e.key === 'Enter' && !e.shiftKey) {
                e.preventDefault()
                send()
              }
            }}
          />
          {options.length > 0 && (
            <div className="board-log__mention-picker" role="listbox" aria-label="Mention a session">
              {options.map((c, i) => (
                <div
                  key={c.id}
                  role="option"
                  aria-selected={i === pick}
                  className={`board-log__mention-option${i === pick ? ' is-active' : ''}`}
                  onMouseDown={(e) => {
                    e.preventDefault() // keep the caret in the composer
                    choose(c)
                  }}
                >
                  {c.title}
                </div>
              ))}
            </div>
          )}
          {pending.length > 0 && (
            <div className="board-log__deliver-note">
              Delivers to {pending.map((id) => `@${titles.get(id) ?? id}`).join(', ')} when you send —
              through agent messaging, when the session is idle.
            </div>
          )}
          {composeError && <div className="board-log__error">{composeError}</div>}
        </div>
      )}
      {!unsupported && error && (
        <div className="board-log__error">Some board history couldn’t be saved.</div>
      )}
      {!unsupported && feed.length === 0 && emptyText && (
        <div className="board-log__hint">{emptyText}</div>
      )}
      <BoardLogFeed
        feed={feed}
        titles={titles}
        statusesFor={(entry) =>
          mentionStatuses(entry, traces, deliveries[entry.id], {
            own: sent[entry.id] !== undefined,
            now: Date.now()
          })
        }
      />
    </div>
  )
}

/** The feed itself, newest first. Runs of like events render folded as one "×N" row that expands
 *  in place (lib/boardLogCollapse — a VIEW; the log is never rewritten). Comments and the audit
 *  types are always one row each. Which groups are open is component state keyed by the group's
 *  newest entry id, so a new entry landing on top does not collapse a row the user just opened.
 *  `titles` renders a mention as its session's current title; `statusesFor` puts a comment's
 *  delivery outcomes on its own row. */
export function BoardLogFeed({
  feed,
  titles,
  statusesFor
}: {
  feed: readonly BoardLogEntry[]
  titles?: ReadonlyMap<string, string>
  statusesFor?: (entry: BoardLogEntry) => MentionStatus[]
}) {
  const [open, setOpen] = useState<ReadonlySet<string>>(() => new Set())
  const items = useMemo(() => collapseFeed(feed), [feed])
  const toggle = (key: string): void =>
    setOpen((cur) => {
      const next = new Set(cur)
      if (next.has(key)) next.delete(key)
      else next.add(key)
      return next
    })
  const row = (entry: BoardLogEntry, fold?: React.ReactNode, key?: string) => (
    <FeedRow
      key={key ?? entry.id}
      entry={entry}
      fold={fold}
      titles={titles}
      statuses={entry.kind === 'comment' ? statusesFor?.(entry) : undefined}
    />
  )
  return (
    <div className="board-log__feed">
      {items.map((item) => {
        if (item.kind === 'single') return row(item.entry)
        const expanded = open.has(item.key)
        const fold = (
          <button
            className="board-log__fold"
            aria-expanded={expanded}
            title={expanded ? 'Collapse' : `Show all ${item.entries.length}`}
            onClick={() => toggle(item.key)}
          >
            ×{item.entries.length}
          </button>
        )
        return expanded ? (
          <div key={item.key} className="board-log__group board-log__group--open">
            {item.entries.map((entry, i) => row(entry, i === 0 ? fold : undefined))}
          </div>
        ) : (
          row(item.entries[0], fold, item.key)
        )
      })}
    </div>
  )
}

/** A comment's text with each mention token drawn as its session's name — the CURRENT title when
 *  the session is on this board, else the name the token was written with. Text only: React escapes
 *  it, and nothing here is ever turned into an action. */
function CommentText({ text, titles }: { text: string; titles?: ReadonlyMap<string, string> }) {
  return (
    <>
      {commentSegments(text).map((s, i) =>
        s.kind === 'text' ? (
          s.text
        ) : (
          <span key={i} className="board-log__mention" title={s.nodeId}>
            @{titles?.get(s.nodeId) || s.label || s.nodeId}
          </span>
        )
      )}
    </>
  )
}

function FeedRow({
  entry,
  fold,
  titles,
  statuses
}: {
  entry: BoardLogEntry
  fold?: React.ReactNode
  titles?: ReadonlyMap<string, string>
  statuses?: MentionStatus[]
}) {
  const when = formatStamp(entry.ts)
  const whenAgo = formatTimeAgo(entry.ts)
  const nameOf = (nodeId: string): string => {
    const current = titles?.get(nodeId)
    if (current) return current
    for (const s of commentSegments(entry.text ?? ''))
      if (s.kind === 'mention' && s.nodeId === nodeId && s.label) return s.label
    return nodeId
  }
  if (entry.kind === 'event' && entry.event) {
    return (
      <div className="board-log__event" title={whenAgo}>
        <span className="board-log__dot" style={{ background: entry.author.color }} />
        <span className="board-log__author" style={{ color: entry.author.color }}>
          {entry.author.name}
        </span>{' '}
        <span className="board-log__event-body">{eventBody(entry.event)}</span>
        {fold}
        <span className="board-log__time">{when}</span>
      </div>
    )
  }
  return (
    <div className="board-log__comment">
      <div className="board-log__meta">
        <span className="board-log__dot" style={{ background: entry.author.color }} />
        <span className="board-log__author" style={{ color: entry.author.color }}>
          {entry.author.name}
        </span>
        <span className="board-log__time" title={whenAgo}>{when}</span>
      </div>
      <div className="board-log__text">
        <CommentText text={entry.text ?? ''} titles={titles} />
      </div>
      {statuses && statuses.length > 0 && (
        <ul className="board-log__deliveries" aria-label="Delivery to mentioned sessions">
          {statuses.map((m) => (
            <li key={m.nodeId} className={`board-log__delivery board-log__delivery--${m.view.tone}`}>
              <span className="board-log__mention">@{nameOf(m.nodeId)}</span>{' '}
              {m.view.text}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}