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.

11.3 KB
Raw Blame
/**
 * Cloud agents: agents that run on their maker's servers and are reached through its API rather than started
 * as a terminal program here (docs/design/2026-10-11-cloud-agents.md). The cloud service owns them
 * (services/cloud.ts); the core lists them beside the terminal agents and routes a person's answers,
 * messages and Stop to that service (core/agents/cloud.ts). This file is what the two, and the frames the
 * apps read, share.
 *
 * A cloud agent's id is never an engine id (engines/types.ts `ENGINES`): it has no launch, transcript or pane,
 * and every per-engine table in the core would otherwise need a row for it that could only refuse.
 */
import type { AgentFrame } from './agentFrame.js'

export interface CloudAgentInfo {
  /** What the apps call it: a CLI agent's name plus "Cloud" for its maker's cloud coding agent (Naming System). */
  name: string
  /** Where it runs, said where a remote computer's name goes. */
  place: string
  /** A coding agent works on a GitHub repository; a personal agent runs errands and takes no repository. */
  kind: 'coding' | 'personal'
  /** A coding agent that can start with no repository: Devin's API takes `repos` as optional (lampOS asked, #1444). */
  repositoryOptional?: true
  /** How its connection is found among the person's Connections: by the host its MCP server or API is at. */
  connection: { mcp: string } | { api: string }
  /** What to connect, said when it is not connected. */
  connect: string
}

export const CLOUD_AGENTS = {
  fo: {
    name: 'Fo', place: "Fo's cloud", kind: 'personal', connection: { mcp: 'mcp.api.wajo.ai' },
    connect: 'Connect Fo in Connections (Add custom, https://mcp.api.wajo.ai/fo).',
  },
  'devin-cloud': {
    name: 'Devin Cloud', place: "Devin's cloud", kind: 'coding', repositoryOptional: true, connection: { api: 'https://api.devin.ai' },
    connect: 'Add your Devin API key: harness connections add-key Devin https://api.devin.ai',
  },
  'cursor-cloud': {
    name: 'Cursor Cloud', place: "Cursor's cloud", kind: 'coding', connection: { api: 'https://api.cursor.com' },
    connect: 'Add your Cursor API key: harness connections add-key Cursor https://api.cursor.com',
  },
} as const satisfies Record<string, CloudAgentInfo>

export type CloudAgentId = keyof typeof CLOUD_AGENTS
export const CLOUD_AGENT_IDS = Object.keys(CLOUD_AGENTS) as CloudAgentId[]

export function isCloudAgent(id: unknown): id is CloudAgentId {
  return typeof id === 'string' && Object.hasOwn(CLOUD_AGENTS, id)
}

