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.

14.8 KB
Raw Blame
/**
 * What the agent verbs show, as pure functions of what the daemon answers (docs/design/2026-10-11-agent-client.md):
 * a harness's row in `harness ps`, which harness a name means, and its last turn from a page of its transcript.
 */
import { PTY_HOST_PANE } from '../lib/ptyHost/instance.js'
import { engineName } from '../messages/model.js'
import type { Ledger, LedgerMember } from './ledger.js'

/** The part of the daemon's `AgentFrame` (lib/agentFrame.ts) the verbs read. */
export interface Frame {
  id: string
  sessionId?: string
  name?: string
  title?: string | null
  engine?: string
  status?: string
  activity?: { state?: string } | null
  tmuxPane?: string | null
  /** Where it runs: a PTY host's pane is named by its instance and pane (Windows). */
  terminal?: { runtimes?: Array<{ backend?: string; instance?: string; paneId?: string }> } | null
  project?: { cwd?: string; root?: string; branch?: string | null; worktree?: boolean } | null
  createdAt?: string
  updatedAt?: string
  /** The harness here whose agent started this one (registry `parentAgentId`); null for the rest. */
  parentAgentId?: string | null
  /** `agent` when another agent started it, here or from another machine or outside Harness. */
  startedBy?: string | null
  /** `cloud`: a harness in its maker's cloud (lib/cloudAgents.ts), with no pane and no session. Its state and words are
   *  the cloud service's: `cloud.state` and `cloud_transcript`. */
  location?: string
  cloud?: {
    state?: string
    activity?: string | null
    links?: Array<{ label: string; url: string }>
    /** The maker's own status. Absent for a harness saved before it was kept, and for Fo and Cursor. */
    providerStatus?: { status?: string | null; detail?: string | null } | null
  } | null
}

/** The agent running the verb: a harness in its own pane, or an agent outside Harness. Null for a person at a terminal. */
export interface Caller extends LedgerMember {
  name: string
  engine: string
  /** An agent Harness did not start (in a terminal app, an editor, the person's own tmux): no pane, so nothing can
   *  message it, and it is told apart by the session its shell names. */
  outside?: boolean
  /** Another agent started this harness, as the core's row says (`startedBy`, `parentAgentId`): one level down. */
  startedByAgent?: boolean
}

/** `installing`, `starting`, `failed`: a harness asked for that has not started (commands.ts `Asked`). */
export type State = 'working' | 'idle' | 'needs-input' | 'stopped' | 'offline' | 'unknown' | 'installing' | 'starting' | 'failed'

export interface Row {
  name: string
  id: string
  agent: string
  machine: string
  state: State
  folder: string | null
  branch: string | null
  /** 'person', 'you' (the caller), or the name of the harness that started it. */
  startedBy: string
  /** The caller started it: it may send it work and close it. */
  yours: boolean
  /** This is the caller's own harness. */
  self: boolean
  lastActive: string | null
  /** The person's last asks and the last turns' summaries, newest first, when the daemon has them. */
  asks?: string[]
  about?: string
  /** A cloud harness's maker state, beside [state]. Absent for a harness on this machine. */
  cloud?: CloudMeta
}

/** What `ps`, `show` and `wait` JSON say about a cloud harness, beside Harness's own state. */
export interface CloudMeta {
  state: string
  activity: string | null
  providerStatus?: { status: string | null; detail: string | null }
}

/** How long a stopped harness stays one to list: what ⌘B offers (desktop task_route.dart `stoppedSessionsWithin`). */
export const STOPPED_WITHIN_MS = 7 * 24 * 60 * 60_000

export const isAgent = (frame: Frame): boolean => !!frame.id && frame.engine !== 'terminal'

/** A cloud harness's `cloud.state` (lib/cloudAgents.ts `CloudState`). Its frame's activity says idle while it asks the
 *  person, so a wait read it as done (lampOS, #1444). */
