# Run log

Every agent run, one line each, newest first: status, what it was, who ran it, where, when, how long and what it cost. Filter to failures or what's running. A cost or duration not yet measured shows a dash.

- Registry name: `run-log` (`@candor/run-log`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/run-log

## Install

```bash
npx candor-ui add run-log
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/run-log`.
It brings in: agent-avatar, chat, locale, relative-time, scale, status, status-dot, terms, utils.

## Example

```tsx
"use client"

import { RunLog, type RunLogEntry } from "@/components/run-log"
import type { AgentIdentity } from "@/lib/chat"

const dev: AgentIdentity = { id: "a-dev", name: "Dev agent", role: "dev" }
const qa: AgentIdentity = { id: "a-qa", name: "QA agent", role: "qa" }
const keel: AgentIdentity = { id: "a-keel", name: "Keel", role: "orchestrator" }

const ago = (minutes: number) => new Date(Date.now() - minutes * 60_000).toISOString()

const runs: RunLogEntry[] = [
  { id: "r1", title: "Add region to projects", agent: dev, environment: "Staging", status: "failed", startedAt: ago(48), duration: 431, cost: 2.37 },
  { id: "r2", title: "Audit API rate limits", agent: qa, environment: "Staging", status: "running", startedAt: ago(12) },
  { id: "r3", title: "Clean up stale flags", agent: keel, environment: "Production", status: "waiting", startedAt: ago(95) },
  { id: "r4", title: "Weekly schema hygiene report", agent: keel, environment: "Production", status: "succeeded", startedAt: ago(60 * 9), duration: 96, cost: 0.31 },
]

export default function Example() {
  return <RunLog className="max-w-3xl" runs={runs} onOpen={() => {}} />
}
```

## <RunLog>

Props:

- `runs: RunLogEntry[]`: The runs to list; shown newest first.
- `onOpen?: ((id: string) => void) | undefined`: Makes each run's name a button; called with the run's id.
- `className?: string | undefined`

## Strings (`runLog`)

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

- `runs`: Runs
- `show`: Show
- `all`: All
- `failed`: Failed
- `running`: Running
- `run`: Run
- `agent`: Agent
- `started`: Started
- `took`: Took
- `cost`: Cost
- `noneMatch`: No runs match.

## Types

### RunLogEntry

```ts
{ id: string title: string agent: AgentIdentity /** Where it ran, as shown. */ environment: string status: RunStatus startedAt: string /** Seconds; absent while running. */ duration?: number | undefined /** USD; absent until measured. */ cost?: number | undefined }
```

## 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`.