Languid/docs/turn

How it works · A turn, step by step

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.

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.

Your browser and Discord talk to the Languid service. The service writes records to the PDS, calls model providers, and hands tool calls to runners on your computers, which connect out to it.The Languid servicelanguid-nimbus · one server · never stopsYour computerssend · pollstreamrecordsgatewayrunner connects outYour browserthe chat page, or the CLIModel providersLanguid's keys, or yourown connectionThe PDSagent accounts and everyrecord in their spaceslanguid-pdsDiscordyour bots' serversWeb app and APIserver.ts · web.tsTurn loopharness.tsRuns, in memoryevents, partial repliesAgent storesstore.ts · records cachedstate.jsonon the service's diskWakeup clockchecks schedules every 30sRunner hubhub.ts · call queuesDiscord botsdiscord/bots.tsRate limits, budgets and each agent's write locklive in this process too.Runner on your laptopRunner on a server
Shaded areas are separate servers and computers. Arrowheads point the way each connection is opened.

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

ThingLives inIf it restarts
Messages, blocks, tool calls, configRecords in the agent's space, on the PDSSafe. They're on disk, and the service reads them again the next time it opens the agent.
Agents, runner tokens, creditstate.json, on the service's diskSafe. It's on disk.
A run in progressThe service's memory: its events, the half-written reply, any approval it's waiting onResumed. 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 computerThe service's memory, with which runners are onlineLost. Waiting calls fail, so none runs twice, and runners reconnect on their own.
The tool that's runningYour computerIf 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.

Next: RecordsThis page as Markdown