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.

22.2 KB
Raw Blame
/**
 * Cloud agents (docs/design/2026-10-11-cloud-agents.md): harnesses that run on their maker's servers. This
 * service owns them. It starts one through its adapter, keeps its conversation, looks at the maker while it
 * works, and tells the core every change (`core.cloud`), which lists them with the terminal agents and puts
 * their questions in front of the person.
 *
 * - Its harnesses and their makers' ids are in `<data>/cloud/harnesses.json`, and each conversation in
 *   `<data>/cloud/<agentId>.jsonl`: the core's experiment start finds the first and wakes this service.
 * - It looks every 10 s while one works, 30 s while it waits on the person, and not at all once it is idle,
 *   stopped or failed, until the person writes to it. Fo's reply is a long wait of its own (`waited`).
 * - Nothing here holds a credential: each call goes through the Connections bridge (cloud/bridge.ts).
 */
import { randomBytes } from 'node:crypto'
import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import type { CloudCore, CloudPort, CloudResult, ServiceRequests } from '../core/api.js'
import { CLOUD_AGENT_IDS, CLOUD_AGENTS, SAID_MAX, cloudAgentFrame, cloudRequestRefusal, isCloudAgent, repositoryOf, type CloudAgentId, type CloudHarness } from '../lib/cloudAgents.js'
import { connectionFor, connectionsBridge, type Bridge } from './bridge.js'
import { cursorAdapter } from './cursor.js'
import { devinAdapter } from './devin.js'
import { foAdapter } from './fo.js'
import { McpClient } from './mcp.js'
import { CloudError, type CloudAdapter, type CloudUpdate, type Remote } from './types.js'

interface Entry {
  harness: CloudHarness
  remote: Remote
  question: { requestId: string; text: string; choices: string[] } | null
  /** When it last changed: one unchanged for a day is no longer looked at. */
  changedAt: number
  failures: number
  /** Whether the agent has said anything since the person last wrote: until it has, a maker still reporting
   *  "waiting for you" is reporting the wait the person just answered (core rule 6, evidence newer than state). */
  heard: boolean
  /** The New Harness that made it (`creationId`): a retry of the same one gets this harness, never a second. */
  creationId?: string
}

export interface TranscriptMessage { id: string; from: 'agent' | 'person'; text: string; at: string }

export interface CloudServiceOptions {
  dataDir: string
  core: CloudCore
  bridge?: Bridge
  /** Swapped in tests for fakes of the makers. */
  adapters?: Partial<Record<CloudAgentId, CloudAdapter>>
  now?: () => number
  setTimer?: (fn: () => void, ms: number) => unknown
  clearTimer?: (timer: unknown) => void
  log?: (line: string) => void
}

const WORKING_MS = 10_000
const WAITING_MS = 30_000
const BACKOFF_MAX_MS = 5 * 60_000
const QUIET_MS = 24 * 60 * 60_000
/** The least time between looks, even for a maker that waits for news itself: one that answers at once must
 *  never be asked again at once, for a day. */
const LOOK_MIN_MS = 5_000
const TRANSCRIPT_MAX = 500

/** A harness's name from its task: its first line, short. */
export function nameFor(task: string, agent: CloudAgentId): string {
  const line = task.split('\n').map((part) => part.trim()).find(Boolean) ?? ''
  return line ? (line.length > 40 ? `${line.slice(0, 39).trimEnd()}…` : line) : CLOUD_AGENTS[agent].name
}

