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.

28.4 KB
Raw Blame
// GENERATED by grid-protocol 0.1.1 — do not edit. The source is autonomous-grid's
// `protocol/grid_protocol/schemas/`: change a schema there, run `python -m grid_protocol._codegen --write`,
// and copy this file.

export const PROTOCOL_VERSION = '0.1.1'

export const NO_WAKE_FLAG = '--no-wake'

/** GET /nodes/discover */
export const DISCOVER_PATH = '/nodes/discover'

export const PROVIDER_ROUTE_PREFIX = 'provider:'

/** GET /relay/v1/models */
export const MODELS_PATH = '/relay/v1/models'

/** POST /nodes/heartbeat */
export const HEARTBEAT_PATH = '/nodes/heartbeat'

export const UNHEALTHY_MODELS_LOAD_KEY = 'unhealthy_models'

/** GET /relay/v1/poll */
export const POLL_PATH = '/relay/v1/poll'

export const RELAY_PATH = '/relay/v1'

/** PUT /nodes/{node_id} */
export const NODE_PATH = '/nodes/{node_id}'

export const CAPABILITIES_SCHEMA_VERSION = 1

/** POST /relay/v1/response/{transaction_id} */
export const RESPONSE_PATH = '/relay/v1/response/{transaction_id}'

export const PROVIDER_ATTEMPT_HEADER = 'X-Grid-Provider-Attempt'

/** POST /relay/v1/error/{transaction_id} */
export const ERROR_REPORT_PATH = '/relay/v1/error/{transaction_id}'

export const NO_PROVIDERS_AVAILABLE_CODE = 'no_providers_available'

export const MODEL_NOT_FOUND_CODE = 'model_not_found'

export const RELAY_RESTARTING_CODE = 'relay_restarting'

/** GET /relay/v1/grid/overview */
export const OVERVIEW_PATH = '/relay/v1/grid/overview'

export const RETRY_AFTER_HEADER = 'Retry-After'

export const GRID_ASLEEP_CODE = 'grid_asleep'

export const GRID_STOPPED_CODE = 'grid_stopped'

export const GRID_DELETED_CODE = 'grid_deleted'

export const GRID_MASTER_DOWN_CODE = 'grid_master_down'

export const FEATURE_RETIRED_CODE = 'feature_retired'

/** How often a provider beats (public CLI `relay.HEARTBEAT_INTERVAL`). */
export const HEARTBEAT_INTERVAL_SECONDS = 30

/**
 * A node silent this long is not selected (grid-src `NODE_TTL_SECONDS`, a knob; the heartbeat answer's
 * `ttl_seconds`).
 */
export const NODE_TTL_SECONDS = 120

/**
 * How long a poll is held before its 204 (grid-src `poll_timeout_seconds`); a provider's own poll timeout
 * must be longer.
 */
export const POLL_WINDOW_SECONDS = 30

/** A provider parked on grid_asleep probes this often (public CLI `serve._ASLEEP_PROBE_SECONDS`). */
export const ASLEEP_PROBE_SECONDS = 10

/** A provider parked on grid_stopped probes this often: only the owner's start ends it. */
export const STOPPED_PROBE_SECONDS = 60

/** The next beat after a failed one (the platform's restart of a dead master). */
export const AFTER_A_FAILED_BEAT_SECONDS = 10

/**
 * Inside the boot-hold window a request that finds NO provider is held this long for one to beat (grid-src
 * `GRID_BOOT_HOLD_SECONDS`, a knob). A woken master starts with every provider past its TTL.
 */
export const BOOT_HOLD_SECONDS = 30

/**
 * How long after a master starts its boot hold applies (grid-src `GRID_BOOT_HOLD_WINDOW_SECONDS`, a knob).
 */
export const BOOT_HOLD_WINDOW_SECONDS = 120

/**
 * A model is dropped from a reader's list only after this long absent across two or more awake reads (a node
 * TTL and a beat), so a cold wake does not blank a list (harness `GRID_MODEL_RETENTION_SECONDS|_MS`).
 */
export const MODEL_RETENTION_SECONDS = 150

/**
 * The last-known record is captured only from a master up this long: a node TTL and a beat, with a margin
 * (grid-apis `sleep_record.MIN_UPTIME_SECONDS`).
 */