const CLOUD_STATES: Record<string, State> = {
  starting: 'starting', working: 'working', needs_input: 'needs-input', idle: 'idle', failed: 'failed', stopped: 'stopped',
}

/** A cloud harness's maker state from its frame, for `ps`, `show` and `wait` JSON. Nothing for any other harness,
 *  and no `providerStatus` when the frame has none: an older harness, or Fo and Cursor. */
export function cloudMeta(frame: Frame): CloudMeta | undefined {
  if (frame.location !== 'cloud' || !frame.cloud || typeof frame.cloud.state !== 'string') return undefined
  const raw = frame.cloud.providerStatus
  const providerStatus = raw && typeof raw === 'object'
    ? { status: typeof raw.status === 'string' ? raw.status : null, detail: typeof raw.detail === 'string' ? raw.detail : null }
    : undefined
  return { state: frame.cloud.state, activity: typeof frame.cloud.activity === 'string' ? frame.cloud.activity : null, ...(providerStatus ? { providerStatus } : {}) }
}

export function stateOf(frame: Frame): State {
  if (frame.status === 'stopped') return 'stopped'
  if (frame.status === 'offline') return 'offline'
  if (frame.location === 'cloud') return CLOUD_STATES[frame.cloud?.state ?? ''] ?? 'unknown'
  const state = frame.activity?.state
  return state === 'working' ? 'working' : state === 'idle' ? 'idle' : 'unknown'
}

/**
 * The harness on [pane] in [frames], when it is an agent: who is calling. Null only for a person: a terminal's pane,
 * or one Harness does not know. Matching active harnesses only made an agent the person, with the person's right to
 * close anything, whenever the daemon listed it offline for a moment (found by e2e/agentClient.e2e.ts). A stopped
 * harness keeps no pane (`toStoppedProject`), so an old pane number never matches one.
 *
 * A pane on Windows is named `<instance>:%N` (HARNESS_PANE), and `tmuxPane` holds only its %N, which restarts in every PTY
 * host. So it is matched on the frame's runtime: comparing it with `tmuxPane` found no harness on Windows at all, and every
 * agent there read as a person.
 */
export function callerOf(frames: Frame[], pane: string | undefined, machineId: string): Caller | null {
  if (!pane) return null
  const pty = PTY_HOST_PANE.exec(pane)
  const on = frames.filter((f) => f.tmuxPane === pane
    || !!pty && f.terminal?.runtimes?.some(r => r.backend === 'ptyhost' && r.instance === pty[1] && r.paneId === pty[2]))
  const frame = on.find((f) => f.status === 'active') ?? on.filter(isAgent).sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''))[0]
  if (!frame || !isAgent(frame)) return null
  return { machineId, agentId: frame.id, name: frame.name || frame.id.slice(0, 8), engine: frame.engine ?? '', ...(frame.startedBy === 'agent' || frame.parentAgentId ? { startedByAgent: true } : {}) }
}

/**
 * The agent outside Harness whose shell runs this, as the agent marks the shells it runs commands in: Claude Code sets
 * CLAUDECODE and its session's id, Codex its thread's id, and others AI_AGENT. Taken for the person, an agent from
 * outside had no limits and could close every harness on the machine. One session is one caller, so what one Claude
 * Code session started another may not close; an agent that names only itself (AI_AGENT) is one caller for all its
 * sessions.
 */
export function outsideCaller(env: NodeJS.ProcessEnv, machineId: string): Caller | null {
  const claude = env.CLAUDECODE === '1' ? env.CLAUDE_CODE_SESSION_ID?.trim() : ''
  if (claude) return { machineId, agentId: `claude-code:${claude}`, name: 'Claude Code', engine: 'claude', outside: true }
  const codex = env.CODEX_THREAD_ID?.trim()
  if (codex) return { machineId, agentId: `codex:${codex}`, name: 'Codex', engine: 'codex', outside: true }
  // "claude-code_2-1-296_agent": the agent's name, then its version.
  const named = (env.AI_AGENT?.trim() || (env.CLAUDECODE === '1' ? 'claude-code' : '')).split('_')[0].slice(0, 40)
  if (!named) return null
  // A wrapper that knows the session when the agent does not say it: `harness mcp`, one server a session.
  const session = env[AGENT_SESSION_ENV]?.trim().slice(0, 80)
  const engine = named === 'claude-code' ? 'claude' : named
  return { machineId, agentId: `agent:${named}${session ? `:${session}` : ''}`, name: AGENT_NAMES[named] ?? engineName(engine), engine, outside: true }
}

