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
/**
 * Agents a service owns: the cloud agents (docs/design/2026-10-11-cloud-agents.md, "The one core change").
 * They have no pane, so they are never registry rows. The cloud service publishes them through `core.cloud`
 * (`doors`); the core keeps the last list, sends each change to the apps and the dial as any agent's frame
 * (`location: 'cloud'`), and puts their questions wherever questions show. What a person does to one comes
 * back here first: a New Harness for a cloud agent, words for it, an answer to its question, a rename and Stop
 * are handed to the service's port, and everything else goes on to the terminal agents' own paths.
 *
 * The dial reads a turn from its cards (lib/commander.ts): working as it starts, its answer as it ends. A cloud
 * harness has no turns to read, so its cards are made here, from what changes between two lists.
 */
import type { CloudCore, CloudPort, CloudResult } from '../api.js'
import { CLOUD_DOWN } from '../api.js'
import { cloudAgentFrame, cloudHarnessIn, isCloudAgent, type CloudAgentFrame, type CloudHarness } from '../../lib/cloudAgents.js'
import type { AutonomousDeviceInput } from '../deviceInput.js'
import type { QuestionAnswerResult } from '../../lib/questionController.js'
import { deriveTurnSummary } from '../../lib/deviceRecap.js'
import { splitSummary } from '../../lib/recapReads.js'

type Frame = { type: string; agentId?: string; dbSessionId?: string; payload: Record<string, unknown> }

export interface CloudAgentsDeps {
  /** The cloud service's port, or null while it is off. */
  port: () => CloudPort | null
  /** Every client (`send`), the dial (`sendCommander`) and the windows on this computer (`sendLocal`). */
  clients: { send(frame: Frame): void; sendCommander(frame: Frame): void; sendLocal(frame: Frame): void }
  /** What is still being asked, by agent, for a window that connects later (core/questions.ts). */
  openQuestions: Map<string, Record<string, unknown>>
  deviceInput: Pick<AutonomousDeviceInput, 'setUserAction'>
  log?: (line: string) => void
}

const DOWN = async (): Promise<typeof CLOUD_DOWN> => CLOUD_DOWN
const busy = (harness: CloudHarness): boolean => harness.state === 'working' || harness.state === 'starting'
/** Its last words as the dial's recap and the text under it, or null when it has said nothing. */
const recapOf = (harness: CloudHarness): { recap: string; text: string } | null => {
  const summary = harness.said ? deriveTurnSummary(harness.said) : null
  if (!summary) return null
  const { recap, body } = splitSummary(summary)
  return { recap, text: body }
}