export const SLEEP_RECORD_MIN_UPTIME_SECONDS = 180

/**
 * No record is written until this long after somebody lost access to the grid: their machine can stay listed
 * for a TTL and a beat (grid-apis `sleep_record.ACCESS_LOSS_SETTLE_SECONDS`).
 */
export const ACCESS_LOSS_SETTLE_SECONDS = 150

/**
 * 29 days: a last-known record older than this is not sent, and a reader ignores one (grid-apis
 * `sleep_record.MAX_AGE_SECONDS`; harness `GRID_LAST_KNOWN_MAX_AGE_SECONDS|_MS`).
 */
export const LAST_KNOWN_MAX_AGE_SECONDS = 2505600

/** 30 days: a master forgets a node row silent this long (grid-src `registry.prune_stale_nodes`). */
export const MASTER_NODE_PRUNE_SECONDS = 2592000

/** Each refusal code, and the HTTP status that carries it. */
export const REFUSAL_STATUS = {
  no_providers_available: 503,
  model_not_found: 404,
  relay_restarting: 503,
  grid_asleep: 503,
  grid_stopped: 503,
  grid_deleted: 410,
  grid_master_down: 503,
  feature_retired: 410,
} as const

/**
 * The one JSON line the public `grid` CLI writes on stderr when a `--json` command fails. Under `--no-wake`
 * (`grid models | engines | stats`, from 0.3.49) the overview and discovery go out with no credential, an
 * owner status already `asleep` is answered with no request at all, and `code` is `grid_asleep` when the
 * proxy said so and null for every other refusal. A `grid` older than 0.3.49 exits 2 at argparse before it
 * sends anything; a caller reads that as "no read" and must never retry without the flag, which would be a
 * wake. Accepted and ignored in local mode.
 */
export interface CliErrorEnvelope {
  error: {
    code: string | null
    message: string
    /** The HTTP status behind the refusal, when there was one. */
    status: number | null
    [key: string]: unknown
  }
  [key: string]: unknown
}

/**
 * A grid's provider discovery (grid-src `server.discover`). Public at the master, and a credential-less GET
 * never wakes a sleeping grid, as for the overview. Readers take only `providers[].models` and
 * `providers[].capabilities.models[<route id>].raw_model_id` — the exact-case model name the overview
 * lower-cases — and read any failure as an empty list.
 */
export interface ProviderDiscovery {
  providers: DiscoveredProvider[]
  [key: string]: unknown
}

export interface DiscoveredProvider {
  node_id: string
  /**
   * Route ids, `provider:<node id>:<hash>`. A route id embeds a NODE id, so nothing that outlives a
   * membership (the sleep record) may store one. Models the provider withdrew in its heartbeat are left out.
   */
  models: string[]
  pricing: {
    [key: string]: number
  }
  capabilities: DiscoveredCapabilities
  load: {
    [key: string]: unknown
  }
  max_concurrency: number
  endpoint_url: string | null
  last_heartbeat: string | null
  first_seen_at: string | null
  verified_at: string | null
  /** The node's presentation metadata, as the overview publishes it. */
  meta: {
    [key: string]: unknown
  }
  [key: string]: unknown
}

/** The provider's capability envelope, normalized by the master. `{}` when the provider published none. */
export interface DiscoveredCapabilities {
  schema_version?: number
  models?: {
    [key: string]: DiscoveredModel
  }
  [key: string]: unknown
}

export interface DiscoveredModel {
  /**
   * The model's exact-case name as its engine serves it. Shown under the display rule: a trailing `.gguf`
   * removed, case kept.
   */
  raw_model_id: string
  public_model_id?: string
  provider_group_id?: string | null
  provider_supplied?: boolean
  [key: string]: unknown
}

/**
 * What the platform recorded a grid serving when it put the grid to sleep (grid-apis
 * `sleep_record.answer_field`), carried on the `503 grid_asleep` answer to a credential-less GET of the
 * overview. The record is kept only from a master up SLEEP_RECORD_MIN_UPTIME_SECONDS, and is deleted when
 * somebody loses access to the grid: it must never name a machine whose owner lost access. Drift costs a
 * stale or empty model list on a grid the reader has never seen awake — never a wake.
 */
