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.

12.3 KB
Raw Blame
import { access } from 'node:fs/promises'
import { constants } from 'node:fs'
import { isAbsolute } from 'node:path'
import { readMachineResources } from '../lib/machineResources.js'
import { commandAvailableInInteractiveShell, type CommandAvailability } from '../lib/engineLaunch.js'
import { launchModelEngines } from '../lib/launchModel.js'
import { object } from './wire.js'
import { readCapacityDisk } from './disk.js'
import { floorOf, heavyNeed } from './machineFit.js'
import type { Needs } from './route.js'

type Json = Record<string, unknown>
export interface Requirements {
  memoryBytes: number; diskBytes: number; maxCpuPercent: number
  tools: string[]; devices: string[]; quotaRequired: boolean
}
/** What `start` asks of a machine when the Lead has no reason to ask for more: the help's template. CPU use is only a momentary
 *  reading: a busy machine would refuse every start (seen in the route e2e at 98.7%), so no cap; memory, disk and pressure gate it. */
export const START_REQUIREMENTS: Requirements = { memoryBytes: 2147483648, diskBytes: 10737418240, maxCpuPercent: 100, tools: ['git'], devices: [], quotaRequired: false }
/** The same plus what the task needs. The route admits a pick on exactly this, so the start it suggests is admitted too. Heavy
 *  work asks only the least it can run with (machineFit.ts floorOf), so a machine the route ranks later, between half the need
 *  and the need, still admits its start (Lead, 10-31); the start says it is heavy in its own `heavy` field. */
export const startRequirements = (needs: Pick<Needs, 'tools' | 'devices' | 'heavy'>): Requirements => {
  const need = heavyNeed(needs), floor = need ? floorOf(need) : null
  return { ...START_REQUIREMENTS, tools: [...new Set([...START_REQUIREMENTS.tools, ...needs.tools])], devices: needs.devices,
    ...(floor ? { memoryBytes: Math.max(START_REQUIREMENTS.memoryBytes, floor.memoryBytes), diskBytes: Math.max(START_REQUIREMENTS.diskBytes, floor.diskBytes) } : {}) }
}

/** A missing result is a completed check; an absent value or failed check is only unverified. */
export function requiredToolReason(tool: string, reported: unknown, failure?: unknown): string | null {
  if (reported === true) return null
  if (reported === false) return `Required tool missing: ${tool}.`
  const detail = typeof failure === 'string' && failure ? `${failure} ` : ''
  return `Required tool not verified: ${tool}. ${detail}Ask the machine owner to check it and refresh the machine reading.`
}

export async function readCapabilities(input: Json, deps = {
  resources: readMachineResources,
  disk: readCapacityDisk,
  tool: (name: string): Promise<CommandAvailability> => commandAvailableInInteractiveShell(name, undefined, undefined, true),
  device: async (path: string) => { await access(path, constants.R_OK | constants.W_OK); return true },
}): Promise<Json> {
  const cwd = input.cwd, tools = input.tools ?? [], devices = input.devices ?? []
  if (typeof cwd !== 'string' || !isAbsolute(cwd) || cwd.length > 4096 || /[\x00-\x1f\x7f]/.test(cwd)
    || (input.worktree !== undefined && typeof input.worktree !== 'boolean')
    || !Array.isArray(tools) || tools.length > 20 || !tools.every(t => typeof t === 'string' && /^[A-Za-z0-9_.+-]{1,80}$/.test(t))
    || !Array.isArray(devices) || devices.length > 20 || !devices.every(d => typeof d === 'string' && isAbsolute(d) && d.length <= 4096 && !/[\x00-\x1f\x7f]/.test(d))) {
    return { error: 'INVALID_REQUEST', detail: 'Name an absolute project path and up to 20 tools and devices.' }
  }
  const probeTools = async () => {
    const answers: Array<readonly [string, CommandAvailability]> = []
    for (let index = 0; index < tools.length; index += 4) {
      answers.push(...await Promise.all(tools.slice(index, index + 4).map(async t => {
        const result = await deps.tool(t).catch(error => ({ status: 'unverified' as const,
          detail: (error instanceof Error ? error.message : String(error)).slice(0, 200) }))
        return [t, result] as const
      })))
    }
    return answers
  }
  // Requested only before admission. No new polling, command execution or shell
  // interpolation; the tool probe is the same bounded one native launches use.
  const [resources, disk, toolValues, deviceValues] = await Promise.all([
    deps.resources().catch(() => null), deps.disk(cwd, input.worktree === true).catch(() => null),
    probeTools(),
    Promise.all(devices.map(async d => [d, await deps.device(d).catch(() => false)] as const)),
  ])
  const toolProbeErrors = Object.fromEntries(toolValues.filter(([, result]) => result.status === 'unverified')
    .map(([name, result]) => [name, result.detail ?? 'The tool probe did not complete.']))
  return { ok: true, sampledAt: Date.now(), resources: { ...resources, projectDiskFreeBytes: disk?.freeBytes ?? null, projectDiskTotalBytes: disk?.totalBytes ?? null,
    projectDiskVolume: disk?.volume ?? null, projectDiskPath: disk?.path ?? null },
    tools: Object.fromEntries(toolValues.filter(([, result]) => result.status !== 'unverified').map(([name, result]) => [name, result.status === 'available'])),
    ...(Object.keys(toolProbeErrors).length ? { toolProbeErrors } : {}), devices: Object.fromEntries(deviceValues),
    // A daemon from before the launch flags leaves this out, and a start then switches the model after it.
    launchModel: launchModelEngines() }
}

