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.

17.2 KB
Raw Blame
/**
 * What one reader may see of a Swarm's parts (design 4.1): today's `visibleState` rules applied to the reassembled parts,
 * plus the private-conversation check, each record sent in its part's envelope. Time-based and cross-part values go only
 * in `derived`, so a part never changes without a new version (Lead's ruling).
 */
import { machineSuspensionReason, suspendedEngines } from '../engineHealth.js'
import { DISPATCH_RULES, laneOf } from '../dispatch.js'
import { leadChoices } from '../leadStart.js'
import { heldView } from '../heldReason.js'
import { buddyCapOf, isBuddyChat, isBuddyReader } from '../buddies.js'
import { agentForBuddy, agentWithoutMachine, groupForBuddy, machineHiddenFrom, seenMachineIds, visibleState, withSeenRequirement, type Actor, type Agent, type Conversation, type SuperTabState } from '../model.js'
import { availableSlots, slotCounter, machineTeamWork, type ContributedMachine } from '../machines.js'
import * as store from '../parts/index.js'
import type { Part, SwarmParts } from '../parts/index.js'
import { canReadGroup, canReadProject, projectsOf } from '../projects.js'
import { promptWaits } from '../promptWaits.js'
import { storedPulse, type Pulse } from '../pulse.js'
import { coordinatorNameOf, roleNameOf } from '../instructions.js'
import { agentChatId, agentKind, inMyAgents, ledProjects } from '../agentKind.js'
import { withAvatarView } from '../profile.js'
import { swarmUsernames } from '../usernames.js'
import type { AgentView, Derived, GroupView, HeadView, LivePart, MachineView, MemberView, ProgressView, StartView } from './contract.js'

export interface ReaderParts {
  head: LivePart<HeadView>
  members: LivePart<MemberView>[]
  agents: LivePart<AgentView>[]
  groups: LivePart<GroupView>[]
  machines: LivePart<MachineView>[]
  starts: LivePart<StartView>[]
  progress: LivePart<ProgressView>[]
}
export interface ReaderView {
  /** The reassembled stored state the view was made from, for the read checks of changed parts. */
  state: SuperTabState
  parts: ReaderParts
  derived: Derived
}
export interface ReadExtras {
  /** Machines whose account row is a Harness Team account (store read helper). */
  teamMachines: string[]
  /** Machines also contributed to a Swarm of another Workspace (store.ts otherWorkspaceMachines). */
  otherWorkspaceMachines?: string[]
  /** No Harness GitHub App on this server, so Team accounts take no work (store.ts teamAccountsIdle). */
  teamAccountsIdle?: boolean
  /** Each contributed machine's CLI version as its daemon last connected (store.ts machineFacts). */
  machineVersions?: Record<string, string>
  /** A person's open mentions, counted by the store. */
  mentionsWaiting?: number
  /** Which ones they are, as a digest (mentions.ts). */
  mentionsDigest?: string
  /** A person's open decisions (decisions.ts). */
  decisionsWaiting?: number
  /** Which ones they are, as a digest (decisions.ts). */
  decisionsDigest?: string
  /** Which of their Activity rows are unread, as a digest (activity.ts). */
  activityDigest?: string
  /** Which reminders they have and when each is due, as a digest (reminders.ts). */
  remindersDigest?: string
}

const HEAD_FIELDS = ['version', 'id', 'name', 'project', 'projects', 'leadsConversationId', 'ownerId', 'environment',
  'routingPolicy', 'rules', 'paused', 'invitations', 'localModels', 'workspaceId', 'workspaceVisibility', 'buddies', 'removedMachines', 'autoJoin',
  // How many Buddies each person may have (task #3818): apps offer a new one below it.
  'buddyCap'] as const

export const envelope = <T>(part: Pick<Part, 'key' | 'version' | 'changedAt'>, data: T): LivePart<T> =>
  ({ key: part.key, version: part.version, changedAt: part.changedAt, data })

/** A group as readers get it: its message counter, a dormant flag only when dormant, never the store's bookkeeping or the
 *  leaderboard's (the leaderboard read sums it), except when it shipped. */