export interface LastKnown {
  /**
   * How old the record is, computed by the SERVER from its own clock, so no client clock matters. Never above
   * LAST_KNOWN_MAX_AGE_SECONDS: an older record is not sent.
   */
  age_seconds: number
  nodes: LastKnownNode[]
  /** Exact-case candidate model ids: a spelling source for a case map, never a list of what is served. */
  ids: string[]
  [key: string]: unknown
}

export interface LastKnownNode {
  name: string
  engine: string | null
  /** Lower-cased, as the overview lists them. */
  models: string[]
  [key: string]: unknown
}

/**
 * The relay's OpenAI-style model list. Needs a credential (scope `inference:models`), so a GET of it WAKES a
 * sleeping grid: it belongs to a person's act (the harness's wake read), never to an automatic read. When the
 * router is on and the list is not empty, the router's rows (`owned_by: grid-router`) come first.
 */
export interface ModelList {
  object: 'list'
  data: ModelEntry[]
  [key: string]: unknown
}

/**
 * A served model, or a router row (`Auto`, and the effort-mode rows while effort mode is served), which
 * carries only the four required keys.
 */
export interface ModelEntry {
  id: string
  object: 'model'
  created: number
  owned_by: string
  display_name?: string
  provider_count?: number
  provider_supplied?: boolean
  trusted?: boolean
  raw_model_id?: string
  raw_model_ids?: string[]
  provider_group_id?: string | null
  provider_group_ids?: string[]
  /** The largest window any engine serving the model was started with. */
  context_window?: number | null
  [key: string]: unknown
}

/**
 * A provider's heartbeat: the body of `POST /nodes/heartbeat`, every HEARTBEAT_INTERVAL_SECONDS, with a node
 * token (the node is the token's, not the body's). It never wakes a sleeping grid; on a sleeping or stopped
 * grid it is the parked provider's one probe. In grid mode the master answers 404 to a heartbeat from a node
 * that has not completed its registration as a provider (`PUT /nodes/{node_id}` with role `provider` or
 * `both`; a `consumer` one, which is how a provider leaves, does not count), and nothing else makes a node
 * registered: not a token, not a heartbeat, not a poll. The public CLI registers again when it is answered
 * 404, so a node whose row was pruned, lost in a restore or left behind by a move is serving again within one
 * heartbeat, instead of staying connected and never being given work.
 */
export interface NodeHeartbeat {
  load?: NodeLoad
  meta?: NodeMeta
  [key: string]: unknown
}

export interface NodeHeartbeatAnswer {
  status: 'ok'
  /** The master's node TTL (NODE_TTL_SECONDS by default): a node silent this long is not selected. */
  ttl_seconds: number
  [key: string]: unknown
}

/**
 * Live telemetry. Each key is optional, and a key the provider did not measure is left out rather than sent
 * as zero.
 */
export interface NodeLoad {
  active_tasks?: number
  platform?: string
  /** Models whose engine is failing; the relay stops selecting them until they drop off this list. */
  unhealthy_models?: string[]
  gpu_count?: number
  memory_total_mb?: number
  memory_used_mb?: number
  gpu_util?: number
  gpu_temp_c?: number
  gpu_power_w?: number
  gpu_power_limit_w?: number
  disk_total_gb?: number
  disk_used_gb?: number
  tok_s?: number
  codex_rate_limits?: {
    [key: string]: unknown
  }
  quota?: {
    [key: string]: unknown
  }
  [key: string]: unknown
}

/**
 * One request for a provider to serve: the 200 body of `GET /relay/v1/poll` (node token). The master
 * long-polls for POLL_WINDOW_SECONDS and answers 204 with an EMPTY body when no work came, so a client's own
 * timeout must be longer. A poll never wakes a sleeping grid. Readers ignore keys they do not know.
 */
export interface PollJob {
  transaction_id: string
  /**
   * Where to send `body` on the engine: `chat/completions`, `completions`, `responses`, or a `media/` path
   * while media is served.
   */
  endpoint_path: string
  /** The request, already in `wire_format`. */
  body: {
    [key: string]: unknown
  }
  is_stream: boolean
  /** Epoch seconds. */
  created_at: number
  /** What is left of the request's budget. */
  inference_timeout_seconds: number
  /** The dialect `body` is in. An older provider ignores it. */
  wire_format: 'chat' | 'responses' | 'anthropic'
  provider_attempt: number
  /**
   * Only for a provider whose capability entry sets `provider_attempt_tokens`; echoed in
   * `X-Grid-Provider-Attempt` on the result.
   */
  provider_attempt_token?: string
  [key: string]: unknown
}

