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.

3.8 KB
Raw Blame
/**
 * Prove a provider URL + credential before a machine is created.
 *
 * Without this step a wrong credential is indistinguishable from an outage — the machine is created,
 * looks fine, and only fails when somebody eventually types a message. That is the worst failure mode
 * in this design, and the whole reason the create flow blocks on a live check.
 *
 * ONE authenticated call does the whole job. `agent.list` proves the URL, the credential and that the
 * endpoint speaks this protocol at once, and it returns exactly what the create screen wants to show
 * next — so there is nothing to fetch beforehand.
 *
 * Four outcomes, four different sentences. They are different because each has a different fix:
 * change the URL, wait, pick a different provider, or paste the right credential.
 */
import { ProviderError, listAgents, type ProviderAgent } from './provider/client.js'
import { checkProviderUrl, ProviderUrlError } from './providerUrl.js'

export type ProbeFailure =
  | 'PROVIDER_URL_REFUSED'
  | 'PROVIDER_UNREACHABLE'
  | 'PROVIDER_NOT_STREAMING'
  | 'PROVIDER_CREDENTIAL_REJECTED'

export class ProviderProbeError extends Error {
  constructor(message: string, readonly code: ProbeFailure) {
    super(message)
    this.name = 'ProviderProbeError'
  }
}

export interface ProbeResult {
  /** Normalised URL to store. */
  url: string
  /** Agent ids, so the UI can show what it just connected to. */
  agents: Array<{ id: string; name: string; description?: string }>
}

export async function probeProvider(rawUrl: string, credential: string): Promise<ProbeResult> {
  let url: string
  try {
    url = (await checkProviderUrl(rawUrl)).url
  } catch (err) {
    // The guard's own message names the actual problem (private address, bad scheme, no DNS), which
    // is more useful than a generic "invalid URL".
    throw new ProviderProbeError(err instanceof ProviderUrlError ? err.message : 'That is not a usable URL', 'PROVIDER_URL_REFUSED')
  }

  let agents: ProviderAgent[]
  try {
    agents = (await listAgents({ url, credential, timeoutMs: 10_000 })).agents ?? []
  } catch (err) {
    if (err instanceof ProviderError && err.kind === 'unauthenticated') {
      throw new ProviderProbeError('The provider rejected that credential', 'PROVIDER_CREDENTIAL_REJECTED')
    }
    // `protocol` errors mean it answered, but not the way this protocol says to — most often because
    // the URL points at something else entirely. That is a different fix from "wait for it to come
    // back", so it keeps its own code.
    if (err instanceof ProviderError && err.kind === 'protocol') {
      throw new ProviderProbeError('That endpoint did not answer as a provider', 'PROVIDER_NOT_STREAMING')
    }
    // A refusal means it IS a provider and it said no — to listing agents, of all things. Its own
    // sentence is the only thing here that tells the owner what to do about it.
    if (err instanceof ProviderError && err.kind === 'refused') {
      throw new ProviderProbeError(`The provider refused to list its agents: ${err.message}`, 'PROVIDER_NOT_STREAMING')
    }
    throw new ProviderProbeError(
      `Could not reach that provider${err instanceof Error && err.message ? `: ${err.message}` : ''}`,
      'PROVIDER_UNREACHABLE',
    )
  }

  const usable = agents.filter((a): a is ProviderAgent & { id: string } => typeof a?.id === 'string' && !!a.id)
  // An empty list is a real failure, not an empty state: the machine would be created and then have
  // nothing to talk to, which reads to the owner as a broken product rather than a bad endpoint.
  if (!usable.length) {
    throw new ProviderProbeError('That provider returned no agents to talk to', 'PROVIDER_NOT_STREAMING')
  }

  return {
    url,
    agents: usable.map((a) => ({ id: a.id, name: a.name ?? a.id, description: a.description })),
  }
}