export function groupView(group: Conversation, seenMachines: ReadonlySet<string>): GroupView {
  const { messageSeq, reportSeq: _report, lastActivityAt: _activity, ledger, proposals: _proposals, owed: _owed, answered: _answered, chatLimits: _chatLimits, talkedAt: _talkedAt, pulse: _pulse, statusLine: _statusLine, dormant, audience, ...rest } = withSeenRequirement(group, seenMachines)
  // A Buddy chat names its owner instead of an audience: an app from before Buddies takes a private chat of the reader
  // alone for their Chat with PM, and would send what they write for the PM to their Buddy instead (buddies.ts).
  const readers = isBuddyChat(group) ? { buddyOwnerId: audience!.people[0]!.id } : audience ? { audience } : {}
  const shippedAt = ledger?.shippedAt
  const held = heldView(group)
  const view: GroupView = { ...rest, messageSeq: messageSeq ?? 0, ...(dormant ? { dormant: true as const } : {}), ...(shippedAt === undefined ? {} : { shippedAt }),
    ...(held ? { held } : {}), ...readers }
  // A task's hand-out lane (dispatch.ts stampLane) is stored with it; only a task stored before that is worked out here.
  if (group.handOutLane === undefined && group.task && !group.reviewOf && !group.kind && !audience) view.handOutLane = laneOf(group, DISPATCH_RULES.lanes)
  return view
}

/** A conversation's whole data as the reader may see it: a task's requirement lists only the machines they see. */
export function visibleGroupView(group: Conversation, _visibleAgents: ReadonlySet<string>, seenMachines: ReadonlySet<string>): GroupView {
  return groupView(group, seenMachines)
}

/** The machines a reader's view shows them: listed, or running an agent they see (model.ts seenMachineIds). */
export const seenIn = (parts: ReaderView['parts']): Set<string> =>
  new Set([...parts.machines.map(m => m.key), ...parts.agents.map(a => a.data.machineId)])

export function agentView(agent: Agent): AgentView {
  // A main project goes in the derived row, to its project's readers only: a private one's id says the project exists. A
  // Member's mark and its set-up record name it too (members.ts; security review 2 of #3575), and are its host's alone
  // (read/hostRows.ts sends the agent as stored).
  const { downNamed: _named, downSince: _since, limitedUntil: _limit, roleId: _role, mainProjectId: _main, member: _member, setUp: _setUp, ...rest } = agent
  return withAvatarView(rest) as AgentView
}

/** `state` is the parts already reassembled, when the caller has it (a read reassembles once). */
export function readerView(parts: SwarmParts, actor: Actor, now: number, extras: ReadExtras, state = store.reassemble(parts, { share: true })): ReaderView {
  const visible = visibleState(state, actor, now)
  const groups = visible.conversations.filter(group => canReadGroup(state, actor, group))
  const readable = new Set(groups.map(g => g.id))
  const part = <T>(list: Part<T>[]) => { const keyed = new Map(list.map(p => [p.key, p])); return (key: string) => keyed.get(key)! }
  const agentPart = part(parts.agents), groupPart = part(parts.groups), machinePart = part(parts.machines), startPart = part(parts.starts)
  const head = Object.fromEntries(HEAD_FIELDS.filter(field => visible[field] !== undefined).map(field => [field, visible[field]])) as HeadView
  // Every project names its coordinator; one from before the field reads as the Product Manager (instructions.ts). The built-in
  // schedule's slot is the coordinator poll's bookkeeping (pmSchedule.ts), like progress, and so is the release list (releases.ts):
  // no reader shows them. What the PM owes is its host's alone (timeChecks.ts owedAsk): it may name a message in someone's private chat.
  if (head.projects) head.projects = head.projects.map(({ progress: _progress, schedule: _schedule, releases: _releases, owed: _owed, ...project }) => ({ ...project, coordinatorName: coordinatorNameOf(project) }))
  head.invitations = visible.invitations.filter(i => readable.has(i.conversationId))
  // Always, its default too (task #3818): an app offers several Buddies only where the head says how many, so an older backend,
  // which sends none, is never taken for one that makes them.
  head.buddyCap = buddyCapOf(state)
  const projects = new Set((visible.projects ?? []).map(p => p.id)), seen = seenMachineIds(visible), names = swarmUsernames(state)
  const buddy = isBuddyReader(state, actor)
  return {
    state,
    parts: {
      head: envelope(parts.head, head),
      // Each person's username as the Swarm shows it, worked out in join order (the reassembled state's), never the order
      // member parts happen to load in.
      members: parts.members.filter(m => !m.deleted).map(m => envelope(m, { ...withAvatarView(m.data!), username: names.get(m.key) } as MemberView)),
      agents: visible.agents.map(a => {
        const stored = state.agents.find(s => s.id === a.id)!
        const view = agentView(stored)
        return envelope(agentPart(a.id), buddy && actor.kind === 'agent' ? agentForBuddy(view, actor.agentId)
          : machineHiddenFrom(state, actor, stored) ? agentWithoutMachine(view) : view)
      }),
      groups: groups.map(g => envelope(groupPart(g.id), groupView(buddy ? groupForBuddy(g) : g, seen))),
      machines: (visible.machines ?? []).map(m => envelope(machinePart(m.machineId), m)),
      starts: (visible.starts ?? []).filter(s => readable.has(s.request.conversationId)).map(s => envelope(startPart(s.id), s)),
      progress: parts.progress.filter(p => !p.deleted && projects.has(p.key)).map(p => envelope(p, progressView(p.data!))),
    },
    derived: derive(state, visible, actor, now, extras),
  }
}

