# Status

A status's label in the current locale: `const label = useStatusLabel(); label("running")`.

- Registry name: `status` (`@candor/status`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/status

## Install

```bash
npx candor-ui add status
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/status`.
It brings in: locale.

## Functions

### useStatusLabel

```ts
useStatusLabel()
```

A status's label in the current locale: `const label = useStatusLabel(); label("running")`.

### isTerminal

```ts
isTerminal(status: RunStatus)
```

### runLiveness

```ts
runLiveness(run: { status: RunStatus; lastHeardAt?: Date | string | undefined; hostOffline?: HostOffline | undefined }, now: number | null, staleAfter = STALE_AFTER)
```

## Strings (`status`)

The fixed words, English by default. Override any of them under `status` in `<LocaleProvider strings={{ status: { … } }}>`; the table is exported as `statusStrings`.

- `idle`: Not started
- `queued`: Queued
- `running`: Running
- `waiting`: Needs you
- `blocked`: Blocked
- `succeeded`: Done
- `failed`: Failed
- `cancelled`: Cancelled
- `skipped`: Skipped

## Types

### RunStatus

The status vocabulary every Candor agent component shares. Components take plain data in these shapes rather than an SDK's message objects, so they work with your own LLM drivers, the Vercel AI SDK or anything else; adapters map an SDK's parts onto them.

```ts
| "idle" // not started | "queued" // accepted, waiting for a worker | "running" // an agent is working on it now | "waiting" // stopped to ask a person (approval, question) | "blocked" // can't start: something it depends on failed or is waiting | "succeeded" | "failed" | "cancelled" | "skipped"
```

### HostOffline

The machine or worker a run is on, when the app can't reach it.

```ts
{ /** The host's name as the app knows it: "Build runner 3", "Priya’s laptop". Left out, it's "The host". */ host?: string | undefined /** When the app lost contact. */ since?: string | undefined }
```

### RunLiveness

Whether a run can be called alive. "live": heard from recently, or the app doesn't track it. "stale": running, but nothing heard for longer than `staleAfter`, so it may have stopped. "offline": its host can't be reached. "unchecked": there's no clock yet (rendering on the server), so freshness isn't claimed either way. "settled": it has finished, so silence is expected. Only a running run goes stale: a queued or waiting one is quiet by design.

```ts
"live" | "stale" | "offline" | "unchecked" | "settled"
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.