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.

16.4 KB
Raw Blame
/**
 * Reading a grid the way a person glances at it — without knocking.
 *
 * A grid sleeps when nobody uses it, and on the platform a SIGNED-IN read of a sleeping grid wakes it
 * (grid-apis `wake_routes`: presence of a credential, never its validity). This daemon used to read
 * every grid an account is in about once a minute, with the account's credential, so none of them ever
 * slept — and the read that woke one usually came back empty, because a just-woken master has not heard
 * from its providers yet. Everything here reads with NO credential:
 *
 * - The master's overview and its provider discovery are public (grid-src serves both unauthenticated),
 *   so an AWAKE grid answers exactly as it would a signed-in read;
 * - a SLEEPING grid answers at once `503 {code: "grid_asleep"}` and is not started, and that answer may
 *   carry `last_known` — what the grid was serving when the platform put it to sleep.
 *
 * ⚠️ **Never add a credential to anything in this file.** Not an Authorization header, not x-api-key,
 * not a token in the query. The whole resource saving rests on it, and its failure is SILENT: every list
 * still looks perfect while every open harness keeps every grid awake again. A person's act that SHOULD
 * wake a grid (a message, Start, an explicit wake, a prewarm) goes out another way — `gridWake.ts` — on
 * purpose.
 *
 * The paths, the code, the flag and every field name read below come from `gridProtocol.ts`: the wire
 * contract, generated from its JSON Schemas in the public autonomous-grid repository (`protocol/`) and copied
 * here whole. Never edit that file by hand; a shape changes there first.
 */
import { VERSION } from '../version.js'
import { gridEnvelopes } from './gridEnvelope.js'
import { gridExec, gridJson } from './gridExec.js'
import { idKey } from './gridPicture.js'
import {
  DISCOVER_PATH, GRID_ASLEEP_CODE, NO_WAKE_FLAG, OVERVIEW_PATH, REFUSAL_STATUS,
  type DiscoveredCapabilities, type DiscoveredModel, type DiscoveredProvider, type GridAsleep,
  type GridOverview, type LastKnown as WireLastKnown, type LastKnownNode, type NodeModelCapability,
  type OverviewModel, type OverviewNode, type ProviderDiscovery,
} from './gridProtocol.js'
import type { Unchecked } from './gridUnchecked.js'

/** The owner status of a grid the platform's reaper slept (grid-apis `grid_sleep_state.ASLEEP`), as
 *  `grid info --json` passes it through. Only the grid's owner sees a status at all. */
export const OWNER_ASLEEP_STATUS = 'asleep'

/** A read that has not answered in this long is not going to; the list shown meanwhile is the last one. */
const READ_TIMEOUT_MS = 10_000

/** An overview is a few KB; anything past this is not one, and is not held in memory to find out. */
const MAX_BODY_BYTES = 2 * 1024 * 1024

/** Bounds on what a hostile or broken answer can put into the picture (and so onto disk). */
const MAX_NODES = 256
const MAX_MODELS_PER_NODE = 256
const MAX_IDS = 1024
const MAX_TEXT = 256

/** Why a request is being made — the User-Agent's trailing word, read by people counting the platform's
 *  "wake fired" journal lines (the zero-baseline alarm keys on `(read)`). Attribution only. */
export type ReadPurpose = 'read' | 'wake' | 'prewarm' | 'prewarm-key'

export function harnessUserAgent(purpose: ReadPurpose): string {
  return `autonomous-harness/${VERSION} (${purpose})`
}

/** One engine node as a read reports it. `models` are ids as the grid lists them — lower-cased by the
 *  overview, exact from the CLI fallback; the picture keys them without case either way. */
export interface ReadNode {
  name: string
  engine: string
  models: string[]
  /** The provider's account, when the grid publishes it (it withholds it on an `os-community` grid).
   *  Read only to decide whether a node is the account's own, and never persisted. */
  providerEmail: string | null
}

/** What the platform recorded a grid serving when it slept it (grid-apis `sleep_record.answer_field`). */
export interface LastKnown {
  /** How long ago the record was taken, computed by the SERVER so no clock here matters. */
  ageSeconds: number
  nodes: Array<{ name: string; engine: string; models: string[] }>
  /** Exact-case candidate ids — a spelling source for the case map, never a list of what is served. */
  ids: string[]
}

