# Concepts

The terms that the nanocode guides and API pages use, each defined once.

## Overview

A host builds one runtime, spawns agents from it, and sends each agent prompts. Each prompt runs as a turn, which streams events and calls tools. A session store journals every turn so a later process can reopen the session.

```mermaid
flowchart LR
  host[Host] --> runtime[Runtime]
  runtime --> agent[Agent and session]
  agent --> turn[Turn]
  turn --> events[/Events/]
  turn --> harness[Harness: Codex or Claude]
  harness --> tools[Tools]
  tools --> codemode[Code Mode cell]
  codemode --> hand[Hand]
  agent --> subagent[Subagents]
  agent --> store[(Session store)]
```

## Runtime and Harness

* **Runtime:** A `Nanocode` value from `Nanocode::builder()`. It owns the harnesses, tools, Code Mode, subagents, and session store that every agent it spawns shares. In TypeScript, `AgentRuntime` plays this role for one session scope.
* **Harness:** The provider driver for a turn, also called the backend. The Codex harness (`Codex`) talks to OpenAI Responses, and the Claude harness (`Claude`) talks to Anthropic Messages. Each sends its provider's own system prompt and tools.
* **Model:** A model of one harness, such as `Model::Luna` (`gpt-6-luna`) or `ClaudeModel::Haiku55` (`claude-haiku-5-5`). A model of the other harness is a configuration error.
* **Thinking:** The reasoning effort: `none`, `low`, `medium`, `high`, `xhigh`, or `max`. Each model accepts a subset and has its own default.

```rust
// Select the harness and model for one agent
let (agent, events) = runtime
    .spawn()
    .backend::<Claude>()
    .model(ClaudeModel::Haiku55)
    .build()
    .await?;
```

## Agents and Turns

* **Agent:** A handle to one conversation, returned with its event stream by `spawn().build()` or `open_session(id)`.
* **Session:** The durable record behind an agent, named by a UUIDv7 session ID. `agent.session_id()` returns it.
* **Turn:** One prompt and the model steps and tool calls that answer it. `agent.prompt(...)` resolves when the turn is accepted, and awaiting the `Turn` resolves with its `TurnResult`.
* **Request ID:** A caller-chosen ID for a turn. A prompt sent again with the same request ID returns the same turn instead of running a second one.

```rust
// Name the turn, so a retry after a crash does not repeat it
let turn = agent
    .prompt(
        PromptRequest::new("Summarize the log.")
            .request_id("summary-1"),
    )
    .await?;
```

## Events

An event has a kind and a JSON payload. Kinds include `input.accepted`, `assistant.delta`, `assistant.message`, `reasoning.summary.delta`, `tool.call`, `tool.result`, `run.completed`, and `run.failed`. Rust hosts read them from `AgentEvents` or the `Turn` stream. TypeScript hosts read logged events with `page` and `published`.

```rust
// Print the JSON payload of each reply delta
while let Some(event) = events.recv().await {
    if matches!(event.kind, AgentEventKind::AssistantDelta) {
        println!("{}", event.payload.get());
    }
}
```

## Tools

* **Built-in tools:** Each harness's own shell, file, and edit tools, plus web search and image generation where the provider serves them. `Tools::builder().without_defaults()` turns them off.
* **Rust tools:** A function marked with `#[tool]`, registered with `ToolsBuilder::tool`.
* **`FunctionTool`:** A tool declared at run time with a name, a description, and JSON Schema parameters. Its calls run through a `FunctionHandler`.
* **Host tools:** A TypeScript host's `HostTool` declarations, which run through `tools.call`. nanocode-wasm registers them as `FunctionTool` values.
* **MCP tools:** Tools of MCP servers over stdio or Streamable HTTP, added with `nanocode::tools::mcp::Mcp::builder()` and `tool_provider`.

```rust
// Register one Rust tool beside the defaults
let tools = Tools::builder().tool(quotient).build()?;
```

## Code Mode

Code Mode gives the model an `exec` tool that runs a JavaScript cell. A cell calls tools as `tools.name(args)`, can run calls in parallel, and keeps values for later cells. Every registered tool is offered directly and inside Code Mode.

```ts
// A cell the model writes: two tool calls in parallel
const [half, zero] = await Promise.allSettled([
  tools.quotient({ a: 42, b: 2 }),
  tools.quotient({ a: 1, b: 0 }),
])
```

## Subagents

A subagent is a child agent that a parent spawns through delegation tools. Each child has its own model, thinking level, and optional typed `output_contract`, which the runtime validates before the parent accepts the result. `without_subagents()` removes the delegation tools.

```rust
// Build a runtime without delegation tools
let runtime = Nanocode::builder()
    .without_subagents()
    .build_async()
    .await?;
```

## Durability

* **Session store:** A `SessionStore` that journals turns, model steps, and tool receipts. Native hosts default to a `JsonlStore` at `~/.nanocode/sessions.jsonl`. `MemoryStore`, SQLite, and Postgres stores are also available, and WebAssembly hosts supply a `SqlHost`.
* **Receipt:** The recorded output of a committed tool call. On reopen, a receipt replays its output. A call without a committed receipt reports an unknown outcome and does not run again.
* **Checkpoint:** A `SessionCheckpoint` from `agent.checkpoint()`, holding the session ID, model, and thinking level. `runtime.resume(checkpoint)` restores the agent from it.

```rust
// Journal sessions to one shared store
let runtime = Nanocode::builder()
    .durability(store.clone())
    .build_async()
    .await?;
```

## Brain and Hand

The brain is the process that runs inference, subagents, and durability. A hand is a machine that runs the brain's Code Mode cells and tools in its own directory, over a WebSocket that either side can dial. A tool call with `hand: "name"` runs on that hand.

```bash
# Make this machine a hand for a brain listening on port 9000
nc hand ws://127.0.0.1:9000 --name build-box
```

## More

- [Rust Tools](/docs/guides/tools): Register #[tool] functions and FunctionTool values.

- [Code Mode](/docs/guides/code-mode): Let the model script tools in JavaScript cells.

- [Durability](/docs/guides/durability): Journal turns and reopen sessions by ID.

- [Remote Hands](/docs/guides/remote-hands): Run Code Mode cells on other machines.