export const progressView = (data: NonNullable<SwarmParts['progress'][number]['data']>): ProgressView =>
  ({ ...data, requestedAt: data.requestedAt ?? null })

/** The board's pulse of each project the reader sees (pulse.ts, task #3384), as last recorded on its chat: the same from a full
 *  read and from a change poll's light base, which keeps the project chats and their pulse (parts/light.ts). A project with
 *  none recorded yet is left out, and the board draws no strip. Its lists name conversations: a project's reader reads every
 *  one of them (none is private: pulse.ts counted), each checked again where it is loaded; a Buddy reads only its person's
 *  own, so it gets the counts alone, the same on every read. */
function pulses(state: SuperTabState, visible: SuperTabState, actor: Actor, buddy: boolean): Record<string, Pulse> | undefined {
  if (!visible.projects?.length) return undefined
  // One lookup by id for every listed conversation: a list names up to 50 per count (pulse.ts PULSE_LIST_MAX).
  const groups = new Map(state.conversations.map(c => [c.id, c])), checked = new Map<string, boolean>()
  const reads = (id: string) => {
    const known = checked.get(id)
    if (known !== undefined) return known
    const group = groups.get(id)
    const readable = !group || canReadGroup(state, actor, group)
    checked.set(id, readable)
    return readable
  }
  const out: Record<string, Pulse> = {}
  for (const seen of visible.projects) {
    const project = state.projects?.find(p => p.id === seen.id)
    const pulse = project && storedPulse(state, project)
    if (!pulse) continue
    out[project.id] = buddy ? countsOnly(pulse) : { ...pulse,
      asks: { ...pulse.asks, list: pulse.asks.list.filter(ask => reads(ask.conversationId)) },
      nextUp: { ...pulse.nextUp, conversationIds: pulse.nextUp.conversationIds.filter(reads) },
      lost: { ...pulse.lost, conversationIds: pulse.lost.conversationIds.filter(reads) },
      held: { ...pulse.held, list: pulse.held.list.filter(hold => reads(hold.conversationId)) } }
  }
  return out
}

/** [pulse] without its lists: what a Buddy reader gets. */
const countsOnly = (pulse: Pulse): Pulse => ({ ...pulse, asks: { ...pulse.asks, list: [] }, working: { ...pulse.working, agentIds: [] },
  nextUp: { ...pulse.nextUp, conversationIds: [] }, lost: { ...pulse.lost, conversationIds: [] }, held: { ...pulse.held, list: [] } })