export type GridRead =
  /** It answered: these are the live nodes. `rawNodes` is the overview's own node objects, for the Model
   *  Manager, which reads telemetry off them; through the CLI fallback, the little `grid models` says.
   *  `windows` is each model's context window, keyed without case (empty through the fallback). */
  | { kind: 'awake'; nodes: ReadNode[]; curatedIds: string[]; rawNodes: Array<Record<string, unknown>>; windows: Record<string, number> }
  /** The platform says it is resting. `lastKnown` is its record, when it has a valid one. */
  | { kind: 'asleep'; lastKnown: LastKnown | null }
  /** Anything else: stopped by its owner, master down, deleted, a codeless 503, garbage, a timeout. */
  | { kind: 'unanswered' }
  /** No HTTP answer at all — the one case the CLI fallback is for. */
  | { kind: 'unreachable' }

type Json = Record<string, unknown>
const isObject = (value: unknown): value is Json => !!value && typeof value === 'object' && !Array.isArray(value)
const text = (value: unknown): string =>
  typeof value === 'string' ? value.replace(/[\u0000-\u001f\u007f]/g, ' ').trim().slice(0, MAX_TEXT) : ''
const strings = (value: unknown, limit: number): string[] =>
  Array.isArray(value) ? value.map(text).filter(Boolean).slice(0, limit) : []

/**
 * The address a read goes to, or null when it is not one this daemon will send anything to: `https`, or
 * plain `http` to this computer only (a developer's local grid), with no credentials in the URL itself.
 * Null is not a verdict on the grid — the caller falls back to the CLI, which knows its own transport.
 */
export function readBase(gridUrl: string | null): string | null {
  if (!gridUrl) return null
  let url: URL
  try { url = new URL(gridUrl) } catch { return null }
  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) return null
  if (url.username || url.password) return null
  url.search = ''
  url.hash = ''
  return url.href.replace(/\/+$/, '')
}

/** A GET with no credential, bounded in time, size and redirects. Throws only on a network failure. */
async function get(base: string, path: string, purpose: ReadPurpose): Promise<{ status: number; body: unknown }> {
  const response = await fetch(`${base}${path}`, {
    method: 'GET',
    headers: { 'user-agent': harnessUserAgent(purpose), accept: 'application/json' },
    // A redirect is answered as what it is — not followed to wherever it points.
    redirect: 'manual',
    signal: AbortSignal.timeout(READ_TIMEOUT_MS),
  })
  return { status: response.status, body: await boundedJson(response) }
}

/** The body as JSON, or undefined when it is not JSON or is larger than any real answer. */
async function boundedJson(response: Response): Promise<unknown> {
  const declared = Number(response.headers.get('content-length'))
  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
    await response.body?.cancel().catch(() => {})
    return undefined
  }
  const reader = response.body?.getReader()
  if (!reader) return undefined
  const chunks: Uint8Array[] = []
  let size = 0
  for (;;) {
    const { done, value } = await reader.read()
    if (done) break
    size += value.byteLength
    if (size > MAX_BODY_BYTES) {
      await reader.cancel().catch(() => {})
      return undefined
    }
    chunks.push(value)
  }
  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')) } catch { return undefined }
}

function readNodes(value: unknown): ReadNode[] {
  if (!Array.isArray(value)) return []
  return value.filter(isObject).slice(0, MAX_NODES).map((raw) => {
    const node: Unchecked<OverviewNode> = raw
    return {
      name: text(node.name),
      engine: text(node.engine),
      models: strings(node.models, MAX_MODELS_PER_NODE),
      providerEmail: typeof node.provider_email === 'string' && node.provider_email ? node.provider_email : null,
    }
  })
}