export function startCloudService(options: CloudServiceOptions) {
  const now = options.now ?? Date.now
  const setTimer = options.setTimer ?? ((fn: () => void, ms: number) => setTimeout(fn, ms).unref())
  const clearTimer = options.clearTimer ?? ((timer: unknown) => clearTimeout(timer as ReturnType<typeof setTimeout>))
  const log = options.log ?? ((line: string) => console.log(line))
  const bridge = options.bridge ?? connectionsBridge()
  const dir = join(options.dataDir, 'cloud')
  const stateFile = join(dir, 'harnesses.json')
  const entries = new Map<string, Entry>()
  const timers = new Map<string, unknown>()
  /** One thing at a time per harness: a look and a message never cross. */
  const queues = new Map<string, Promise<unknown>>()
  /** The look in flight, by harness: the person's words cut short a long wait (Fo's reply waits 40 s) rather
   *  than queue behind it. */
  const looking = new Map<string, AbortController>()
  const interrupt = (agentId: string): void => { looking.get(agentId)?.abort() }
  let stopped = false

  // Each maker's connection, found by where it points, for a minute at a time; a refusal finds it again.
  const codes = new Map<CloudAgentId, { code: string; at: number }>()
  const codeFor = (agent: CloudAgentId) => async (): Promise<string> => {
    const known = codes.get(agent)
    if (known && now() - known.at < 60_000) return known.code
    const { code } = await connectionFor(bridge, agent)
    codes.set(agent, { code, at: now() })
    return code
  }
  const mcpClients = new Map<string, McpClient>()
  const adapters: Record<CloudAgentId, CloudAdapter> = {
    fo: options.adapters?.fo ?? foAdapter(async () => {
      const url = bridge.mcpUrl(await codeFor('fo')())
      let client = mcpClients.get(url)
      if (!client) { client = new McpClient(url, CLOUD_AGENTS.fo.name, bridge.fetch); mcpClients.set(url, client) }
      return client
    }),
    'devin-cloud': options.adapters?.['devin-cloud'] ?? devinAdapter(bridge, codeFor('devin-cloud')),
    'cursor-cloud': options.adapters?.['cursor-cloud'] ?? cursorAdapter(bridge, codeFor('cursor-cloud')),
  }

  const transcriptFile = (agentId: string): string => join(dir, `${agentId}.jsonl`)
  const save = (): void => {
    mkdirSync(dir, { recursive: true, mode: 0o700 })
    const temp = `${stateFile}.${process.pid}.tmp`
    writeFileSync(temp, JSON.stringify({ harnesses: [...entries.values()].map(({ harness, remote, question, changedAt, creationId }) => ({ harness, remote, question, changedAt, creationId })) }), { mode: 0o600 })
    renameSync(temp, stateFile)
  }
  const transcript = (agentId: string): TranscriptMessage[] => {
    try {
      return readFileSync(transcriptFile(agentId), 'utf8').split('\n').flatMap((line) => {
        try { return line ? [JSON.parse(line) as TranscriptMessage] : [] } catch { return [] }
      })
    } catch { return [] }
  }
  const record = (entry: Entry, message: TranscriptMessage): void => {
    mkdirSync(dir, { recursive: true, mode: 0o700 })
    appendFileSync(transcriptFile(entry.harness.agentId), `${JSON.stringify(message)}\n`, { mode: 0o600 })
    entry.harness.messages += 1
    if (message.from === 'agent') entry.harness.said = message.text.slice(0, SAID_MAX)
  }

  const publish = (): void => {
    if (stopped) return
    options.core.publish([...entries.values()].map((entry) => ({ ...entry.harness, links: [...entry.harness.links] })))
  }
  const touched = (entry: Entry): void => {
    entry.harness.updatedAt = new Date(now()).toISOString()
    entry.changedAt = now()
    save()
    publish()
  }
  const serial = <T>(agentId: string, work: () => Promise<T>): Promise<T> => {
    const run = (queues.get(agentId) ?? Promise.resolve()).catch(() => {}).then(work)
    queues.set(agentId, run)
    return run
  }

  const ask = (entry: Entry, question: { text: string; choices: string[] } | null): void => {
    const asked = entry.question
    if (asked && question && asked.text === question.text && asked.choices.join('\n') === question.choices.join('\n')) return
    if (asked) { options.core.unask(entry.harness.agentId, asked.requestId); entry.question = null }
    if (!question) return
    entry.question = { requestId: `cloud_q_${randomBytes(6).toString('hex')}`, ...question }
    options.core.ask(entry.harness.agentId, entry.question.requestId, question)
  }

  /** What one look found, applied: new messages recorded, where it is now, and its question. */
  const apply = (entry: Entry, update: CloudUpdate): boolean => {
    const before = JSON.stringify([entry.harness, entry.remote, entry.question?.text])
    const seen = new Set(transcript(entry.harness.agentId).slice(-TRANSCRIPT_MAX).map((message) => message.id))
    for (const message of update.messages) {
      if (seen.has(message.id)) continue
      record(entry, { ...message, from: 'agent' })
      entry.heard = true
    }
    // "Waiting for you" with nothing said since the person wrote is the wait they just answered: not a new one.
    if (update.state === 'needs_input' && !entry.heard) update = { ...update, state: undefined, question: undefined }
    if (update.state) entry.harness.state = update.state
    if (update.activity !== undefined) entry.harness.activity = update.activity
    // Refreshed even when this look brought no messages, and when its "waiting" was the wait just answered.
    // A null detail replaces the old one: the maker no longer reports it.
    if (update.providerStatus) entry.harness.providerStatus = { status: update.providerStatus.status, detail: update.providerStatus.detail }
    if (update.branch !== undefined) entry.harness.branch = update.branch
    if (update.links) entry.harness.links = update.links
    if (update.remote) entry.remote = { ...entry.remote, ...update.remote }
    if (entry.harness.state !== 'needs_input') ask(entry, null)
    else if (update.question) ask(entry, update.question)
    // Waiting, with nothing new said and nothing asked yet (a restart): it asks what it last said.
    else if (!entry.question) {
      const said = transcript(entry.harness.agentId).filter((message) => message.from === 'agent').at(-1)?.text
      ask(entry, { text: (said ?? `${CLOUD_AGENTS[entry.harness.agent].name} is waiting for you.`).slice(0, 500), choices: [] })
    }
    return JSON.stringify([entry.harness, entry.remote, entry.question?.text]) !== before
  }

  const schedule = (agentId: string, ms: number): void => {
    clearTimer(timers.get(agentId))
    timers.delete(agentId)
    if (stopped) return
    timers.set(agentId, setTimer(() => { timers.delete(agentId); void look(agentId) }, ms))
  }
  const watching = (entry: Entry): boolean => ['starting', 'working', 'needs_input'].includes(entry.harness.state) && now() - entry.changedAt < QUIET_MS

  const look = (agentId: string): Promise<void> => serial(agentId, async () => {
    const entry = entries.get(agentId)
    if (!entry || stopped || !watching(entry)) return
    let update: CloudUpdate
    const controller = new AbortController()
    looking.set(agentId, controller)
    const started = now()
    try {
      update = await adapters[entry.harness.agent].poll(entry.remote, controller.signal)
      entry.failures = 0
    } catch (error) {
      // Cut short by the person's words: they are next in line, and look again after.
      if (controller.signal.aborted) return
    
      entry.failures += 1
      const said = error instanceof CloudError ? error.message : `${CLOUD_AGENTS[entry.harness.agent].name} could not be reached.`
      log(`[cloud] ${agentId} look failed (${entry.failures}): ${error instanceof Error ? error.name : 'error'}`)
      if (entry.harness.activity !== said) { entry.harness.activity = said; touched(entry) }
      schedule(agentId, Math.min(BACKOFF_MAX_MS, WORKING_MS * 2 ** entry.failures))
      return
    }
    finally {
      if (looking.get(agentId) === controller) looking.delete(agentId)
    }
    if (apply(entry, update)) touched(entry)
    const waitedLong = update.waited && now() - started >= LOOK_MIN_MS
    if (watching(entry)) schedule(agentId, waitedLong ? 0 : update.waited ? LOOK_MIN_MS : entry.harness.state === 'needs_input' ? WAITING_MS : WORKING_MS)
  })

  const refused = (error: unknown, agent?: CloudAgentId): { ok: false; error: string; detail: string } => error instanceof CloudError
    ? { ok: false, error: error.code, detail: error.message }
    : { ok: false, error: 'CLOUD_FAILED', detail: `${agent ? CLOUD_AGENTS[agent].name : 'The cloud agent'} could not be reached. Try again.` }

  /** New Harnesses still starting at their maker, by `creationId`: a retry while one starts gets its answer. */
  const creating = new Map<string, ReturnType<CloudPort['create']>>()

  const create: CloudPort['create'] = (request) => {
    // The same New Harness asked again (a window that timed out waiting): the harness it made, not a second.
    const creationId = typeof request.creationId === 'string' && request.creationId ? request.creationId.slice(0, 120) : undefined
    if (!creationId) return createNew(request, undefined)
    const made = [...entries.values()].find((entry) => entry.creationId === creationId)
    if (made) return Promise.resolve({ ok: true, agent: cloudAgentFrame(made.harness) })
    const pending = creating.get(creationId) ?? createNew(request, creationId).finally(() => creating.delete(creationId))
    creating.set(creationId, pending)
    return pending
  }

  const createNew = async (request: Record<string, unknown>, creationId: string | undefined): ReturnType<CloudPort['create']> => {
    const agent = request.engine
    if (!isCloudAgent(agent)) return { ok: false, error: 'INVALID_ENGINE', detail: 'That is not a cloud agent.' }
    const task = typeof request.prompt === 'string' ? request.prompt.trim() : ''
    const refusal = cloudRequestRefusal(agent, task, [request.repositoryUrl, request.repository])
    if (refusal) return { ok: false, error: 'INVALID_REQUEST', detail: refusal }
    const repository = repositoryOf(request.repositoryUrl) ?? repositoryOf(request.repository)
    const acuLimit = typeof request.acuLimit === 'number' && Number.isInteger(request.acuLimit) && request.acuLimit > 0 && request.acuLimit <= 1000 ? request.acuLimit : undefined
    const model = typeof request.model === 'string' && request.model ? request.model.slice(0, 120) : undefined
    let started: Awaited<ReturnType<CloudAdapter['start']>>
    try {
      started = await adapters[agent].start({ task, repository, options: { acuLimit, model } })
    } catch (error) {
      codes.delete(agent)
      return refused(error, agent)
    }
    const at = new Date(now()).toISOString()
    const entry: Entry = {
      harness: {
        agentId: `cloud_${randomBytes(8).toString('hex')}`, agent,
        name: typeof request.name === 'string' && request.name.trim() ? request.name.trim().slice(0, 120) : nameFor(task, agent),
        state: 'starting', activity: null, repository, branch: null, links: started.links, messages: 0, createdAt: at, updatedAt: at,
      },
      remote: started.remote,
      question: null,
      changedAt: now(),
      failures: 0,
      heard: false,
      ...(creationId ? { creationId } : {}),
    }
    entries.set(entry.harness.agentId, entry)
    record(entry, { id: `person-${now()}`, from: 'person', text: task, at })
    if (started.update) apply(entry, started.update)
    if (entry.harness.state === 'starting' && !started.update?.state) entry.harness.state = 'working'
    touched(entry)
    log(`[cloud] ${entry.harness.agentId} started on ${agent}`)
    schedule(entry.harness.agentId, started.update?.waited || adapters[agent].answered?.(entry.remote) ? 0 : 2_000)
    return { ok: true, agent: cloudAgentFrame(entry.harness) }
  }

  const deliver = (agentId: string, text: string): Promise<CloudResult> => { interrupt(agentId); return serial(agentId, async () => {
    const entry = entries.get(agentId)
    if (!entry) return { ok: false, error: 'UNKNOWN_AGENT', detail: 'That cloud harness is gone.' }
    const words = text.trim()
    if (!words) return { ok: false, error: 'INVALID_REQUEST', detail: 'Write something to send.' }
    // Working from the moment the words go, as a terminal agent's turn starts with its prompt: Fo answers
    // `ask_fo` with its whole reply, 15 s later, and the dial sat on the last recap all that time (2026-10-11).
    // Told, not saved: refused, it is back where it was.
    const was = { state: entry.harness.state, activity: entry.harness.activity, providerStatus: entry.harness.providerStatus }
    entry.harness.state = 'working'
    entry.harness.activity = null
    // The status from before these words is not this turn's. It stands again when the next look says so;
    // a refused send puts the old one back, because the maker never took the words.
    delete entry.harness.providerStatus
    publish()
    const adapter = adapters[entry.harness.agent]
    try {
      const moved = await adapter.send(entry.remote, words)
      if (moved) entry.remote = { ...entry.remote, ...moved }
    } catch (error) {
      Object.assign(entry.harness, was)
      if (!was.providerStatus) delete entry.harness.providerStatus
      publish()
      return refused(error, entry.harness.agent)
    }
    record(entry, { id: `person-${now()}`, from: 'person', text: words, at: new Date(now()).toISOString() })
    entry.heard = false
    ask(entry, null)
    touched(entry)
    // Its reply already here: read now, not after the wait a maker that is only starting needs.
    schedule(agentId, adapter.answered?.(entry.remote) ? 0 : 2_000)
    return { ok: true }
  }) }

  const answer = async (agentId: string, requestId: string, answers: Record<string, string>): Promise<CloudResult> => {
    const entry = entries.get(agentId)
    const question = entry?.question
    if (!entry || !question || question.requestId !== requestId) return { ok: false, error: 'STALE_QUESTION', detail: 'That question was already answered.' }
    const words = Object.values(answers).filter((value) => typeof value === 'string' && value.trim()).join('\n')
    // Taken at once, before anything waits: a second answer (the dial and the window both) finds it answered.
    entry.question = null
    options.core.unask(agentId, question.requestId)
    const result = await deliver(agentId, words)
    // Not taken: the question stands, asked again.
    if (!result.ok && !entry.question && entry.harness.state === 'needs_input') ask(entry, { text: question.text, choices: question.choices })
    return result
  }

  /** Only the name Harness shows: nothing is asked of the maker, and its activity time stands. */
  const rename = async (agentId: string, name: string): Promise<CloudResult> => {
    const entry = entries.get(agentId)
    if (!entry) return { ok: false, error: 'UNKNOWN_AGENT', detail: 'That cloud harness is gone.' }
    const trimmed = name.trim().slice(0, 120)
    if (!trimmed) return { ok: false, error: 'MISSING_NAME', detail: 'A harness needs a name.' }
    entry.harness.name = trimmed
    save()
    publish()
    return { ok: true }
  }

  const stopHarness = (agentId: string): Promise<CloudResult> => { interrupt(agentId); return serial(agentId, async () => {
    const entry = entries.get(agentId)
    if (!entry) return { ok: false, error: 'UNKNOWN_AGENT', detail: 'That cloud harness is gone.' }
    const adapter = adapters[entry.harness.agent]
    try { await adapter.stop?.(entry.remote) } catch (error) { return refused(error, entry.harness.agent) }
    clearTimer(timers.get(agentId))
    timers.delete(agentId)
    entry.harness.state = 'stopped'
    entry.harness.activity = adapter.stop ? null : `${CLOUD_AGENTS[entry.harness.agent].name} keeps working on its own.`
    // A local stop is not the maker's last report. Showing that report would call a finished session current.
    delete entry.harness.providerStatus
    ask(entry, null)
    touched(entry)
    return adapter.stop ? { ok: true } : { ok: true, detail: `${CLOUD_AGENTS[entry.harness.agent].name} keeps working on its own.` }
  }) }

  const requests: ServiceRequests = {
    cloud_transcript: (payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
      if (!entries.has(agentId)) return { error: 'UNKNOWN_AGENT' }
      const all = transcript(agentId)
      const after = typeof payload.after === 'number' && payload.after > 0 ? Math.floor(payload.after) : 0
      return { messages: all.slice(Math.max(after, all.length - TRANSCRIPT_MAX)), total: all.length }
    },
    // The chat pane's prompt: answered, so the pane can say why words were not taken ("still working").
    cloud_send: (payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      return deliver(typeof payload.agentId === 'string' ? payload.agentId : '', typeof payload.text === 'string' ? payload.text : '')
        .then((result) => (result.ok ? { ok: true } : { error: result.error, detail: result.detail ?? '' }))
    },
    cloud_agents: async (_payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      const agents = await Promise.all(CLOUD_AGENT_IDS.map(async (id) => {
        const info = CLOUD_AGENTS[id]
        const connected = await connectionFor(bridge, id).then(() => true, () => false)
        return { id, name: info.name, place: info.place, kind: info.kind, connected, ...(connected ? {} : { connect: info.connect }) }
      }))
      return { agents }
    },
  }

  // The harnesses from before this start: told to the core again, and looked at where one was working.
  try {
    const saved = JSON.parse(readFileSync(stateFile, 'utf8')) as { harnesses?: Array<Omit<Entry, 'failures'>> }
    for (const raw of saved.harnesses ?? []) {
      if (!raw?.harness?.agentId || !isCloudAgent(raw.harness.agent) || !raw.remote?.id) continue
      // A harness saved before it kept its last words finds them in its conversation.
      if (typeof raw.harness.said !== 'string') raw.harness.said = transcript(raw.harness.agentId).filter((message) => message.from === 'agent').at(-1)?.text.slice(0, SAID_MAX) ?? null
      entries.set(raw.harness.agentId, { harness: raw.harness, remote: raw.remote, question: null, changedAt: raw.changedAt ?? now(), failures: 0, heard: true,
        ...(typeof raw.creationId === 'string' ? { creationId: raw.creationId } : {}) })
    }
  } catch { /* None yet. */ }
  for (const entry of entries.values()) if (watching(entry)) schedule(entry.harness.agentId, 1_000)

  return {
    requests,
    port: { create, deliver, answer, rename, stopHarness } satisfies CloudPort,
    /** The core connected again (its restart): it is told every harness, and asked every open question, again. */
    republish(): void {
      publish()
      for (const entry of entries.values()) if (entry.question) options.core.ask(entry.harness.agentId, entry.question.requestId, { text: entry.question.text, choices: entry.question.choices })
    },
    transcript,
    stop(): void {
      stopped = true
      for (const timer of timers.values()) clearTimer(timer)
      timers.clear()
    },
  }
}

export type CloudService = ReturnType<typeof startCloudService>