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.3 KB
Raw Blame
import type { FastifyRequest } from 'fastify'
import type { Machine, Prisma } from '@prisma/client'
import { machineAlive, prisma } from './prisma.js'
import { machineBillingAllowsDataPlane } from './billingState.js'
import { AppError } from '../errors/index.js'
import type { AuthUser } from './ssoAuth.js'

/**
 * Team sessions (docs/plans/2026-10-24-swarm-team-account.md, Task 1).
 *
 * Teammates' Swarm agents run on a person's Mac inside a separate standard macOS user, whose own Harness daemon signs
 * in to the person's account. With a computer's sign-in that daemon could reach the person's other machines through
 * the relay (`harness ps --machine …`, `harness show`, `harness new` there), read the account over REST and act in a
 * Swarm as the person. So it signs in with a TEAM session instead (lib/harnessSession.ts): minted only by one of the
 * account's computers, bound to the computer that redeemed it, and able to do strictly less than a computer.
 *
 * Every limit is the server's; none relies on the CLI behaving:
 *  - Authentication (lib/ssoAuth.ts) refuses a team session unless the caller passes `allowTeamSession`, and only two
 *    callers do: the REST gate below and the machine socket. So the web relay (`machine_select` and attach,
 *    lib/webWs.ts), the device lane (lib/deviceWs.ts), Agent Messages (lib/agentMessagesWs.ts), the observer socket
 *    (lib/observerWs.ts) and the phone's routes refuse it, and so will any socket added later.
 *  - REST (`teamRequestAllowed`, run by middlewares/authMiddleware.ts for every team request): deny by default.
 *    TEAM_ROUTES is the whole list; a route whose path names a machine must name this session's own.
 *  - The machine socket (lib/adapterWs.ts): only as its own computer's machine, and only while that row is marked
 *    `team` (`Machine.sessionKind`). It hears only device-key pushes, never the account's grid name, raises no pairing
 *    notice on the person's apps, and may take only its own key off the device key log (lib/deviceKeyLog.ts).
 *  - The Super Tab store (superTabs/store.ts, native.ts): never the person; as an agent only one running on its own
 *    machine; host routes only for its own machine; no machine contribution, pause or removal; and no command that
 *    starts, adds, moves or drives an agent on another machine.
 *
 * The other direction stays open: the person's own apps select the team machine like any of theirs, and Swarm members'
 * read-only views of its agents reach it through the shares its daemon publishes (routes/harnessShares.ts).
 */

export const TEAM_SESSION_LIMITED = 'TEAM_SESSION_LIMITED'
export const TEAM_SESSION_MESSAGE = 'A team sign-in can only run Swarm agents on its own machine.'

/**
 * A computer turning ITSELF into a team machine (`harness team on`, a machine used only for agents) keeps its computer
 * id, so its Swarm contributions and history survive. Only that computer may ask (routes/auth.ts): its own Harness
 * computer session, or any sign-in of the account carrying this message signed by the computer's machine key on the
 * account's device key log (lib/deviceKeyLog.ts) — what an Autonomous sign-in, which names no computer, can show.
 * The signature is ed25519 over these UTF-8 bytes, base64; `at` is milliseconds since the epoch.
 */
export function teamConversionMessage(userId: string, computerId: string, machineId: string, at: number): string {
  return `harness team conversion v1\n${userId}\n${computerId}\n${machineId}\n${at}`
}
/** How far a conversion proof's `at` may be from the server's clock, either way. A proof is good once. */
export const TEAM_CONVERSION_PROOF_MS = 5 * 60_000
/** Sent down to a machine its computer just converted: a socket still connected under the old sign-in closes. */
export const TEAM_CONVERTED_FRAME = '__team_converted'

export function isTeamSession(user: Pick<AuthUser, 'harnessSessionKind'> | null | undefined): boolean {
  return user?.harnessSessionKind === 'team'
}

type MachineReader = Pick<Prisma.TransactionClient, 'machine'>

/**
 * The machine a team session acts for: the account's live remote machine for the session's computer. Null for any
 * other session, and while there is none to act for — not registered yet, removed from the account, unpaid, or any
 * live row for that computer held by a normal sign-in (which would make it the person's machine, not a team one).
 */
export async function teamMachine(user: AuthUser, db: MachineReader = prisma): Promise<Machine | null> {
  if (!isTeamSession(user) || !user.harnessComputerId) return null
  const rows = await db.machine.findMany({
    where: { userId: user.sub, computerId: user.harnessComputerId, authMode: 'remote', autonomousEnv: user.autonomousEnv, ...machineAlive },
    orderBy: { createdAt: 'asc' },
  })
  if (rows.some(row => row.sessionKind !== 'team')) return null
  return rows.find(row => machineBillingAllowsDataPlane(row)) ?? null
}