/** `owner/name` from a GitHub address or the pair itself, or null. */
export function repositoryOf(value: unknown): string | null {
  if (typeof value !== 'string') return null
  const match = /^(?:https:\/\/github\.com\/|git@github\.com:)?([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec(value.trim())
  return match ? `${match[1]}/${match[2]}` : null
}

/**
 * Why a cloud agent cannot start this task, in the words a person reads, or null when it can. The cloud service
 * answers with it (cloud/service.ts) and `harness new` refuses with it before sending (lib/newCommand.ts): a typo
 * there reached the service and came back a counted launch failure (Oct 26 report). [repositories] are the ways a
 * request names one, the first that reads winning.
 */
export function cloudRequestRefusal(agent: CloudAgentId, task: string, repositories: readonly unknown[]): string | null {
  const info: CloudAgentInfo = CLOUD_AGENTS[agent]
  if (!task.trim()) return `Tell ${info.name} what to do.`
  const repository = repositories.map(repositoryOf).find(Boolean)
  // A repository given but not read (a GitLab address, a typo) is refused: started without it, the agent would work blind.
  if (!repository && repositories.some(Boolean)) return 'That is not a GitHub repository: give owner/name or https://github.com/owner/name.'
  if (info.kind === 'coding' && !info.repositoryOptional && !repository) return `Choose a GitHub repository for ${info.name}.`
  return null
}

/** Where a cloud harness is: working, waiting on the person, done with its turn, failed, or stopped. */
export type CloudState = 'starting' | 'working' | 'needs_input' | 'idle' | 'failed' | 'stopped'
export const CLOUD_STATES: readonly CloudState[] = ['starting', 'working', 'needs_input', 'idle', 'failed', 'stopped']

/**
 * The maker's own status, beside Harness's. A null is a reading where the maker gave none, so a later look
 * can drop a detail that went away. It does not say whether the words in the transcript were a question:
 * Devin's `finished` and a wait can look the same, and the text is not a status.
 */
export interface CloudProviderStatus {
  status: string | null
  detail: string | null
}

/** One cloud harness, as the cloud service tells the core about it (`core.cloud.publish`). */
export interface CloudHarness {
  /** Harness's own id for it, `cloud_…`: never the vendor's session id, which the service keeps. */
  agentId: string
  agent: CloudAgentId
  name: string
  state: CloudState
  /** What it is doing, in a line ("Calling Hair Lab"), or null. */
  activity: string | null
  /** The maker's own status. Absent on a harness saved before it was kept, and for a maker that does not report one. */
  providerStatus?: CloudProviderStatus
  /** The GitHub repository a coding agent works on (`owner/name`), or null. */
  repository: string | null
  branch: string | null
  /** Where to see it at its maker (the session page) and what it made (a pull request). */
  links: { label: string; url: string }[]
  /** How many messages its conversation holds: a client that shows it reads the conversation again when this moves. */
  messages: number
  /** What it said last, for the dial's card: a terminal agent's turn ends with its answer the same way. Kept in
   *  the core alone, never in a frame: the apps read the whole conversation. */
  said?: string | null
  createdAt: string
  updatedAt: string
}

/** As much of its last words as the dial's longest card draws, and some over (lib/deviceRecap.ts). */
export const SAID_MAX = 4_000
/** A maker's own status string on the way into the core: long enough for an unknown detail, and no more. */
const PROVIDER_STATUS_MAX = 200

const text = (value: unknown, max = 500): string | null => (typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : null)
const stamp = (value: unknown): string | null => (typeof value === 'string' && Number.isFinite(Date.parse(value)) ? value : null)

/** A maker's status beside the harness, or nothing when it is absent or not an object. A bad field is dropped, not the harness. */
function providerStatusIn(raw: unknown): CloudProviderStatus | undefined {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
  const value = raw as Record<string, unknown>
  return { status: text(value.status, PROVIDER_STATUS_MAX), detail: text(value.detail, PROVIDER_STATUS_MAX) }
}

/** A harness as a service reported it, or null for anything else: the core keeps nothing it cannot read. */
export function cloudHarnessIn(raw: unknown): CloudHarness | null {
  if (!raw || typeof raw !== 'object') return null
  const value = raw as Record<string, unknown>
  const agentId = text(value.agentId, 80)
  const createdAt = stamp(value.createdAt), updatedAt = stamp(value.updatedAt)
  if (!agentId?.startsWith('cloud_') || !isCloudAgent(value.agent) || !CLOUD_STATES.includes(value.state as CloudState) || !createdAt || !updatedAt) return null
  const links = Array.isArray(value.links) ? value.links.flatMap((link) => {
    const entry = link as Record<string, unknown> | null
    const label = text(entry?.label, 80), url = text(entry?.url, 2048)
    return label && url && /^https:\/\//.test(url) ? [{ label, url }] : []
  }).slice(0, 8) : []
  const providerStatus = providerStatusIn(value.providerStatus)
  return {
    agentId,
    agent: value.agent,
    name: text(value.name, 120) ?? CLOUD_AGENTS[value.agent].name,
    state: value.state as CloudState,
    activity: text(value.activity, 200),
    ...(providerStatus ? { providerStatus } : {}),
    repository: text(value.repository, 200),
    branch: text(value.branch, 200),
    links,
    messages: typeof value.messages === 'number' && Number.isInteger(value.messages) && value.messages >= 0 ? value.messages : 0,
    said: text(value.said, SAID_MAX),
    createdAt,
    updatedAt,
  }
}

/** What the apps read about a cloud agent beyond an agent's usual frame: `location: 'cloud'` and this. */
export interface CloudFrameBlock {
  place: string
  state: CloudState
  activity: string | null
  links: { label: string; url: string }[]
  messages: number
  /** Absent when the harness has no maker status (an older one, or Fo and Cursor). */
  providerStatus?: CloudProviderStatus
}

export type CloudAgentFrame = Omit<AgentFrame, 'engine'> & { engine: CloudAgentId; location: 'cloud'; cloud: CloudFrameBlock }

/**
 * A cloud harness as every client reads an agent: the same frame a terminal agent has, with no pane and no
 * terminal (as a stopped agent's), `location: 'cloud'` for the chat pane, and its repository as its project
 * so the footer and the pull request read it as they read any other.
 */
export function cloudAgentFrame(harness: CloudHarness): CloudAgentFrame {
  const working = harness.state === 'working' || harness.state === 'starting'
  const project = harness.repository
    ? { kind: 'git' as const, name: harness.repository.split('/').pop() ?? harness.repository, cwd: '', root: null,
      remote: `https://github.com/${harness.repository}`, branch: harness.branch }
    : null
  return {
    id: harness.agentId,
    sessionId: harness.agentId,
    userId: '',
    name: harness.name,
    // Whether a person chose it is not known here: a client sends nothing for it (agentFrame.ts).
    nameChosen: false,
    title: null,
    status: harness.state === 'stopped' ? 'stopped' : 'active',
    activity: { state: working ? 'working' : 'idle', epoch: harness.agentId, revision: Date.parse(harness.updatedAt), validForMs: working ? 120_000 : 0 },
    closePlan: null,
    closeSupported: false,
    launch: harness.state === 'failed' ? { state: 'failed', error: 'CLOUD_FAILED', detail: harness.activity ?? `${CLOUD_AGENTS[harness.agent].name} stopped with an error.` }
      : harness.state === 'starting' ? { state: 'starting' } : { state: 'ready' },
    createdAt: harness.createdAt,
    updatedAt: harness.updatedAt,
    lastOpenedAt: null,
    tokenUsage: null,
    outputStats: null,
    tmuxPane: null,
    terminal: { available: false, primary: '', runtimes: [] },
    engine: harness.agent,
    selectedModel: null,
    grid: null,
    codexHome: null,
    project,
    gitContext: { state: project ? 'workspace' : 'unavailable', current: project, observedAt: null, locations: [], pullRequests: [], truncated: false },
    dsh: null,
    dshName: null,
    viewerUrl: null,
    viewerName: null,
    verdict: null,
    forkedFrom: null,
    forkable: false,
    // A person starts a cloud harness from New Harness: no agent here or elsewhere started it.
    parentAgentId: null,
    startedBy: null,
    resumeMode: 'conversation',
    permissionMode: null,
    bypassPermission: null,
    namedAgent: null,
    location: 'cloud',
    cloud: {
      place: CLOUD_AGENTS[harness.agent].place, state: harness.state, activity: harness.activity, links: harness.links, messages: harness.messages,
      ...(harness.providerStatus ? { providerStatus: { status: harness.providerStatus.status, detail: harness.providerStatus.detail } } : {}),
    },
  }
}