const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v)
const GiB = 1024 ** 3
/** One decimal, rounded down, so a refusal never reads "2 GiB free, 2 GiB needed". */
export const gibibytes = (bytes: number) => `${Math.floor(Math.max(0, bytes) / GiB * 10) / 10} GiB`
/** The refusal for memory, the one start-failure reason every Swarm member may read (backend startFailure.ts): it says
 *  only numbers they already see in the Machines view. */
export const memoryShort = (freeBytes: number, neededBytes: number) =>
  `Not enough free memory: ${gibibytes(freeBytes)} free, ${gibibytes(neededBytes)} needed.`
/** The free and needed amounts of a `memoryShort` reason at the start of a host's raw reason, or null for any other. */
export function memoryShortIn(reason: unknown): { free: string; needed: string } | null {
  const match = typeof reason === 'string' ? /^Not enough free memory: (\d+(?:\.\d)? GiB) free, (\d+(?:\.\d)? GiB) needed\./.exec(reason) : null
  return match ? { free: match[1]!, needed: match[2]! } : null
}
/** Only measured windows leave the account reader. No credentials, emails or
 * invented token counts; an unreported/custom-profile allowance is unknown. */
export function quotaOf(reply: Json, engine: string, customAccount: boolean) {
  const reading = !customAccount && Array.isArray(reply.providers) ? reply.providers.map(object).find(r => r.provider === engine) : null
  const windows: Array<{ usedPercent: number; resetsAt: unknown; name: string }> = []
  if (reading?.outcome === 'answered' && reading.httpStatus === 200) {
    const body = object(reading.body)
    const raw = engine === 'claude' ? [body.five_hour, body.seven_day]
      : engine === 'codex' ? [object(body.rate_limit).primary_window, object(body.rate_limit).secondary_window] : []
    // Both engines report the short window first and the weekly one second, so the name is by that position, kept even
    // when one is missing — unless the window says how long it is, as Codex's do (`limit_window_seconds`, the length the
    // Desktop names them by). 2026-10-24: a Codex account reported only its weekly window, first; read as its 5-hour one,
    // the weekly read as missing, and the route never offered Codex while a Claude candidate fit.
    raw.forEach((value, index) => {
      const w = object(value), used = w.utilization ?? w.used_percentage ?? w.used_percent, length = w.limit_window_seconds
      const name = finite(length) && length > 0 ? (length >= 86_400 ? 'weekly' : '5-hour') : index === 0 ? '5-hour' : 'weekly'
      if (finite(used) && used >= 0 && used <= 100 && !windows.some(x => x.name === name)) windows.push({ usedPercent: used, resetsAt: w.resets_at ?? w.reset_at ?? null, name })
    })
  }
  return { known: windows.length > 0, account: typeof reading?.account === 'string' ? reading.account : null, windows }
}
const VENDOR: Record<string, string> = { claude: 'Anthropic', codex: 'OpenAI' }
/** Why [engine]'s allowance could not be read from the account reader's [reply], or null when it was. Words only: no
 *  account, token or plan. A reading the CLI could not give says why itself (services/usage.ts). */