export function createCloudAgents({ port, clients, openQuestions, deviceInput, log = (line) => console.log(line) }: CloudAgentsDeps) {
  let harnesses = new Map<string, CloudHarness>()
  /** Each open question's agent, by request id: an answer to one of these goes to the service. */
  const asked = new Map<string, string>()
  /** The questions the dial was shown: only those with choices, since its question screen takes no words. */
  const onDial = new Set<string>()
  /** The last words each harness's card told, so a list told again is not told twice. */
  const told = new Map<string, string>()

  const card = (harness: CloudHarness, payload: Record<string, unknown>): void => {
    // The name rides a summary's outer frame, as a terminal agent's does: a notification's second line.
    clients.sendCommander({ type: 'commander_event', agentId: harness.agentId, dbSessionId: harness.agentId, ...(payload.kind === 'summary' ? { name: harness.name } : {}), payload })
  }
  /**
   * Its cards, from one list to the next: working as it starts; once it stops, what it said, or done. First seen
   * (new, or a list told again whole after a restart), what it said is not news: the dial restores its tile by
   * `recent`. Working is, since the tile is idle until told.
   */
  const cards = (before: CloudHarness | undefined, harness: CloudHarness): void => {
    if (!before) told.set(harness.agentId, harness.said ?? '')
    // Stopped, it leaves the dial's wheel (`sync`): there is no tile to tell.
    if (harness.state === 'stopped') return
    if (busy(harness)) {
      if (!before || !busy(before)) card(harness, { kind: 'processing', text: harness.activity ?? 'Working…' })
      return
    }
    if (!before) return
    const recap = recapOf(harness)
    if (recap && harness.said !== told.get(harness.agentId)) {
      told.set(harness.agentId, harness.said!)
      // Waiting on the person, its question rings instead (lib/agentNotifications.ts keeps the same rule).
      card(harness, { kind: 'summary', ...recap, ...(harness.state === 'failed' ? { failed: true } : {}), notification: harness.state === 'needs_input' ? null : { id: `${harness.agentId}:${harness.messages}`, kind: 'done' } })
    } else if (busy(before)) {
      card(harness, harness.state === 'failed' ? { kind: 'error', text: harness.activity ?? 'It stopped with an error.' } : { kind: 'done', text: 'done' })
    }
  }

  const sync = (harness: CloudHarness): void => {
    const frame: Frame = { type: 'agent_synced', payload: { agent: cloudAgentFrame(harness) } }
    clients.send(frame)
    // The dial lists the harnesses it can drive: a stopped one leaves its wheel.
    clients.sendCommander(harness.state === 'stopped' ? { type: 'agent_deleted', payload: { agentId: harness.agentId } } : frame)
  }
  const gone = (agentId: string): void => {
    const frame: Frame = { type: 'agent_deleted', payload: { agentId } }
    clients.send(frame)
    clients.sendCommander(frame)
  }

  const doors: CloudCore = {
    publish(list) {
      const next = new Map<string, CloudHarness>()
      for (const raw of Array.isArray(list) ? list : []) {
        const harness = cloudHarnessIn(raw)
        if (harness) next.set(harness.agentId, harness)
      }
      const before = harnesses
      harnesses = next
      for (const [agentId, harness] of next) {
        const prior = before.get(agentId)
        if (JSON.stringify(prior) === JSON.stringify(harness)) continue
        sync(harness)
        cards(prior, harness)
      }
      for (const agentId of before.keys()) if (!next.has(agentId)) { told.delete(agentId); gone(agentId) }
    },
    ask(agentId, requestId, question) {
      if (!harnesses.has(agentId) || typeof requestId !== 'string' || !requestId.startsWith('cloud_q_') || typeof question?.text !== 'string') return
      const choices = (Array.isArray(question.choices) ? question.choices : []).filter((choice): choice is string => typeof choice === 'string' && !!choice).slice(0, 6)
      asked.set(requestId, agentId)
      const frame: Frame = {
        type: 'commander_question', agentId, dbSessionId: agentId,
        // As a terminal agent's question (core/questions.ts): one key, its choices, and free text, which the
        // windows take and the dial does not.
        payload: { requestId, questions: [{ key: 'answer', q: question.text.slice(0, 500), options: choices, multi: false, canText: true }], notification: { id: requestId, kind: 'needsYou' } },
      }
      deviceInput.setUserAction(agentId, true)
      if (choices.length) {
        onDial.add(requestId)
        clients.sendCommander(frame)
      }
      clients.sendLocal(frame)
      openQuestions.set(agentId, frame)
      log(`[cloud] ${agentId} asking the person · req=${requestId}`)
    },
    unask(agentId, requestId) {
      if (asked.get(requestId) !== agentId) return
      asked.delete(requestId)
      const frame: Frame = { type: 'commander_question_close', agentId, dbSessionId: agentId, payload: { requestId } }
      deviceInput.setUserAction(agentId, false)
      if (onDial.delete(requestId)) clients.sendCommander(frame)
      clients.sendLocal(frame)
      openQuestions.delete(agentId)
    },
  }

  const call = async <T>(work: (cloud: CloudPort) => Promise<T>, fallback: () => Promise<T>): Promise<T> => {
    const cloud = port()
    return cloud ? work(cloud) : fallback()
  }

  return {
    doors,
    /** Every cloud harness's frame, for `agents_list`. */
    frames: (): CloudAgentFrame[] => [...harnesses.values()].map(cloudAgentFrame),
    owns: (agentId: string): boolean => harnesses.has(agentId),
    /** Its last turn as the dial restores a tile (`agent_recent`), what it said; null when it is not one. */
    recent: (agentId: string): Array<{ kind: 'summary'; recap: string; text: string; fullText: string }> | null => {
      const harness = harnesses.get(agentId)
      if (!harness) return null
      const recap = recapOf(harness)
      return recap ? [{ kind: 'summary', ...recap, fullText: harness.said! }] : []
    },
    /** All it said last, for a dial that draws a long recap; undefined when it is not one or said nothing. */
    said: (agentId: string): string | undefined => harnesses.get(agentId)?.said ?? undefined,
    /** The working cards, for a dial attaching mid-turn. */
    liveCards: (): Frame[] => [...harnesses.values()].filter(busy).map((harness) => ({
      type: 'commander_event', agentId: harness.agentId, dbSessionId: harness.agentId, payload: { kind: 'processing', text: harness.activity ?? 'Working…' },
    })),
    /** What a working cloud harness is doing, for the dial's working card; null when it says nothing. */
    activity: (agentId: string): string | null => {
      const harness = harnesses.get(agentId)
      return harness && (harness.state === 'working' || harness.state === 'starting') ? harness.activity : null
    },
    /**
     * The running cloud harnesses as the dial lists agents (services/fleetRouter.ts reads an agent's id, its
     * start, its engine and its name): rows with no pane, no transcript and no process, so nothing that reads a
     * terminal agent's files finds one to read. A stopped one is off the wheel, as a stopped agent is.
     */
    dialRows: (): Array<Record<string, unknown>> => [...harnesses.values()].filter((harness) => harness.state !== 'stopped').map((harness) => ({
      agentId: harness.agentId, sessionId: harness.agentId, engine: harness.agent, displayName: harness.name, defaultName: harness.name, runtimeProfile: null,
      registeredAt: Date.parse(harness.createdAt), lastHookAt: Date.parse(harness.updatedAt), active: true,
      tmuxPane: '', cwd: '', projectDir: '', transcriptPath: null, runtimes: [], primaryRuntimeKey: '',
    })),
    /** `agent_create` for a cloud agent, answered as the socket answers one (`{ agent }`, or the refusal); null for any other engine. */
    create(payload: Record<string, unknown>): Promise<Record<string, unknown>> | null {
      if (!isCloudAgent(payload.engine)) return null
      return call((cloud) => cloud.create(payload), DOWN).then((result) => (result.ok ? { agent: result.agent } : { error: result.error, ...(result.detail ? { detail: result.detail } : {}) }))
    },
    /** Words for a cloud harness; null when it is not one. */
    deliver(agentId: string, text: string): Promise<CloudResult> | null {
      if (!harnesses.has(agentId)) return null
      return call((cloud) => cloud.deliver(agentId, text), DOWN)
    },
    /** `question_response` to a cloud harness's question, answered as a terminal agent's is; null when it is not one. */
    answer(payload: { requestId?: unknown; answers?: unknown }): Promise<QuestionAnswerResult> | null {
      const requestId = typeof payload.requestId === 'string' ? payload.requestId : ''
      const agentId = asked.get(requestId)
      if (!agentId) return null
      const answers = Object.fromEntries(Object.entries(payload.answers && typeof payload.answers === 'object' ? payload.answers : {})
        .filter((entry): entry is [string, string] => typeof entry[1] === 'string'))
      return call((cloud) => cloud.answer(agentId, requestId, answers), DOWN)
        .then((result): QuestionAnswerResult => (result.ok ? { ok: true }
          : { ok: false, error: result.error === 'STALE_QUESTION' ? 'STALE_QUESTION' : 'ANSWER_FAILED', detail: result.detail ?? '' }))
    },
    /**
     * `agent_update` for a cloud harness, answered as a terminal agent's is (core/agents/update.ts): its frame
     * after a rename, told to every window and the dial; its frame as it stands for an app opening it, since
     * nothing here keeps a "last used"; null when it is not one. It has no model to move.
     */
    update(payload: Record<string, unknown>): Promise<Record<string, unknown>> | null {
      const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
      const harness = harnesses.get(agentId)
      if (!harness) return null
      if (!Object.prototype.hasOwnProperty.call(payload, 'name')) {
        return Promise.resolve(payload.opened === true ? { agent: cloudAgentFrame(harness) } : { error: 'MISSING_UPDATE' })
      }
      const name = typeof payload.name === 'string' ? payload.name.trim().slice(0, 120) : ''
      if (!name) return Promise.resolve({ error: 'MISSING_NAME' })
      return call((cloud) => cloud.rename(agentId, name), DOWN).then((result) => {
        if (!result.ok) return { error: result.error, ...(result.detail ? { detail: result.detail } : {}) }
        // As a terminal agent's rename is told; the service's next list says it again, which changes nothing.
        const renamed: Frame = { type: 'agent_renamed', payload: { agentId, name, engine: harness.agent } }
        clients.send(renamed)
        clients.sendCommander(renamed)
        return { agent: cloudAgentFrame({ ...harness, name }) }
      })
    },
    /**
     * Stop Harness for a cloud harness, answered as `agent_delete` is; null when it is not one. The socket waits
     * on this in the connection's line, so a maker slower than a few seconds is answered "stopping" and its
     * harness's frame says when it has: the window's other requests never wait behind a vendor.
     */
    stop(agentId: string, quickMs = 3_000): Promise<Record<string, unknown>> | null {
      if (!harnesses.has(agentId)) return null
      const stopped = call((cloud) => cloud.stopHarness(agentId), DOWN)
        .then((result) => (result.ok ? { deleted: true, ...(result.detail ? { detail: result.detail } : {}) } : { error: result.error, ...(result.detail ? { detail: result.detail } : {}) }))
      let timer: ReturnType<typeof setTimeout> | undefined
      const stopping = new Promise<Record<string, unknown>>((resolve) => {
        timer = setTimeout(() => resolve({ deleted: true, detail: 'Stopping. Its pane says when it has.' }), quickMs)
        timer.unref?.()
      })
      return Promise.race([stopped, stopping]).finally(() => clearTimeout(timer))
    },
  }
}

export type CloudAgents = ReturnType<typeof createCloudAgents>