# A turn, step by step

What happens between pressing Send and reading the answer: which server does each part, and what gets written where. It follows one chat message on the hosted service, at languid.ai. Here, a **server** is one of Languid's own, and a **computer** is one of yours.

## The servers

Languid is two servers, the runners on your computers, and a few outside services.

- **The service** (`languid-nimbus` on Fly) is one Node process on one server. It does nearly all the work: it serves the web app and the API, runs every turn, talks to the models, keeps the queues of tool calls, and runs the Discord bots and the wakeup clock.
- **The PDS** (`languid-pds`, at `pds.languid.ai`) is a standard atproto PDS. It holds the agents' accounts and every record in their spaces. See [Records](/docs/records).
- **Runners** run on your computers, or in a cloud sandbox. A runner connects out to the service, picks up the tool calls meant for it, and sends back the results. See [Computers](/docs/computers).
- **Model providers** (Together, OpenRouter, Anthropic, OpenAI and others) answer model calls, on Languid's keys or on your own connection. See [Models](/docs/models).

## Step by step

You ask an agent which tests fail. It runs one `bash` command on your laptop, then answers. Steps 6 to 12 repeat for every tool call, up to 40 model calls in one turn.

<!-- turn-map -->

### You press Send

The chat page sends your text to the service (`POST /agents/<handle>/send`), with the thread, the computer picked in the page, and whether to ask before each change or allow them all. The service checks your browser session and your request limits first.

### The service opens the agent

Only the first time since the service started. It finds the agent in its own `state.json` (the agent's account, owner and space), logs in to the PDS as the agent, and loads every record in the agent's space into memory. From then on it updates that copy as it writes, and each turn reads from memory.

### Checks, before anything is saved

The service needs to know the agent's model and hold credentials for its provider: Languid's key for its two hosted models, or your ChatGPT plan, Grok plan, Claude key or OpenRouter key. A call on Languid's key needs credit left, and you can have at most 8 runs going at once. If any check fails, the service refuses the message and writes nothing.

### Your message becomes a record

The service writes your message to the agent's space as an `ai.languid.conversation.message` record, before any model sees it. If the thread already has a run going, your message joins it. Otherwise the service starts a new run in memory, answers the browser with its id, and does the rest in the background.

### The page starts polling

Twice a second the page asks for the run's new events (`GET runs/<id>?since=n`), along with the reply written so far. Runs live in the service's memory. If the service restarts, it notes the runs it cut off and resumes them when it starts again, and everything already written stays in the thread.

### Building the prompt

The turn loop rebuilds the whole conversation from the records in memory: the system prompt, pinned blocks, the list of other blocks, the latest summary, then the messages. If that would come close to the model's context window, it compacts first: one extra model call writes an `ai.languid.conversation.summary` record, which stands in for the older messages. That call sends the same context the turn would, plus a request for the summary, so the provider can answer it from its prompt cache. A long thread that has been quiet for a few minutes is compacted the same way (trigger `idle`), before its cache expires.

### Calling the model

The service streams a request to the provider. Text comes back in pieces and is added to the run's partial reply, which is what the page shows as it polls. If the provider is overloaded or rate limited, the service waits and tries again, after 2, 8, 20 and 60 seconds.

### The model asks for a tool

Here it asks to run `bash`. Before the call runs, the service writes the model's message and an `ai.languid.tool.call` record naming the computer, so the call is on record even if the run dies halfway. Memory block edits and `xrpc` scripts run in the service itself, with block edits one at a time per agent. Only the computer tools (read, bash, edit, write, grep, find and ls) go to a runner.

### Asking you first

Your rules for that computer decide first: a tool or command you always allow just runs, and one you never allow is refused. Otherwise, if the page is set to ask, the run adds an approval to its events, the page shows **Allow** and **Deny**, and your answer goes back to the service. The call waits, and is denied if no one answers in time.

### Handing the call to your computer

Your runner keeps a request open to the service, for up to 25 seconds at a time, and then opens another. The service puts the call in that computer's queue and answers the waiting request with it straight away. A runner that hasn't checked in for 45 seconds counts as offline, and the call fails; so does a call no runner picks up within 30 seconds. A sleeping cloud sandbox is the exception: the service starts it, and the call waits for its runner. The service hands out each call once at most, since a shell command may already have run.

### Your computer runs it

The runner runs the command with pi's own tool code, in the session's working directory, and posts the output back to the service. A long shell command can become a background job, which reports back when it ends.

### Recorded, and round again

The service writes an `ai.languid.tool.result` record, rebuilds the prompt with the result in it, and calls the model again.

### The answer

This time the model replies with text and no tool calls. The service writes that message. With no message of yours left waiting for an answer, the run ends and frees its slot, and the page's next poll settles. If you sent another message while the agent was working, the same run answers it before it ends.

> Messages from Discord and scheduled wakeups take the same path. The Discord bots and the wakeup clock start an ordinary run in the service, and from the message being recorded onwards, the turn is the same.

## Where each thing lives

| Thing | Lives in | If it restarts |
| --- | --- | --- |
| Messages, blocks, tool calls, config | Records in the agent's space, on the PDS | Safe. They're on disk, and the service reads them again the next time it opens the agent. |
| Agents, runner tokens, credit | `state.json`, on the service's disk | Safe. It's on disk. |
| A run in progress | The service's memory: its events, the half-written reply, any approval it's waiting on | Resumed. The service notes the run before it stops and picks it up when it starts again. Whatever was already recorded stays in the thread. |
| Calls waiting for a computer | The service's memory, with which runners are online | Lost. Waiting calls fail, so none runs twice, and runners reconnect on their own. |
| The tool that's running | Your computer | If the runner restarts mid-call, the call fails and says it may or may not have run. |

What has to stay running on Languid's servers is in [Self-host](/docs/self-host#what-has-to-stay-running).