export function quotaUnknownReason(reply: Json, engine: string): string | null {
  if (quotaOf(reply, engine, false).known) return null
  const reading = Array.isArray(reply.providers) ? reply.providers.map(object).find(r => r.provider === engine) : undefined
  const vendor = VENDOR[engine] ?? 'The vendor'
  if (!reading) return 'The allowance reader on this machine did not answer.'
  if (reading.outcome === 'signedOut') return 'No subscription sign-in is stored on this machine.'
  if (reading.outcome !== 'answered') return typeof reading.message === 'string' && reading.message ? reading.message : `${vendor} could not be reached.`
  const status = reading.httpStatus
  if (status === 429) return `${vendor} is limiting how often the allowance can be read.`
  if (status === 200) return `${vendor} answered without usage windows.`
  return `${vendor} answered with an error (HTTP ${finite(status) ? status : 'unknown'}).`
}
/** An engine that runs on an API key or a gateway's base URL has no subscription windows to read: it is metered, not unknown.
 * `env` is the machine's own, so the host reads its own and a key never leaves it. */
export function meteredEngine(engine: string, env: NodeJS.ProcessEnv): boolean {
  const names = engine === 'claude' ? ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY']
    : engine === 'codex' ? ['OPENAI_BASE_URL', 'OPENAI_API_KEY', 'CODEX_API_KEY'] : []
  return names.some(name => !!env[name]?.trim())
}
export function admission(capacity: Json, engine: Json, quota: ReturnType<typeof quotaOf>, requirements: Requirements, customAccount = false) {
  const reasons: string[] = [], unknown: string[] = []
  const resources = object(capacity.resources), tools = object(capacity.tools), devices = object(capacity.devices), toolProbeErrors = object(capacity.toolProbeErrors)
  if (engine.installed !== true) reasons.push('The selected agent engine is not installed on this machine.')
  const memory = finite(resources.memoryTotalBytes) && finite(resources.memoryUsedBytes)
    ? resources.memoryTotalBytes - resources.memoryUsedBytes : null
  for (const [label, value, needed] of [
    ['Available memory', memory, requirements.memoryBytes],
    ['Project disk space', resources.projectDiskFreeBytes, requirements.diskBytes],
  ] as const) {
    if (!finite(value)) { unknown.push(`${label} is unknown.`); if (needed > 0) reasons.push(`${label} could not be verified.`) }
    else if (value < needed) reasons.push(label === 'Available memory' ? memoryShort(value, needed) : `${label} is ${value} bytes; this work requires ${needed}.`)
  }
  if (!finite(resources.cpuPercent)) {
    unknown.push('CPU use is unknown.')
    if (requirements.maxCpuPercent < 100) reasons.push('CPU headroom could not be verified.')
  } else if (resources.cpuPercent > requirements.maxCpuPercent) reasons.push(`CPU use is ${resources.cpuPercent}%; the requested maximum is ${requirements.maxCpuPercent}%.`)
  if (resources.memoryPressure === 'critical') reasons.push('The machine reports critical memory pressure.')
  for (const t of requirements.tools) {
    const reason = requiredToolReason(t, tools[t], toolProbeErrors[t])
    if (reason) reasons.push(reason)
  }
  for (const d of requirements.devices) if (devices[d] !== true) reasons.push(`Required device unavailable: ${d}.`)
  if (!quota.known) {
    unknown.push('Subscription allowance is unknown for this account.')
    if (requirements.quotaRequired) reasons.push('The requested subscription allowance could not be verified.')
  } else if (quota.windows.some(w => w.usedPercent >= 100)) unknown.push(USED_UP_WINDOW)
  return { allowed: reasons.length === 0, reasons, unknown }
}
/** Quota is information, not a gate (project instructions, phase 4): a start on a used-up account goes ahead, its engine
 *  shows its usage limit, and the agent resumes when the window resets (superTabs/limitResume.ts). The route says it too. */
export const USED_UP_WINDOW = 'The subscription has a used-up usage window: work there waits until it resets.'