/** Agents that are not an engine Harness runs, by the name they give. */
const AGENT_NAMES: Record<string, string> = { 'claude-desktop': 'Claude Desktop', windsurf: 'Windsurf', cline: 'Cline', zed: 'Zed' }

/** Set beside AI_AGENT by what runs `harness` for an agent and knows its session (`harness mcp`): one caller a session. */
export const AGENT_SESSION_ENV = 'HARNESS_AGENT_SESSION'

export interface RowContext {
  machineId: string
  machine: string
  caller: Caller | null
  ledger: Ledger
  now: number
  /** Include stopped harnesses (within a week). */
  all: boolean
}

export function rowsOf(frames: Frame[], ctx: RowContext): Row[] {
  const rows: Row[] = []
  for (const frame of frames) {
    if (!isAgent(frame)) continue
    const state = stateOf(frame)
    const last = frame.updatedAt ? Date.parse(frame.updatedAt) : NaN
    if (state === 'stopped' && (!ctx.all || !(ctx.now - last < STOPPED_WITHIN_MS))) continue
    const cloud = cloudMeta(frame)
    const member = { machineId: ctx.machineId, agentId: frame.id }
    const you = ctx.caller?.agentId === frame.id && ctx.caller.machineId === ctx.machineId
    const parent = ctx.ledger.parentOf(member)
    const yours = !!ctx.caller && !!parent && parent.by.machineId === ctx.caller.machineId && parent.by.agentId === ctx.caller.agentId
    rows.push({
      name: frame.name || frame.id.slice(0, 8),
      id: frame.id,
      agent: engineName(frame.engine ?? ''),
      machine: ctx.machine,
      state,
      folder: frame.project?.worktree && frame.project.root ? frame.project.root : frame.project?.cwd ?? null,
      branch: frame.project?.branch ?? null,
      startedBy: yours ? 'you' : parent ? parent.by.name || parent.by.agentId.slice(0, 8) : 'person',
      yours,
      self: you,
      lastActive: Number.isFinite(last) ? new Date(last).toISOString() : null,
      ...(cloud ? { cloud } : {}),
    })
  }
  // Working first, then by last activity: what an agent choosing where work goes looks at first.
  const rank = (r: Row): number => (r.state === 'working' || r.state === 'needs-input' ? 0 : r.state === 'idle' || r.state === 'unknown' ? 1 : 2)
  return rows.sort((a, b) => rank(a) - rank(b) || (b.lastActive ?? '').localeCompare(a.lastActive ?? ''))
}

/** How many rows an agent's `ps` shows unless asked for all: on the owner's Mac, 40 rows became about 8 to read. */
export const AGENT_ROWS = 15

/** An agent's `ps`: its own first, then those working or waiting on the person, then the rest; [max] at most. */
export function forAgent(rows: readonly Row[], max = AGENT_ROWS): { shown: Row[]; more: number } {
  const busy = (r: Row) => r.state === 'working' || r.state === 'needs-input'
  const ordered = [...rows.filter((r) => r.yours), ...rows.filter((r) => !r.yours && busy(r)), ...rows.filter((r) => !r.yours && !busy(r))]
  return { shown: ordered.slice(0, max), more: Math.max(0, ordered.length - max) }
}