/** `last_known`, or null when it is absent or not in the shape grid-apis writes. Parsing it sends nothing. */
export function parseLastKnown(value: unknown): LastKnown | null {
  if (!isObject(value)) return null
  const record: Unchecked<WireLastKnown> = value
  const age = record.age_seconds
  if (typeof age !== 'number' || !Number.isFinite(age) || age < 0) return null
  if (!Array.isArray(record.nodes)) return null
  const nodes = record.nodes.filter(isObject).slice(0, MAX_NODES).map((raw) => {
    const node: Unchecked<LastKnownNode> = raw
    return { name: text(node.name), engine: text(node.engine), models: strings(node.models, MAX_MODELS_PER_NODE) }
  })
  return { ageSeconds: age, nodes, ids: strings(record.ids, MAX_IDS) }
}

/**
 * Read a grid's public overview, with no credential, and say which of the four it is.
 *
 * Asleep is a 503 whose JSON `code` EQUALS `grid_asleep` and nothing else: `grid_stopped` (its owner
 * stopped it), `grid_master_down`, a 410 for a deleted grid and a codeless 503 are all "not answering",
 * and so is a 200 that is not an overview.
 */
export async function readOverview(base: string): Promise<GridRead> {
  let answer: { status: number; body: unknown }
  try {
    answer = await get(base, OVERVIEW_PATH, 'read')
  } catch {
    return { kind: 'unreachable' }
  }
  const { status, body } = answer
  if (status === REFUSAL_STATUS[GRID_ASLEEP_CODE] && isObject(body)) {
    const refusal: Unchecked<GridAsleep> = body
    if (refusal.code === GRID_ASLEEP_CODE) return { kind: 'asleep', lastKnown: parseLastKnown(refusal.last_known) }
  }
  // A 200 that is not an overview (a maintenance page, a proxy's own JSON) is not "awake with nothing":
  // read as that, it would count as an empty answer and start taking models off every list.
  if (status !== 200 || !isObject(body)) return { kind: 'unanswered' }
  const overview: Unchecked<GridOverview> = body
  if (!Array.isArray(overview.nodes)) return { kind: 'unanswered' }
  const curatedIds = Array.isArray(overview.models)
    ? overview.models.filter(isObject).map((entry: Unchecked<OverviewModel>) => text(entry.id)).filter(Boolean)
      .slice(0, MAX_IDS)
    : []
  const rawNodes = overview.nodes.filter(isObject).slice(0, MAX_NODES)
  return { kind: 'awake', nodes: readNodes(rawNodes), curatedIds, rawNodes, windows: readWindows(overview.models, rawNodes) }
}

/** No model's window is this large; a number past it is not one. */
const MAX_WINDOW = 100_000_000

/**
 * Each model's context window as the overview reports it — the largest of its curated entry's
 * `context_length` and every node's `model_capabilities[id].context_length`. The same figure the relay's
 * signed-in `/models` gives as `context_window` (grid-src `advertised_context_window`, MAX across the
 * engines serving it), read here without a credential. Keyed without case.
 */
function readWindows(curated: unknown, nodes: Array<Record<string, unknown>>): Record<string, number> {
  const windows: Record<string, number> = {}
  const take = (id: unknown, value: unknown): void => {
    const key = idKey(text(id))
    if (!key || typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0 || value > MAX_WINDOW) return
    if (Object.keys(windows).length >= MAX_IDS && !(key in windows)) return
    windows[key] = Math.max(windows[key] ?? 0, value)
  }
  if (Array.isArray(curated)) {
    for (const entry of curated.filter(isObject) as Array<Unchecked<OverviewModel>>) take(entry.id, entry.context_length)
  }
  for (const raw of nodes) {
    const node: Unchecked<OverviewNode> = raw
    const capabilities = isObject(node.model_capabilities) ? node.model_capabilities : {}
    for (const [id, cell] of Object.entries(capabilities).slice(0, MAX_MODELS_PER_NODE)) {
      if (isObject(cell)) take(id, (cell as Unchecked<NodeModelCapability>).context_length)
    }
  }
  return windows
}

/** The master's display rule (grid-src `model_ids.display_model_name`): a trailing `.gguf` removed,
 *  compared without regard to case, and the case of what is left KEPT. */
export function displayModelName(raw: string): string {
  return raw.toLowerCase().endsWith('.gguf') ? raw.slice(0, -'.gguf'.length) : raw
}

/**
 * Every served model's exact-case name from the grid's public provider discovery, under the display rule.
 * Asked only when an awake answer names a model no other source can spell. Any failure is an empty list,
 * which leaves the lower-case id the overview gave — a spelling problem, never a reason to fail a read.
 */