/**
 * A provider's registration: the body of `PUT /nodes/{node_id}`, with a node token whose node is the path's.
 * Every key is optional at the master and an unknown key is ignored; the public CLI always sends `role`,
 * `models` and `pricing`, and leaving a grid sends `{role: consumer, models: [], pricing: {}}`. A
 * registration WAKES a sleeping grid (it carries a credential). A node answered 404 on its heartbeat
 * registers again.
 */
export interface NodeRegistration {
  /** `provider`, or `consumer` to stop serving. */
  role?: string
  models?: string[]
  pricing?: {
    [key: string]: number
  }
  capabilities?: NodeCapabilities
  meta?: NodeMeta
  /**
   * Concurrent requests this provider serves. Null or absent: no change. The master clamps it to at least 1.
   */
  max_concurrency?: number | null
  [key: string]: unknown
}

export interface NodeRegistrationAnswer {
  status: 'updated'
  [key: string]: unknown
}

/**
 * The provider's capability envelope. The master keeps it only at this schema version (otherwise it stores
 * `{}`), and refuses it 400 unless `models`' keys are exactly the registration's `models`.
 */
export interface NodeCapabilities {
  schema_version: 1
  models: {
    [key: string]: ModelCapability
  }
  [key: string]: unknown
}

/**
 * What one model on this node can do. `endpoints` absent means chat completions only (fail-closed for the
 * Responses dialect).
 */
export interface ModelCapability {
  /** The relay's endpoint paths, e.g. `chat/completions`, `responses`. */
  endpoints?: string[]
  input_modalities?: string[]
  output_modalities?: string[]
  context_window?: number
  max_output_tokens?: number
  features?: {
    [key: string]: boolean
  }
  limits?: {
    [key: string]: unknown
  }
  /**
   * The provider echoes `X-Grid-Provider-Attempt`; the relay then puts `provider_attempt_token` in its poll
   * jobs.
   */
  provider_attempt_tokens?: boolean
  [key: string]: unknown
}

/** Presentation metadata. An empty object means "no change". */
export interface NodeMeta {
  name?: string
  /** The operator chose `name`. Absent means NOT chosen, which is the private answer. */
  name_chosen?: boolean
  engine?: string
  device?: string
  chip?: string
  memory_gb?: number
  device_class?: string
  plan_type?: string
  [key: string]: unknown
}

/**
 * The answer to a provider's result: `POST /relay/v1/response/{transaction_id}` with a node token, whose body
 * is the engine's own bytes — one JSON body (`application/json`), or its SSE lines as they come
 * (`text/event-stream`). The master checks the framing and answers `400` ResultRejected for a malformed
 * result, `409` for a stale attempt, `410` when the transaction already ended. An upload never wakes a
 * sleeping grid.
 */
export interface ResultDelivered {
  status: 'delivered'
  [key: string]: unknown
}

/** 400: the result's framing is wrong, and the request is failed rather than delivered. */
export interface ResultRejected {
  error: 'validation_failed'
  reason: 'bare_cr_in_sse_line' | 'unterminated_sse_block' | 'invalid_responses_stream' | 'truncated_responses_stream' | 'non_stream_responses_submit' | 'invalid_responses_body' | 'non_terminal_responses_body' | 'invalid_json'
  [key: string]: unknown
}

/** A provider's report that it could not serve the request: `POST /relay/v1/error/{transaction_id}`. */
export interface ErrorReport {
  /** What failed, for the log; the public CLI sends a string. */
  error: unknown
  /** Tokens already streamed; the relay retries on another provider only when none were. */
  tokens_delivered?: number
  [key: string]: unknown
}

export interface ErrorReportAnswer {
  status: 'failed' | 'retried'
  [key: string]: unknown
}