function derive(state: SuperTabState, visible: SuperTabState, actor: Actor, now: number, extras: ReadExtras): Derived {
  // Where New Project's Product Manager would run on each teammate's machine, decided as its start decides (leadStart.ts).
  const leads = actor.kind === 'person' && state.people.find(p => p.id === actor.userId)?.role !== 'viewer'
    ? leadChoices(state, actor.userId, { now, teamMachines: extras.teamMachines, otherWorkspaceMachines: extras.otherWorkspaceMachines ?? [],
      ...(extras.teamAccountsIdle ? { teamAccountsIdle: true } : {}) })
    : {}
  // Every listed machine's slots from one pass over the Swarm's lists (machines.ts slotCounter).
  const slots = slotCounter(state)
  const machine = (pool: ContributedMachine) => {
    const stored = state.machines!.find(m => m.machineId === pool.machineId)!
    const refusal = machineTeamWork(stored, now, extras.teamMachines, extras.otherWorkspaceMachines ?? [])
    const version = extras.machineVersions?.[pool.machineId]
    const suspended = suspendedEngines(stored, now)
    const machineSuspended = machineSuspensionReason(stored, now)
    return [pool.machineId, { availableSlots: availableSlots(state, stored, slots(stored)),
      teamWork: refusal ? { allowed: false as const, ...refusal } : { allowed: true as const }, ...(version ? { clientVersion: version } : {}),
      ...(Object.keys(suspended).length ? { suspendedEngines: suspended } : {}), ...(machineSuspended ? { machineSuspended } : {}), ...(leads[pool.machineId] ? { lead: leads[pool.machineId] } : {}) }] as const
  }
  const pulse = pulses(state, visible, actor, isBuddyReader(state, actor))
  // Each visible agent's stored row, looked up once rather than once per derived field.
  const storedAgents = new Map(state.agents.map(a => [a.id, a]))
  // Whether the reader reads each project, worked out once for every agent naming it as its main project.
  const projectReads = new Map<string, boolean>()
  const readsProject = (id: string) => {
    let reads = projectReads.get(id)
    if (reads === undefined) {
      const project = projectsOf(state).find(p => p.id === id)
      projectReads.set(id, reads = !!project && canReadProject(state, actor, project))
    }
    return reads
  }
  // A Lead's main project is the one it leads; a Member's, the one its person picked (task #4540).
  const led = ledProjects(state)
  const shownMain = (agent: Agent) => { const main = led.get(agent.id) ?? agent.mainProjectId; return main && readsProject(main) ? main : null }
  // The next release times the settle recorded (releases.ts), for the projects this reader sees: the release list itself stays
  // the server's (task #3827).
  const releaseTimes = Object.fromEntries(visible.projects?.flatMap(seen => {
    const nextAt = state.projects?.find(p => p.id === seen.id)?.releases?.nextAt
    return nextAt ? [[seen.id, nextAt] as const] : []
  }) ?? [])
  return {
    ...(pulse ? { pulse } : {}),
    ...(Object.keys(releaseTimes).length ? { releaseTimes } : {}),
    agents: Object.fromEntries(visible.agents.map(seen => {
      const stored = storedAgents.get(seen.id)!
      return [seen.id, { downSince: seen.downSince ?? null, limitedUntil: seen.limitedUntil ?? null,
        workDecision: seen.workDecision === 'awaiting' && stored.workDecision !== 'awaiting' ? 'awaiting' as const : null,
        roleId: seen.roleId ?? null,
        // Derived on every read: who leads a project, and its role set, live outside the agent's own part.
        roleName: roleNameOf(state, stored),
        // What it is and where its person talks to it, for the left pane's "My agents" (agentKind.ts, task #4116).
        kind: agentKind(state, stored), chatId: agentChatId(state, stored),
        // Whether it is in this reader's My agents, decided here so every client lists the same (task #4192).
        myAgent: inMyAgents(state, actor, stored),
        // Lead or Member, and its main project (agentKind.ts, task #4540).
        role: led.has(stored.id) ? 'lead' as const : 'member' as const, mainProjectId: shownMain(stored) }]
    })),
    machines: Object.fromEntries((visible.machines ?? []).map(machine)),
    ...(visible.otherProjectsWork ? { otherProjectsWork: visible.otherProjectsWork } : {}),
    ...(visible.pmAccounts ? { pmAccounts: visible.pmAccounts } : {}),
    ...(visible.ownerlessProjects ? { ownerlessProjects: visible.ownerlessProjects } : {}),
    ...(actor.kind === 'person' && extras.mentionsWaiting !== undefined ? { mentionsWaiting: extras.mentionsWaiting } : {}),
    ...(actor.kind === 'person' && extras.mentionsDigest !== undefined ? { mentionsDigest: extras.mentionsDigest } : {}),
    ...(actor.kind === 'person' && extras.decisionsWaiting !== undefined ? { decisionsWaiting: extras.decisionsWaiting } : {}),
    ...(actor.kind === 'person' && extras.decisionsDigest !== undefined ? { decisionsDigest: extras.decisionsDigest } : {}),
    // Its agents waiting at a prompt in their tasks, under Decisions (promptWaits.ts): from the live state, every read.
    ...(actor.kind === 'person' ? { promptsWaiting: promptWaits(state, actor) } : {}),
    ...(actor.kind === 'person' && extras.activityDigest !== undefined ? { activityDigest: extras.activityDigest } : {}),
    ...(actor.kind === 'person' && extras.remindersDigest !== undefined ? { remindersDigest: extras.remindersDigest } : {}),
    threadSessions: true as const,
    sessionsFromChat: true as const,
    // One Buddy per person per Swarm (Dee, 10-31): an app shows # buddy and New session in a project only when the server says so.
    swarmBuddy: true as const,
  }
}