export async function readDiscoveryIds(base: string): Promise<string[]> {
  try {
    const { status, body } = await get(base, DISCOVER_PATH, 'read')
    if (status !== 200 || !isObject(body)) return []
    const discovery: Unchecked<ProviderDiscovery> = body
    if (!Array.isArray(discovery.providers)) return []
    const ids: string[] = []
    for (const provider of discovery.providers.filter(isObject) as Array<Unchecked<DiscoveredProvider>>) {
      const capabilities: Unchecked<DiscoveredCapabilities> = isObject(provider.capabilities) ? provider.capabilities : {}
      const entries = isObject(capabilities.models) ? capabilities.models : {}
      if (!Array.isArray(provider.models)) continue
      for (const route of provider.models) {
        const entry = typeof route === 'string' ? entries[route] : undefined
        const raw = isObject(entry) ? text((entry as Unchecked<DiscoveredModel>).raw_model_id) : ''
        if (raw) ids.push(displayModelName(raw))
      }
    }
    return ids.slice(0, MAX_IDS)
  } catch {
    return []
  }
}

/** `grid info <grid> --json`, reduced to what a read needs. Null when `grid` could not answer. */
export interface GridInfo {
  /** The owner status (`running`, `asleep`, `stopped`, …); null for a member, who cannot read it. */
  status: string | null
  /** The grid's address; reads go to `<gridUrl>/relay/v1/grid/overview`. */
  gridUrl: string | null
}

export async function readGridInfo(gridName: string): Promise<GridInfo | null> {
  const { value } = await gridJson<Json>(['--remote', 'info', gridName])
  if (!isObject(value)) return null
  return {
    status: typeof value.status === 'string' && value.status ? value.status : null,
    gridUrl: typeof value.grid_url === 'string' && value.grid_url.trim() ? value.grid_url.trim() : null,
  }
}

/** The `code` of `grid`'s `--json` refusal envelope (one JSON line on stderr), or null. */
function envelopeCode(stderr: string): string | null {
  return gridEnvelopes(stderr).find((envelope) => envelope.code !== null)?.code ?? null
}

/**
 * The fallback for a machine that reaches the internet only through something the daemon's own `fetch`
 * does not use (an HTTP proxy the `grid` CLI honours): `grid models <grid> --json --no-wake`, ONCE.
 *
 * ⚠️ Never retried without the flag. A `grid` too old for it exits 2 before sending anything, and that is
 * "no read" — a stale list, which is the direction every failure here must take.
 */
export async function readViaCli(gridName: string): Promise<GridRead> {
  const result = await gridExec(['--remote', 'models', gridName, NO_WAKE_FLAG, '--json'])
  if (result.code !== 'OK') {
    return envelopeCode(result.stderr) === GRID_ASLEEP_CODE ? { kind: 'asleep', lastKnown: null } : { kind: 'unanswered' }
  }
  let rows: unknown
  try { rows = JSON.parse(result.stdout) } catch { return { kind: 'unanswered' } }
  if (!Array.isArray(rows)) return { kind: 'unanswered' }
  // `grid models` answers one row per (model, node); the picture wants nodes.
  const byNode = new Map<string, ReadNode>()
  const exact: string[] = []
  for (const row of rows.filter(isObject).slice(0, MAX_NODES * MAX_MODELS_PER_NODE)) {
    const model = text(row.model)
    if (!model) continue
    const name = text(row.node)
    const engine = text(row.engine)
    const key = `${name}\u0000${engine}`
    const node = byNode.get(key) ?? { name, engine, models: [], providerEmail: null }
    node.models.push(model)
    byNode.set(key, node)
    exact.push(model)
  }
  const nodes = [...byNode.values()].slice(0, MAX_NODES)
  // The Model Manager reads node objects; these carry what `grid models` knows, and a node it lists is
  // one the grid is routing to right now.
  const rawNodes = nodes.map((node) => ({ name: node.name, engine: node.engine, models: node.models, online: true }))
  return { kind: 'awake', nodes, curatedIds: exact.slice(0, MAX_IDS), rawNodes, windows: {} }
}