/**
 * OpenAI's error envelope. A master answers an inference request's failure in it when the caller asked for
 * OpenAI errors (a Bearer `lga_sk_` key, or the error-format header); otherwise the same failure is
 * `{"detail": <message>}` with no code. `/messages` answers in Anthropic's envelope instead. Keys a master
 * adds go BESIDE `error`, never inside it.
 */
export interface OpenAIError {
  error: {
    message: string
    type: string
    param: string | null
    /** The relay's name for the failure. */
    code: string | null
    [key: string]: unknown
  }
  [key: string]: unknown
}

/**
 * No provider serves the requested model now, on a grid that has served it (its engine may only be away),
 * that has never had an engine at all, or whose master cannot tell: retryable. On a grid that has had an
 * engine, a model none of its engines ever served is ModelNotFound instead. Inside a master's boot hold
 * (BOOT_HOLD_WINDOW_SECONDS after it starts) a request for a model nobody serves yet is held up to
 * BOOT_HOLD_SECONDS first, so that a provider parked on the sleeping grid can come back.
 */
export interface NoProvidersAvailable {
  error: {
    message: string
    type: 'server_error'
    param: string | null
    code: 'no_providers_available'
    [key: string]: unknown
  }
  [key: string]: unknown
}

/**
 * No engine on this grid has ever served the requested model: none it still has a node row for, live or not,
 * and nothing in its model catalog, whose rows outlive an engine that left. No wait can bring one, so it is
 * refused at once (after a woken master's boot hold) rather than as the retryable NoProvidersAvailable, which
 * a grid that has served the model, a grid that has never had an engine, and a master that cannot tell keep.
 * The message names what the grid serves now and never echoes the requested name. A caller that did not ask
 * for OpenAI errors gets `{"detail": <message>}`. Displayed, never parsed: the public CLI must not parse it.
 */
export interface ModelNotFound {
  error: {
    message: string
    type: 'invalid_request_error'
    param: string | null
    code: 'model_not_found'
    [key: string]: unknown
  }
  [key: string]: unknown
}

/**
 * The master holding the request ended it while retiring or stopping: send it again. A non-stream request is
 * answered 503 with this envelope (or `{"detail": <message>}` for a caller that did not ask for OpenAI
 * errors). A chat stream ends with `data: {"error": <this envelope's error>}`. A Responses stream ends with a
 * `response.failed` event whose `response.error.code` is `server_error`: the Responses code set is closed, so
 * this name never reaches a Responses client. The public CLI must not parse it.
 */
export interface RelayRestarting {
  error: {
    message: string
    type: 'server_error'
    param: null
    code: 'relay_restarting'
    [key: string]: unknown
  }
  [key: string]: unknown
}

/**
 * A grid's public overview (grid-src `overview.build_grid_overview`). The master serves it with NO
 * authentication, and a credential-less GET never wakes a sleeping grid: grid-proxy answers it `503
 * grid_asleep` with `last_known` instead, while a GET that carries any credential (its presence, not its
 * validity) wakes the grid. So an automatic reader — the harness daemon, `grid models|engines|stats
 * --no-wake` — must never add one. Readers take `nodes[].{name, engine, models}` and `models[].id`; anything
 * that is not a 200 object with a `nodes` array is "not answering", never "awake with nothing".
 */
export interface GridOverview {
  grid: {
    /** `running` whenever a master answers. */
    state: string
    [key: string]: unknown
  }
  /** Whether the reserved model `auto` routes on this grid. */
  router_enabled: boolean
  advertises_chat_completions: boolean
  advertises_responses: boolean
  advertises_messages: boolean
  stats: {
    models: number
    nodes: number
    concurrent_capacity: number
    /** A fixed placeholder, not a measurement. */
    uptime_pct: number
    [key: string]: unknown
  }
  /**
   * What the grid answered in the rollup window; null until a rollup has landed (a master warming up must not
   * report an idle grid).
   */
  answered: null | Answered
  models: OverviewModel[]
  nodes: OverviewNode[]
  [key: string]: unknown
}

export interface Answered {
  window_seconds: number
  /** Includes `tokens_cached`, the cached share of the prefill. */
  tokens_in: number
  tokens_cached: number
  tokens_out: number
  requests: number
  [key: string]: unknown
}