/** The rows [name] means: a whole name, else a name's start, else an id's start (six characters or more). */
export function matching<T extends { name: string; id: string }>(name: string, rows: T[]): T[] {
  const wanted = name.trim().toLowerCase()
  if (!wanted) return []
  const exact = rows.filter((r) => r.name.toLowerCase() === wanted || r.id.toLowerCase() === wanted)
  if (exact.length) return exact
  const prefix = rows.filter((r) => r.name.toLowerCase().startsWith(wanted))
  if (prefix.length) return prefix
  return wanted.length >= 6 ? rows.filter((r) => r.id.toLowerCase().startsWith(wanted)) : []
}

/** One transcript event as the daemon's history reader answers it (`session_get`). */
export interface HistoryEvent { type?: string; payload?: Record<string, unknown> }

export interface LastTurn {
  ask: string | null
  answer: string
  tools: number
  /** It has answered: there is text after its last tool call. A turn still at work may have said something since
   *  its last tool too, so this alone never means done; `wait` also needs the screen idle, twice. */
  answered: boolean
}

const text = (value: unknown): string => (typeof value === 'string' ? value : '')

/**
 * What a harness was asked, as the person said it: without the markers Claude Code puts around a paste. `ps` and
 * `show` printed `asked: another agent release: <pasted_content id="1c18"> #1242 is merged…` (October 12, 2026).
 * What was pasted stays: it was said. A marker on a line of its own goes with its line; one inside a line, as the
 * daemon keeps an ask (on one line), leaves a space.
 */
const PASTE_TAG = '<\\/?pasted_content\\b[^>]*>'
const PASTE_LINE = new RegExp(`^[^\\S\\n]*${PASTE_TAG}[^\\S\\n]*\\n?`, 'gm')
const PASTE_INLINE = new RegExp(`[^\\S\\n]*${PASTE_TAG}[^\\S\\n]*`, 'g')
export const asSaid = (ask: string): string => ask.replace(PASTE_LINE, '').replace(PASTE_INLINE, ' ').replace(/\n{3,}/g, '\n\n').trim()

/**
 * The last turn in [events], oldest first: the last ask, and the answer, which is the text after the turn's last
 * tool call (the narration before it is the working, not the result). Null when the page holds no ask.
 *
 * `done` says nothing here: Claude Code's and Codex's history readers end every newest page with one
 * (`{ result: 'success' }`, claude/normalize.ts), whether the turn ended or not. Read as the end of the turn, it
 * made `wait` return at once after a `send` and `show` print "success" for a turn of tool calls (the review of
 * #1180).
 */
export function lastTurn(events: HistoryEvent[]): LastTurn | null {
  let start = -1
  for (let i = events.length - 1; i >= 0; i--) if (events[i].type === 'user_message') { start = i; break }
  if (start < 0) return null
  const turn = events.slice(start + 1)
  let lastTool = -1, tools = 0
  turn.forEach((e, i) => { if (e.type === 'tool_start') tools++; if (e.type === 'tool_end' || e.type === 'tool_start') lastTool = i })
  const said = (from: number) => turn.slice(from).filter((e) => e.type === 'text_delta').map((e) => text(e.payload?.content)).join('').trim()
  const final = said(lastTool + 1)
  return { ask: asSaid(text(events[start].payload?.content)) || null, answer: final || said(0), tools, answered: !!final }
}

/** A cloud harness's last turn from its conversation (`cloud_transcript`): the person's last words and everything the
 *  agent said after them. */
export function cloudTurn(messages: ReadonlyArray<{ from?: unknown; text?: unknown }>): LastTurn | null {
  let start = -1
  for (let i = messages.length - 1; i >= 0; i--) if (messages[i].from === 'person') { start = i; break }
  if (start < 0) return null
  const answer = messages.slice(start + 1).filter((m) => m.from === 'agent').map((m) => text(m.text).trim()).filter(Boolean).join('\n\n')
  return { ask: text(messages[start].text) || null, answer, tools: 0, answered: !!answer }
}

export const clip = (value: string, max: number): string => (value.length > max ? `${value.slice(0, max - 1)}…` : value)