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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { memo, useState } from 'react'
import { sshHostKey } from '@shared/ssh'
import type { KanbanCardMeta, KanbanColumnCategory, KanbanLabel, KanbanPriority } from '@shared/types'
import { useAgentStatus, type AgentStatusSession } from '../../state/agentStatus'
import { AccountChip, useAccountChip } from '../AccountChip'
import { ContextMeter } from '../ContextMeter'
import { transcriptSessionFor } from '../../lib/transcriptSession'
import { isRemoteSessionNode } from '@shared/worktree'
import { NodeIconView } from '../NodeIcon'
import { LabelChips } from './LabelChips'
import { PRIORITIES } from './CardMetaBar'
import type { KanbanSession } from './KanbanView'
import type { GitHubPullStatus, PullStatusFreshness } from '@shared/github-pull-status'
import { PullRefChip } from './PullStatusBadges'
import type { IssueRef } from '@shared/github-issue-ref'
import { IssueRefChip } from '../IssueRefChip'
import { cardBadge } from '../../lib/kanbanStatusChips'
import { cardAssignees } from '@shared/kanban-labels'
import { TeamProgressChip } from '../TeamProgressChip'
import type { TeamStation } from '../../lib/teamProgress'
import { cardShowsOverdue, sessionNameRepeatsTitle } from '../../lib/cardRedundancy'
import { PortsChip } from '../PortsChip'
import { QueuedLaunchChip } from './QueuedLaunchChip'
import type { SelectMods } from '../../lib/cardSelection'
const PRIO_COLOR = Object.fromEntries(PRIORITIES.map((p) => [p.id, p.color])) as Record<KanbanPriority, string>
interface SessionCardProps {
session: KanbanSession
meta?: KanbanCardMeta
/** Resolved board labels on this card (LabelChips) — resolved by the board, passed in. */
labels?: KanbanLabel[]
// Every callback carries the node id so the column can pass ONE stable function to all its
// cards — per-card arrow closures would give each card fresh props and defeat the memo.
/** Single click opens the card modal directly (the expand/collapse step was dropped). */
onOpen: (nodeId: string) => void
onDragStart: (nodeId: string) => void
onDragEnd: () => void
/** A dragged card was dropped on this card — before it (top half) or after it (bottom half). */
onDropAt: (nodeId: string, side: 'before' | 'after') => void
/** Right-click on the card — opens the actions menu at the cursor. */
onContext: (nodeId: string, x: number, y: number) => void
/** Pull requests linked to this card through its worktree branch (stable array per card). */
pulls?: GitHubPullStatus[]
pullFreshness?: PullStatusFreshness
/** The session's `#N` chip (it was started on a GitHub issue): open that issue. */
onOpenIssue?: (ref: IssueRef) => void
/** The stations this session opened (lib/teamProgress) — a stable array per card. */
team?: readonly TeamStation[]
/** A station row in the team list was picked: go to that node on the canvas. */
onTravel?: (nodeId: string) => void
/** The lifecycle category of the column the card sits in (lib/cardRedundancy reads it). */
columnCategory?: KanbanColumnCategory
/** The card's project, when the dev-port scanner covers it (the project on the canvas). Absent =
* no Ports chip: the scanner scans the active project only, so an Omni lane of a background
* project would only ever show a stale or empty list. A stable object per board (memo). */
ports?: { projectId: string; remote: boolean }
/** A port row was picked: open it in a browser node beside the card's node (on the canvas). */
onOpenPort?: (nodeId: string, url: string) => void
/** ▶ on the card's QUEUED chip: start the node's held launch now (Canvas's `run` path; on a relay
* tab Canvas answers with a "runs on the host" notice instead). Absent = the chip shows without ▶. */
onRunQueued?: (nodeId: string) => void
/** The agent-status store of the session the card's PROJECT belongs to
* (`agentStatusForProject(projectId).store`, re-resolved by the board on a registry change).
* A team tab's card reads its relay session's store; its node id is the handed-off SSH
* project's too, so the default store would show that project's state on this card. Absent =
* the default store. A stable reference per board (SessionCard is memoized). */
statusStore?: AgentStatusSession['store']
/** This card is part of the board's multi-selection. */
selected?: boolean
/** Every click is offered to the board's selection first (⌘/Ctrl-click, Shift-click, or any
* click while cards are selected). True = it was a selection gesture and the card must NOT
* open. One stable function for every card (`useCardSelection`). Absent = no multi-select. */
onSelectClick?: (nodeId: string, mods: SelectMods) => boolean
}
export const SessionCard = memo(function SessionCard({
session, meta, labels = [], onOpen, onDragStart, onDragEnd, onDropAt, onContext, pulls,
pullFreshness = 'fresh', onOpenIssue, team, onTravel, columnCategory, ports, onOpenPort, onRunQueued,
statusStore, selected = false, onSelectClick
}: SessionCardProps) {
// THIS card's agent status, subscribed per card rather than threaded down from the board.
// KanbanView used to hold `useAgentStatus((s) => s.byId)` and pass the map through the column:
// that map's identity changes on every hook event of every node, so one agent's working→idle
// flip re-rendered the whole board — every column, every card. The same rule Canvas follows
// (see its loopSig comment) and StatusAwareMiniMap demonstrates: subscribe where the value is
// read, so the re-render is confined to the one thing that changed.
const status = (statusStore ?? useAgentStatus)((s) => s.byId[session.id])
// The card's meter follows the same session rule as the node and the card modal.
const cardTranscript = transcriptSessionFor({ live: status?.sessionId, persisted: session.spawn.agentSessionId, cwd: session.spawn.cwd })
// The board is the canvas's other view of the same node (CONTRIBUTING), so the card carries the
// node header's account chip from the same helper — created-with account, else what the session
// was observed running as.
const accountChip = useAccountChip(
session.spawn.accountId,
status?.account,
statusStore,
session.spawn.ssh ? sshHostKey(session.spawn.ssh) : undefined
)
// Local drag state only styles THIS card (ghost look) — the drag payload lives in KanbanView.
const [dragging, setDragging] = useState(false)
// Which edge a drag is hovering over → shows the drop line (top = before, bottom = after).
const [dropSide, setDropSide] = useState<'before' | 'after' | null>(null)
const sideFor = (e: React.DragEvent): 'before' | 'after' => {
const r = (e.currentTarget as HTMLElement).getBoundingClientRect()
return e.clientY < r.top + r.height / 2 ? 'before' : 'after'
}
// The board is the canvas's other view of the same sessions and reads the same store, so the
// node's pause/liveness chips (DROPPED, PAUSED, SLEEPING) are badges here too.
// The ONE badge rule, shared with the board's status chips (lib/kanbanStatusChips), so a chip
// can never select cards whose badge says something else. The ranking and its reasons live there.
const badge = cardBadge(session.kind, status)
const stickyPreview = session.kind === 'sticky' ? (session.text ?? '').trim() : ''
const assignees = cardAssignees(meta)
const due = meta?.dueAt
// Not in a done/closed column: the column already settled it (lib/cardRedundancy). The card
// modal's Due strip still says "Overdue".
const overdue = cardShowsOverdue(due, Date.now(), columnCategory)
// The session name is usually the title (agent titles auto-track it) — then the chip repeats it.
const sessionName = status?.session && !sessionNameRepeatsTitle(status.session, session.title)
? status.session
: undefined
const priority = meta?.priority
// The account chip counts as detail in its own right: a card whose only thing to say is "this
// one is on the other Claude login" is exactly the card that must say it.
const hasDetail =
!!status?.sessionId || !!sessionName || !!accountChip || stickyPreview.includes('\n')
return (
<div
className={`kanban-card kanban-card--session${dragging ? ' kanban-card--dragging' : ''}${
dropSide ? ` kanban-card--drop-${dropSide}` : ''
}${selected ? ' kanban-card--selected' : ''}`}
draggable
// Focusable, and named for the board's keyboard (J/K/arrows walk these, Space opens one —
// KanbanView's board-key handler finds the current card through this attribute).
tabIndex={0}
data-kanban-card={session.id}
onDragStart={(e) => {
e.dataTransfer.effectAllowed = 'move'
setDragging(true)
onDragStart(session.id)
}}
onDragEnd={() => {
setDragging(false)
setDropSide(null)
onDragEnd()
}}
onDragOver={(e) => {
e.preventDefault()
const side = sideFor(e)
if (side !== dropSide) setDropSide(side)
}}
onDragLeave={() => setDropSide(null)}
onDrop={(e) => {
e.preventDefault()
e.stopPropagation() // don't let the column's end-drop swallow a drop aimed at this card
const side = sideFor(e)
setDropSide(null)
onDropAt(session.id, side)
}}
// A Shift-click extends the selection; without this it would also sweep a text selection
// across every card in between.
onMouseDown={(e) => {
if (e.shiftKey && onSelectClick) e.preventDefault()
}}
onClick={(e) => {
const mods = { toggle: e.metaKey || e.ctrlKey, range: e.shiftKey }
if (onSelectClick?.(session.id, mods)) return
onOpen(session.id)
}}
onContextMenu={(e) => {
e.preventDefault()
onContext(session.id, e.clientX, e.clientY)
}}
title="Open card"
>
<div className="kanban-card__row">
<span className="kanban-card__nodedot" style={{ background: session.color }} />
<NodeIconView icon={session.icon} size={14} className="kanban-card__icon" />
<span className="kanban-card__title">{session.title}</span>
{session.kind === 'terminal' && onOpenIssue && (
<IssueRefChip issueRef={session.issueRef} onOpen={onOpenIssue} />
)}
{session.kind === 'terminal' && team && team.length > 0 && onTravel && (
<TeamProgressChip stations={team} onTravel={onTravel} statusStore={statusStore} />
)}
{session.kind === 'terminal' && session.pendingLaunch && (
<QueuedLaunchChip
nodeId={session.id}
pending={session.pendingLaunch}
firstOpen={session.launchFirstOpen}
onRun={onRunQueued ? () => onRunQueued(session.id) : undefined}
/>
)}
{/* The canvas node header's Ports chip — one component, so the two views of a session
cannot disagree. It stops its own clicks, so opening it never opens the card. */}
{session.kind === 'terminal' && ports && onOpenPort && (
<PortsChip
nodeId={session.id}
projectId={ports.projectId}
remote={ports.remote}
onOpenUrl={(url) => onOpenPort(session.id, url)}
/>
)}
{session.kind === 'sticky' && <span className="kanban-card__kind">note</span>}
{session.kind === 'browser' && <span className="kanban-card__kind">web</span>}
{badge === 'dropped' && (
<span
className="kanban-badge kanban-badge--dropped"
title="This session's agent process is gone (it did not exit cleanly) — open the card to resume it"
>
DROPPED
</span>
)}
{badge === 'running' && <span className="kanban-badge kanban-badge--running">RUNNING</span>}
{badge === 'needs' && <span className="kanban-badge kanban-badge--needs">NEEDS YOU</span>}
{badge === 'paused' && (
<span
className="kanban-badge kanban-badge--sleeping"
title="Session paused — use Resume session from the node menu to bring it back"
>
PAUSED
</span>
)}
{badge === 'sleeping' && (
<span
className="kanban-badge kanban-badge--sleeping"
title="Agent hibernated to save memory — resumes when you open the session"
>
SLEEPING
</span>
)}
{status?.unread && <span className="kanban-card__unread" />}
</div>
{pulls && pulls.length > 0 && (
<div className="pull-refs pull-refs--session">
{pulls.slice(0, 3).map((pull) => (
<PullRefChip key={pull.number} status={pull} freshness={pullFreshness} />
))}
</div>
)}
{(labels.length > 0 || assignees.length > 0 || due !== undefined || priority !== undefined) && (
<div className="kanban-card__metarow">
{/* Labels share the priority/due/avatars row (left); the meta chips hug the right. */}
<LabelChips labels={labels} size="sm" className="kanban-card__metalabels" />
<div className="kanban-card__metaright">
{priority !== undefined && PRIO_COLOR[priority] && (
<span
className="kanban-due kanban-prio-chip"
style={{ background: `color-mix(in srgb, ${PRIO_COLOR[priority]} 15%, transparent)`, color: PRIO_COLOR[priority] }}
>
{priority.toUpperCase()}
</span>
)}
{due !== undefined && (
<span className={`kanban-due${overdue ? ' kanban-due--overdue' : ''}`}>
{new Date(due).toLocaleDateString(undefined, { day: 'numeric', month: 'short' })}
</span>
)}
{assignees.length > 0 && (
<span className="kanban-card__avatars">
{assignees.slice(0, 3).map((a) => (
<span key={a.name} className="kanban-avatar kanban-avatar--sm" style={{ background: a.color }} title={a.name}>
{(a.name.trim()[0] ?? '?').toUpperCase()}
</span>
))}
{assignees.length > 3 && <span className="kanban-avatar kanban-avatar--sm kanban-avatar--more">+{assignees.length - 3}</span>}
</span>
)}
</div>
</div>
)}
{/* Detail line is ALWAYS visible when the card has something to say (no expand step):
agents show the context meter + session chip; multi-line notes show a preview. */}
{hasDetail && (
<div className="kanban-card__detail" onClick={(e) => e.stopPropagation()}>
{session.kind === 'sticky' ? (
<span className="kanban-card__stickytext">{stickyPreview}</span>
) : (
<>
<ContextMeter sessionId={cardTranscript.sessionId ?? null} fromLaunchId={cardTranscript.fallback} nodeId={session.id} remote={isRemoteSessionNode(session.spawn)} agentId={session.agentId ?? session.spawn.agentId ?? status?.agentId} />
<AccountChip chip={accountChip} />
{sessionName && (
<span className="kanban-card__session" title={sessionName}>
{sessionName}
</span>
)}
</>
)}
</div>
)}
</div>
)
})