/** For a handler that serves a team session too: null for any other session, else the id of the machine it acts for.
 *  A team session with no machine to act for is refused. */
export async function teamMachineScope(user: AuthUser, db: MachineReader = prisma): Promise<string | null> {
  if (!isTeamSession(user)) return null
  const machine = await teamMachine(user, db)
  if (!machine) throw new AppError(TEAM_SESSION_MESSAGE, 403, TEAM_SESSION_LIMITED)
  return machine.machineId
}

/**
 * How a route on the list is held to the session's machine:
 *  - `open`: needs no machine yet (reading the device keys, registering its own computer — whose handler checks it);
 *  - `machine`: the path's `:machineId` must be its machine;
 *  - `agent`: speaks as one of its agents, so `asAgentId` is required; the store checks that agent runs on its machine;
 *  - `bound`: its machine must exist; the handler or store checks what the body or path names against it.
 */
export type TeamRouteScope = 'open' | 'machine' | 'agent' | 'bound'
export interface TeamRoute {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE'
  url: string
  scope: TeamRouteScope
  /** The body names a machine (`machineId`): it must name this session's own, checked once the body is read. */
  bodyMachine?: true
}

/** Everything a team daemon may call over REST: what it needs to run its own machine and host Swarm agents there. Sign-in
 *  renewal and sign-out (`/api/auth/refresh`, `/api/auth/revoke`) take the refresh token, not a session, and are open
 *  to every session already. Anything else answers 403 `TEAM_SESSION_LIMITED`. Pinned to the route table by a test. */
