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
// "Open recent" — the pure half: where a past conversation should be resumed, and how the list is
// grouped. Canvas executes the plan; nothing here touches a store or the disk.
//
// The rules, each a refusal or a dedupe the feature would be wrong without:
// - A conversation already held by a node (the node's live hook-fed id, else the id it persisted)
// is FOCUSED, never resumed twice — two CLIs writing one transcript interleave it.
// - The session id is re-validated (`canResumeWith` = SAFE_SESSION_ID) before anything is planned:
// it came off disk, and the plan ends with it on a typed command line.
// - Resume happens only in a LOCAL folder project whose cwd is exactly the conversation's. The
// history is this machine's, so an SSH project (its cwd is on the host) and a relay tab (another
// machine's project) never match. No project → offer to open the folder as one.
// - The conversation must run under the account whose config dir holds it: a managed/linked
// account that is gone (or pending, or pinned to a host) refuses rather than resuming under the
// system login, where the CLI would answer "No conversation found".
import type { ClaudeAccount, Project } from '@shared/types'
import type { CodexAccount } from '@shared/codex-account'
import { canResumeWith } from '@shared/agents/config'
import type { RecentConversation } from '@shared/recent-conversations'
export type ResumePlan =
| { kind: 'focus'; nodeId: string; projectId: string }
/** `groupId`: a worktree-bound group frame whose worktree holds the conversation's folder — the
* node opens inside it, so it is where the user's branch work already is. */
| { kind: 'resume'; projectId: string; reopen: boolean; groupId?: string }
| { kind: 'open-folder'; folder: string }
| { kind: 'refuse'; reason: string }
export const RESUME_REFUSALS = {
unsafeId: 'This conversation’s id cannot be put on a command line safely.',
noCwd: 'The history does not say which folder this conversation ran in.',
folderGone:
'The folder this conversation ran in no longer exists (a removed worktree?). Opening it would recreate an empty folder.',
accountGone: 'The account this conversation belongs to is no longer set up on this machine.'
} as const
/** A node's session as the planner needs it: its id, its project, the ids it could be holding. */
export interface HeldSession {
nodeId: string
projectId: string
/** The ONE session this node holds: the live hook-fed id, else the persisted `agentSessionId`.
* Never both — `agentSessionId` is the id minted at launch and nothing rewrites it from hooks,
* so after a `/clear` (live id B) the node no longer holds A, and A must stay resumable. Same
* rule as `closedHistory` (`live || persisted`). */
sessionId: string | undefined
}
/** A worktree-bound group frame on a canvas: its project, its id and its worktree folder. */
export interface WorktreeGroupRef {
projectId: string
groupId: string
path: string
}
export interface ResumeContext {
projects: readonly Pick<Project, 'id' | 'cwd' | 'ssh' | 'closed' | 'unavailable' | 'remote'>[]
activeProjectId: string
held: readonly HeldSession[]
/** Worktree-bound groups (live canvas + stored projects), for a conversation that ran in one. */
worktreeGroups?: readonly WorktreeGroupRef[]
claudeAccounts: readonly Pick<ClaudeAccount, 'id' | 'host' | 'pending'>[]
codexAccounts: readonly Pick<CodexAccount, 'id' | 'host' | 'pending'>[]
}
/** Every node holding a session, from the live canvas (active project) and the stored projects.
* The live copy of the active project wins: the store lags it by an autosave. */
export function heldSessions(
projects: readonly Pick<Project, 'id' | 'nodes'>[],
activeProjectId: string,
liveNodes: ReadonlyArray<{ id: string; data?: { agentSessionId?: unknown } }>,
liveSessionId: (nodeId: string) => string | undefined
): HeldSession[] {
const out: HeldSession[] = []
const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined)
for (const n of liveNodes) {
out.push({
nodeId: n.id,
projectId: activeProjectId,
sessionId: liveSessionId(n.id) || str(n.data?.agentSessionId)
})
}
for (const p of projects) {
if (p.id === activeProjectId && liveNodes.length) continue
for (const n of p.nodes ?? []) {
out.push({
nodeId: n.id,
projectId: p.id,
sessionId: liveSessionId(n.id) || str((n as { agentSessionId?: unknown }).agentSessionId)
})
}
}
return out
}
/** Every worktree-bound group, live canvas first (the store lags it by an autosave). */
export function worktreeGroups(
projects: readonly Pick<Project, 'id' | 'nodes'>[],
activeProjectId: string,
liveNodes: ReadonlyArray<{ id: string; type?: string; data?: { worktree?: unknown } }>
): WorktreeGroupRef[] {
const out: WorktreeGroupRef[] = []
const pathOf = (w: unknown): string | undefined =>
w && typeof w === 'object' && typeof (w as { path?: unknown }).path === 'string'
? (w as { path: string }).path
: undefined
for (const n of liveNodes) {
const p = n.type === 'group' ? pathOf(n.data?.worktree) : undefined
if (p) out.push({ projectId: activeProjectId, groupId: n.id, path: p })
}
for (const pr of projects) {
if (pr.id === activeProjectId && liveNodes.length) continue
for (const n of pr.nodes ?? []) {
const p = n.kind === 'group' ? pathOf((n as { worktree?: unknown }).worktree) : undefined
if (p) out.push({ projectId: pr.id, groupId: n.id, path: p })
}
}
return out
}
export function findHolder(conv: RecentConversation, held: readonly HeldSession[]): HeldSession | undefined {
return held.find((h) => h.sessionId === conv.sessionId)
}
function accountUsable(conv: RecentConversation, ctx: ResumeContext): boolean {
if (!conv.accountId) return true
if (conv.agentId === 'claude') {
return ctx.claudeAccounts.some((a) => a.id === conv.accountId && !a.host && !a.pending)
}
if (conv.agentId === 'codex') {
return ctx.codexAccounts.some((a) => a.id === conv.accountId && !a.host && !a.pending)
}
// Only claude and codex have managed accounts; anything else naming one is not ours to trust.
return false
}
const trimSep = (s: string): string => (s.length > 1 ? s.replace(/[/\\]+$/, '') : s)
/** Length of `dir` when it is `target` or an ANCESTOR of it (segment-wise: `/repo` holds
* `/repo/packages/app`, never `/repository`), else -1. Longer = more specific. */
export function containsDir(dir: string | undefined, target: string): number {
if (!dir) return -1
const d = trimSep(dir)
const t = trimSep(target)
if (t === d) return d.length
const prefixes = /[/\\]$/.test(d) ? [d] : [d + '/', d + '\\']
return prefixes.some((p) => t.startsWith(p)) ? d.length : -1
}
export function planResume(conv: RecentConversation, ctx: ResumeContext): ResumePlan {
// A conversation that is already open is where the user is going, whatever else is true.
const holder = findHolder(conv, ctx.held)
if (holder) return { kind: 'focus', nodeId: holder.nodeId, projectId: holder.projectId }
if (!canResumeWith(conv.agentId, conv.sessionId)) return { kind: 'refuse', reason: RESUME_REFUSALS.unsafeId }
if (!accountUsable(conv, ctx)) return { kind: 'refuse', reason: RESUME_REFUSALS.accountGone }
if (!conv.cwd) return { kind: 'refuse', reason: RESUME_REFUSALS.noCwd }
// Only a DEFINITE absence refuses; `unknown` (a stat that failed otherwise) proceeds.
if (conv.cwdState === 'absent') return { kind: 'refuse', reason: RESUME_REFUSALS.folderGone }
const cwd = conv.cwd
// The most specific owner of the folder wins: a worktree-bound group, or the local project whose
// folder is the conversation's or an ANCESTOR of it (a subfolder like `/repo/packages/app`
// resumes in the `/repo` project, it does not mint a second project inside the repository).
const local = ctx.projects.filter((p) => !p.ssh && !p.remote && !p.unavailable)
const localIds = new Set(local.map((p) => p.id))
const rank = (p: (typeof local)[number]): number =>
p.id === ctx.activeProjectId ? 0 : p.closed ? 2 : 1
let best: { depth: number; projectId: string; groupId?: string; rank: number } | null = null
const consider = (depth: number, projectId: string, groupId?: string): void => {
if (depth < 0) return
const p = local.find((x) => x.id === projectId)!
const r = rank(p)
// Deeper wins; at equal depth a group beats its project, then active > open > closed.
if (
!best ||
depth > best.depth ||
(depth === best.depth && !!groupId && !best.groupId) ||
(depth === best.depth && !!groupId === !!best.groupId && r < best.rank)
) {
best = { depth, projectId, groupId, rank: r }
}
}
for (const p of local) consider(containsDir(p.cwd, cwd), p.id)
for (const g of ctx.worktreeGroups ?? []) {
if (localIds.has(g.projectId)) consider(containsDir(g.path, cwd), g.projectId, g.groupId)
}
const pick = best as { depth: number; projectId: string; groupId?: string; rank: number } | null
if (pick) {
const project = local.find((p) => p.id === pick.projectId)!
return {
kind: 'resume',
projectId: pick.projectId,
reopen: !!project.closed,
...(pick.groupId ? { groupId: pick.groupId } : {})
}
}
return { kind: 'open-folder', folder: cwd }
}
/** The action a row offers, in words. */
export function resumeActionLabel(plan: ResumePlan, projectName: (id: string) => string): string {
switch (plan.kind) {
case 'focus':
return 'Go to node'
case 'resume':
return `Resume in ${projectName(plan.projectId)}`
case 'open-folder':
return 'Open folder & resume'
case 'refuse':
return 'Cannot resume'
}
}
export interface RecentFolderGroup {
/** null = the conversations whose history does not name a folder. */
cwd: string | null
items: RecentConversation[]
}
/** Group by folder, groups ordered by their newest conversation, rows newest-first within. */
export function groupRecentByFolder(items: readonly RecentConversation[]): RecentFolderGroup[] {
const groups = new Map<string, RecentFolderGroup>()
const sorted = [...items].sort((a, b) => b.lastActiveAt - a.lastActiveAt)
for (const it of sorted) {
const key = it.cwd ?? '\0'
let g = groups.get(key)
if (!g) groups.set(key, (g = { cwd: it.cwd, items: [] }))
g.items.push(it)
}
return [...groups.values()]
}
/** The last path segment, for a compact folder label. */
export function folderLabel(cwd: string | null): string {
if (!cwd) return 'Unknown folder'
const segs = cwd.split(/[/\\]+/).filter(Boolean)
return segs[segs.length - 1] ?? cwd
}
/** The display title, never empty. */
export function recentTitle(conv: RecentConversation): string {
return conv.title || `Untitled ${conv.agentId} conversation`
}
/** The managed Codex homes this machine may read: local, settled accounts only (a host-pinned
* account's home is on that host; a pending one has never logged in). */
export function localCodexAccountIds(accounts: readonly Pick<CodexAccount, 'id' | 'host' | 'pending'>[]): string[] {
return accounts.filter((a) => a && typeof a.id === 'string' && !a.host && !a.pending).map((a) => a.id)
}