/** An admin-curated model a live node of its provider serves now (or a `coming_soon` placeholder). */
export interface OverviewModel {
  /** Lower-cased. */
  id: string
  name: string
  maker: string | null
  modality: string
  context_length: number | null
  vision: boolean
  pricing: null | {
    unit: 'token'
    input_per_1m: number
    output_per_1m: number
    [key: string]: unknown
  }
  status: string
  [key: string]: unknown
}

/**
 * One live engine node. Telemetry fields are each independently null when the node did not report them —
 * never a zero.
 */
export interface OverviewNode {
  /**
   * On an `os-community` grid, the machine's name only when its operator chose it; otherwise an anonymous
   * `node-<id>` label.
   */
  name: string
  /** Withheld (null) where the grid does not publish it. */
  provider_email: string | null
  device: string
  chip?: string | null
  memory_gb?: number | null
  vram_total_mb?: number | null
  vram_gb?: number | null
  vram_used_mb?: number | null
  gpu_util_pct?: number | null
  gpu_temp_c?: number | null
  gpu_power_w?: number | null
  gpu_power_limit_w?: number | null
  disk_total_gb?: number | null
  disk_used_gb?: number | null
  platform?: string | null
  device_class: string
  /** `models[0]`, or null when the node serves nothing. */
  model: string | null
  /** Every model the node serves, lower-cased (the display rule: a trailing `.gguf` removed). */
  models: string[]
  model_engines: {
    [key: string]: string
  }
  /**
   * Keyed like `models`. A model absent here is one the node published no capability envelope for — not one
   * with no window.
   */
  model_capabilities: {
    [key: string]: NodeModelCapability
  }
  responses_models: string[]
  engine: string
  plan_type?: string | null
  codex_rate_limits?: {
    [key: string]: unknown
  } | null
  throughput_tok_s?: number | null
  max_concurrency: number
  answered: null | NodeAnswered
  online: boolean
  [key: string]: unknown
}

export interface NodeModelCapability {
  context_length: number | null
  vision: boolean | null
  [key: string]: unknown
}

export interface NodeAnswered {
  window_seconds: number
  tokens_in: number
  tokens_cached: number
  tokens_out: number
  requests: number
  by_model: Array<{
    model: string
    tokens_in: number
    tokens_cached: number
    tokens_out: number
    requests: number
    [key: string]: unknown
  }>
  [key: string]: unknown
}

/**
 * The platform's coded refusal: a sentence for a person in `detail` and, BESIDE it (never under it), a
 * machine-readable `code`. grid-proxy sends it for a grid that is not up; a master sends it for a retired
 * feature. The public CLI compares `code` for EQUALITY, never for truthiness and never paired with the
 * status, and reads a code it does not know, or none, as a transient failure. grid-proxy's codeless answers
 * have this shape too: `404 unknown network`, `503` while a wake is starting (with `Retry-After: 20`), and
 * `502`/`504` when the master did not answer. The public CLI acts on exactly three codes (grid_asleep,
 * grid_stopped, grid_deleted); it must never parse the others, so that renaming one of them cannot change
 * what a provider does.
 */
export interface Refusal {
  /** A sentence for a person. Clients render it; its wording is not part of the contract. */
  detail: string
  /** The refusal's name, when it has one. Each named refusal is a definition below. */
  code?: string
  [key: string]: unknown
}

/**
 * The grid is asleep and this request did not wake it. A request that may wake a grid (a signed-in read,
 * inference, an owner's act, a provider's registration) is held and replayed instead, unless grid-proxy's
 * limits turn it away (then with a Retry-After: past a wake limit nothing is woken, past the waiting bound
 * the grid IS waking and only this request is not held); a provider's heartbeat, poll and callbacks, and any
 * credential-less read, never wake one. The public CLI's provider PARKS on it: its heartbeat probes every
 * ASLEEP_PROBE_SECONDS, bring-up on its own schedule, and the engine serves again by itself after a wake.
 */
export interface GridAsleep {
  detail: string
  code: 'grid_asleep'
  /**
   * Only on the answer to a credential-less GET of the overview, after `detail` and `code`. Absent when the
   * platform holds no record for the grid, or none younger than LAST_KNOWN_MAX_AGE_SECONDS.
   */
  last_known?: LastKnown
  [key: string]: unknown
}