export const TEAM_ROUTES: readonly TeamRoute[] = [
  // Its own machine: registered before its socket dials, and the account's device keys, which say whom to let in.
  { method: 'POST', url: '/api/machines/resolve-computer', scope: 'open' },
  { method: 'GET', url: '/api/device-keys', scope: 'open' },
  // The Swarm host loop for its machine.
  { method: 'GET', url: '/api/super-tabs/hosts/:machineId', scope: 'machine' },
  { method: 'GET', url: '/api/super-tabs/hosts/:machineId/pools', scope: 'machine' },
  { method: 'GET', url: '/api/super-tabs/hosts/:machineId/assignments', scope: 'machine' },
  // The host loop by parts (docs/design/2026-10-26-swarm-state-parts.md 4.10). The three reads above answer 426 now; they
  // stay listed so an old team daemon is told to update rather than refused.
  { method: 'GET', url: '/api/super-tabs/hosts/:machineId/changes', scope: 'machine' },
  // The same read with the etags the host holds, in a body (too many for a URL).
  { method: 'POST', url: '/api/super-tabs/hosts/:machineId/changes', scope: 'machine' },
  { method: 'POST', url: '/api/super-tabs/hosts/:machineId/terminal', scope: 'machine' },
  { method: 'GET', url: '/api/super-tabs/hosts/:machineId/starts/:tabId/:startId', scope: 'machine' },
  { method: 'POST', url: '/api/super-tabs/hosts/:machineId/starts/:tabId/:startId', scope: 'machine' },
  // A read-only token for a queued start's repository, to clone and fetch its folder before the agent exists: a team account
  // has no git login of its own (routes/superTabs.ts).
  { method: 'POST', url: '/api/super-tabs/hosts/:machineId/starts/:tabId/:startId/github-token', scope: 'machine' },
  { method: 'POST', url: '/api/super-tabs/:tabId/machines/:machineId', scope: 'machine' },
  // The same readings for all of its Swarms in one call (DB roadmap 2.5).
  { method: 'POST', url: '/api/super-tabs/hosts/:machineId/readings', scope: 'machine' },
  // Reads as one of its agents.
  { method: 'GET', url: '/api/super-tabs/:tabId', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/parts', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/changes', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/groups', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/groups/:conversationId', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/starts/:startId', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/routing-policy', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/route-decisions', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/route-decisions/:decisionId', scope: 'agent' },
  // Its project's instructions, which every agent works by: its launch line runs `instructions`, and its host tells it to
  // run it again for each new revision (cli superTabs/instructionsNotice.ts). Missing here until 2026-11-02, so a teammate's
  // agent worked by its role file alone.
  { method: 'GET', url: '/api/super-tabs/:tabId/projects/:projectId/instructions', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/projects/:projectId/instructions/revisions', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/projects/:projectId/instructions/revisions/:revision', scope: 'agent' },
  // Its project's rules record, which a Team-account PM reads for the revision it saves on (superTabs/policy.ts).
  { method: 'GET', url: '/api/super-tabs/:tabId/projects/:projectId/rules', scope: 'agent' },
  // What the route ranks by: the project's measured costs and its CI load (superTabs/costs/read.ts, github/ciLoad.ts). Missing
  // here until 2026-11-03, so a Team PM routed without them and the CI hold never applied.
  { method: 'GET', url: '/api/super-tabs/:tabId/costs', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/projects/:projectId/ci-load', scope: 'agent' },
  // The decisions its agent asked of people, and their answers (superTabs/decisions.ts).
  { method: 'GET', url: '/api/super-tabs/:tabId/decisions', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/conversations/:conversationId/messages', scope: 'agent' },
  // A fresh link to one file of a message its agent may read (superTabs/fileLinks.ts).
  { method: 'GET', url: '/api/super-tabs/:tabId/conversations/:conversationId/messages/:messageId/attachments/:attachmentId', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/conversations/:conversationId/attempts', scope: 'agent' },
  { method: 'GET', url: '/api/super-tabs/:tabId/terminal/:requestId', scope: 'agent' },
  { method: 'POST', url: '/api/super-tabs/:tabId/attachments', scope: 'agent' },
  // A file over the form's 10 MB: a signed link to the bucket, then its check (store.ts uploadLink, completeUpload).
  { method: 'POST', url: '/api/super-tabs/:tabId/attachments/uploads', scope: 'agent' },
  { method: 'POST', url: '/api/super-tabs/:tabId/attachments/uploads/:uploadId/complete', scope: 'agent' },
  // Its agent's one-hour GitHub token for the repository of its task (Task 4); the body's machine must be its own.
  { method: 'POST', url: '/api/super-tabs/:tabId/github-token', scope: 'agent', bodyMachine: true },
  // Commands as one of its agents, its agents' deliveries, stops and native terminals, its agents' role texts.
  { method: 'POST', url: '/api/super-tabs/:tabId/commands', scope: 'bound' },
  { method: 'GET', url: '/api/super-tabs/:tabId/agents/:agentId/deliveries', scope: 'bound' },
  { method: 'GET', url: '/api/super-tabs/:tabId/agents/:agentId/deliveries/:deliveryId', scope: 'bound' },
  { method: 'POST', url: '/api/super-tabs/:tabId/agents/:agentId/deliveries/:deliveryId', scope: 'bound' },
  { method: 'POST', url: '/api/super-tabs/:tabId/stopped', scope: 'bound' },
  { method: 'GET', url: '/api/super-tabs/:tabId/native/:contextId', scope: 'bound' },
  { method: 'POST', url: '/api/super-tabs/:tabId/native/:contextId', scope: 'bound' },
  { method: 'GET', url: '/api/super-tabs/:tabId/projects/:projectId/roles/:roleId', scope: 'bound' },
  // Swarm members' read-only views of its agents: shares of its own harnesses, for a Swarm only.
  { method: 'PUT', url: '/api/harness-shares/:id', scope: 'bound' },
  { method: 'DELETE', url: '/api/harness-shares/:id', scope: 'bound' },
]

/** The matched route's entry on TEAM_ROUTES: by the route, not the raw URL, so an encoded spelling is the same route. */
function teamRoute(request: FastifyRequest): TeamRoute | undefined {
  const url = request.routeOptions?.url
  return url ? TEAM_ROUTES.find(r => r.method === request.method && r.url === url) : undefined
}

/** The machine each admitted team request acts for, kept for the check that runs once its body is read. */
const admitted = new WeakMap<FastifyRequest, string>()

/** Whether a team session may make this request: its matched route is on TEAM_ROUTES and holds to its machine. */
export async function teamRequestAllowed(request: FastifyRequest, user: AuthUser): Promise<boolean> {
  const rule = teamRoute(request)
  if (!rule) return false
  if (rule.scope === 'open') return true
  const machine = await teamMachine(user)
  if (!machine) return false
  admitted.set(request, machine.machineId)
  if (rule.scope === 'machine') return (request.params as { machineId?: unknown } | undefined)?.machineId === machine.machineId
  if (rule.scope === 'agent') {
    const asAgentId = (request.query as { asAgentId?: unknown } | undefined)?.asAgentId
    return typeof asAgentId === 'string' && asAgentId.length > 0
  }
  return true
}

/** Once the body is read (a preHandler, middlewares/authMiddleware.ts): a route whose body names a machine must name
 *  the one this team session acts for, whatever the route itself then checks. */
export function teamBodyAllowed(request: FastifyRequest): boolean {
  if (!teamRoute(request)?.bodyMachine) return true
  const machineId = (request.body as { machineId?: unknown } | null | undefined)?.machineId
  return typeof machineId === 'string' && machineId === admitted.get(request)
}