/**
 * The grid's OWNER stopped it, and nothing wakes it until the owner starts it: not inference, not a read, not
 * a join. The public CLI's provider parks on it as on grid_asleep, probing every STOPPED_PROBE_SECONDS.
 */
export interface GridStopped {
  detail: string
  code: 'grid_stopped'
  [key: string]: unknown
}

/**
 * The grid was deleted. The only refusal that ENDS a provider: the public CLI stops the engine for good, so a
 * false positive would stop a provider serving a live grid. An older proxy answered `404 unknown network`
 * with no code instead.
 */
export interface GridDeleted {
  detail: string
  code: 'grid_deleted'
  [key: string]: unknown
}

/**
 * The grid should be running but its master refused the connection; the platform is bringing it back.
 * Deliberately NOT parsed for its value by the public CLI: a parked provider leaves the park on any code
 * other than a pause code, and otherwise retries it like any 503.
 */
export interface GridMasterDown {
  detail: string
  code: 'grid_master_down'
  [key: string]: unknown
}

/**
 * The route or model name belongs to a retired feature (media, distributed tasks, effort mode), and the
 * master answers this instead of serving it. The public CLI must not parse it.
 */
export interface FeatureRetired {
  detail: string
  code: 'feature_retired'
  [key: string]: unknown
}

/**
 * The timing values two or more parties must agree on, each in seconds. The rules BETWEEN them (a parked
 * probe fits twice in the boot hold; a model outlives a node TTL and a beat; the last-known record dies
 * before the master forgets its nodes) are checked by grid-protocol's own tests, because JSON Schema cannot
 * relate two values. Several are also operator knobs on the side that owns them (named in each description);
 * the value here is the default the others were built against.
 */
export interface Timing {
  /** How often a provider beats (public CLI `relay.HEARTBEAT_INTERVAL`). */
  heartbeat_interval_seconds: 30
  /**
   * A node silent this long is not selected (grid-src `NODE_TTL_SECONDS`, a knob; the heartbeat answer's
   * `ttl_seconds`).
   */
  node_ttl_seconds: 120
  /**
   * How long a poll is held before its 204 (grid-src `poll_timeout_seconds`); a provider's own poll timeout
   * must be longer.
   */
  poll_window_seconds: 30
  /** A provider parked on grid_asleep probes this often (public CLI `serve._ASLEEP_PROBE_SECONDS`). */
  asleep_probe_seconds: 10
  /** A provider parked on grid_stopped probes this often: only the owner's start ends it. */
  stopped_probe_seconds: 60
  /** The next beat after a failed one (the platform's restart of a dead master). */
  after_a_failed_beat_seconds: 10
  /**
   * Inside the boot-hold window a request that finds NO provider is held this long for one to beat (grid-src
   * `GRID_BOOT_HOLD_SECONDS`, a knob). A woken master starts with every provider past its TTL.
   */
  boot_hold_seconds: 30
  /**
   * How long after a master starts its boot hold applies (grid-src `GRID_BOOT_HOLD_WINDOW_SECONDS`, a knob).
   */
  boot_hold_window_seconds: 120
  /**
   * A model is dropped from a reader's list only after this long absent across two or more awake reads (a
   * node TTL and a beat), so a cold wake does not blank a list (harness `GRID_MODEL_RETENTION_SECONDS|_MS`).
   */
  model_retention_seconds: 150
  /**
   * The last-known record is captured only from a master up this long: a node TTL and a beat, with a margin
   * (grid-apis `sleep_record.MIN_UPTIME_SECONDS`).
   */
  sleep_record_min_uptime_seconds: 180
  /**
   * No record is written until this long after somebody lost access to the grid: their machine can stay
   * listed for a TTL and a beat (grid-apis `sleep_record.ACCESS_LOSS_SETTLE_SECONDS`).
   */
  access_loss_settle_seconds: 150
  /**
   * 29 days: a last-known record older than this is not sent, and a reader ignores one (grid-apis
   * `sleep_record.MAX_AGE_SECONDS`; harness `GRID_LAST_KNOWN_MAX_AGE_SECONDS|_MS`).
   */
  last_known_max_age_seconds: 2505600
  /** 30 days: a master forgets a node row silent this long (grid-src `registry.prune_stale_nodes`). */
  master_node_prune_seconds: 2592000
  [key: string]: unknown
}