Open source agent hosting on the AT Protocol
languid docs development.md
50 kB · 371 lines
Markdown

Developing Languid #

Running Languid from a checkout against a local dev stack, and the reference for its CLI, service and runner. To use Languid, read the docs. To run your own service, read Self-host.

Quick start #

Requires Node 22.18+, pnpm, and Docker. The package scripts work with bun run, pnpm or npm run (with npm, put -- before flags), and all of them run node src/cli.ts <command>.

git clone https://tangled.org/cameron.stream/languid languid && cd languid
pnpm install
(cd dev/plc && npm ci)
./dev/stack up                       # Spaces-alpha PDS on :2583, private PLC on :2582

bun run init                         # owner account ($USER.<PDS handle domain>; or: bun run init alice.test)
bun run agent create scout           # agent account, and its space under the owner's own DID
# or pick a model: --model openrouter/anthropic/claude-sonnet-5.5

bun run languid serve                 # terminal 1: the languid service (owns the agent's records)
bun run languid computer invite       # prints a one-time join command; run it in terminal 2:
bun run languid computer join http://127.0.0.1:2590 <code>  # this computer runs scout's tools
languid chat scout                    # terminal 3: talk to it in pi (pi-languid extension); later just `languid`

bun run records scout                # see its records in the PDS
bun run records scout ai.languid.tool.call --json
bun run records scout --public
bun run blocks scout

bun run languid run scout "summarize your notes"   # one headless run, no pi (new thread; -c continues the latest)
bun run languid run scout -c <<< "and then?"        # prompt on stdin avoids shell quoting
bun run languid models sonnet                         # list models (provider/id)
bun run agent model scout openrouter/anthropic/claude-sonnet-5.5   # switch (or /model in pi)

Inference is bring-your-own-key through pi-ai. Keys come from the environment (ANTHROPIC_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, …) or from pi's /login, including subscription logins such as xAI's (stored in ~/.pi/agent/auth.json, which bun run pi uses). The default model for new agents is anthropic/claude-haiku-5-5.

Models checked against the full loop with node scripts/model-check.ts <provider/model> ... (tool call through a runner, a block edit, recall from records), Nov 2026, prices in $ per million input/output tokens:

model price notes
anthropic/claude-haiku-5-5 (or openrouter/anthropic/claude-haiku-5.5) 0.10 / 0.50 fewest steps, fastest
openrouter/qwen/qwen3.7-flash 0.03 / 0.13 cheapest that passed
openrouter/deepseek/deepseek-v4-flash 0.09 / 0.18
xai/grok-4.7 subscription via xAI /login in pi; newest Grok, as few steps as Haiku

Headless runs use the same credentials as pi. src/models.ts builds pi's ModelRuntime, which reads pi's auth.json (~/.pi/agent, or $PI_CODING_AGENT_DIR) and falls back to environment keys. Refreshing an OAuth token takes pi's file lock, so a running pi and languid never both rotate the same token. Log in once with pi (/login, or pi auth login xai) and both can use it.

Bring your own ChatGPT plan: sign in on the website, then choose Connect or manage ChatGPT on your account page (/settings/models). Languid shows a device code to approve at OpenAI; device-code authorization may need enabling in your ChatGPT security settings. After approval, choose an openai-codex model in your agent's model menu. These calls use your eligible subscription and its limits, not your Languid dollar budget. Other owners cannot use your connection. The service stores credentials under model-auth/<SHA-256 of owner DID>/auth.json in its home directory (private directories, 0600 files), with pi's locked token refresh; treat that directory as a secret when backing up. Disconnect removes the local credentials, but does not revoke access at OpenAI or stop in-flight requests. The installation owner can still use their existing pi Codex login; invited owners never inherit it.

Talking to an agent: pi-languid #

Agents are used through pi with the extension in packages/pi-languid. languid chat scout (or bun run languid chat scout) runs pi -e <checkout>/packages/pi-languid --languid scout in the directory you're in, using the pi version pinned in this repo. With languid on your PATH (a script that runs node <checkout>/src/cli.ts "$@"), it works from any directory; a bare languid opens the agent you used last. With none used yet, it opens your only agent, or asks which one, or, if you have none, offers to make one (a script gets the same as a hint instead). At a terminal, bare languid also does whatever the first time still needs: if you aren't signed in, or your sign-in has expired, it runs languid login first, which offers to set up this computer. Tools run on the computer you start it on, once that computer is set up (languid computer setup); --computer <name> picks another. If it's set up but the agent can't use it yet (an agent made after the setup), chat asks whether to let it, and on yes does what languid computer attach does; a script gets that command as a hint. Options after the agent go to pi (languid chat scout -c continues this directory's last session). While pi is attached:

  • before every request, pi fetches the context from the service (ai.languid.agent.getContext), which compiles it from the agent's records. pi's own session file is just a local cache.
  • every user turn, assistant turn and tool result is written back as records.
  • tools are the agent's block tools, xrpc (scripts that look up records; see Scripts: the xrpc tool), and pi's own built-ins (read, bash, edit, write, grep, find, ls), with one extra optional argument, computer. Every tool also takes a required call_intention, listed first: a few words saying what the call is for, which the web chat, languid run and pi's approval question show as the call's label (the same field Identity uses). A call without one is refused before anything runs or anyone is asked; the field is removed before the tool's implementation sees its arguments. The service records each call, and the runner on that computer executes it with pi's implementation, so pi shows its usual diffs and output. Without computer, a call runs on the session's computer; relative paths resolve in pi's directory when that computer is the one pi runs on, and in home on other computers. Calls to different computers run at the same time. Without --languid, the extension's built-ins run locally like pi's.
  • pi asks before each bash, edit or write call; read, grep, find and ls run without asking. The question offers: yes once, yes for that tool on that computer for this session, always yes for that tool on that computer, or no. "Always" is saved in the agent's space (an ai.languid.computer.permissions record), shared with the web chat's "Always allow", so it holds wherever you use the agent. /approvals lists the rules and removes them. Rules older versions of pi saved in ~/.languid/state.json move into the agent's space the next time pi attaches. --languid-yes skips every question. Print mode (-p) has no way to ask, so it denies those calls unless --languid-yes is given.
  • model calls go through the service (pi provider languid): the service calls the model named in the agent's ai.languid.agent.config record with its own credentials, so pi needs no model keys. /model lists the service's models as languid/<provider>/<id>; choosing one saves it to the record. Choosing a non-languid model is refused.
  • each pi session gets its own languid thread; resuming the session (--continue, /resume) continues that thread.
  • /threads lists the agent's threads from the service, most recently active first, and switches to the one you pick, including threads started on another computer. It opens a new pi session seeded with that thread's compiled transcript. /threads new starts a new thread. (pi's /resume only knows this computer's session files.)
  • /languid shows the agent, space, thread and computers; /languid blocks shows its blocks.

Steering, Esc to stop, model selection and the terminal UI are pi's own.

languid run has no one to ask, so it denies bash, edit and write unless you pass --yes. When languid serve is running, the run happens inside the service (ai.languid.agent.run), and the CLI streams its events. Otherwise it runs in-process, without computer tools (runners connect to the service).

Local credentials (account passwords, runner tokens) are kept in ~/.languid/state.json (mode 0600; override the location with LANGUID_HOME). Secrets never go in records.

Installing the CLI #

curl -fsSL https://languid.ai/install | sh

The service serves its own install script at /install (scripts/install.sh, with the service's URL and where the code is filled in). It needs Node 22.18 or newer, curl and tar, and nothing else: it downloads a tarball of main (Tangled serves one at /archive/main; another service sets LANGUID_SOURCE_TARBALL), unpacks it into ~/.languid/app, installs its dependencies with the pnpm pinned in package.json (through npx, so pnpm needn't be installed; Node 25 dropped corepack), and writes a languid command into ~/.local/bin, adding that directory to PATH in your shell's rc file if it isn't on it. A failed install leaves the previous one in place. On a first install from a terminal it then runs languid login against that service (LANGUID_NO_LOGIN=1 skips it). Running it again updates the code, and restarts this computer's runner when it runs from that install. LANGUID_APP_DIR, LANGUID_BIN_DIR and LANGUID_TARBALL change where it puts things and what it fetches.

Signing in #

A service that others can reach identifies its owners by their atproto account:

languid login                                  # languid.ai; prints a link and a code, and opens the link
languid login you.example.com --url https://<service>   # another service, or a named account
languid whoami
languid account list                           # every account signed in here; * marks the current one
languid account use bob.example.com            # switch (alone: the other one, or asks which)
languid --as bob.example.com chat              # one command as another account, without switching
languid logout [handle]

login signs in to languid.ai unless --url (or LANGUID_SERVER, or the service already in state.json) names another. It needs no handle: the browser says who. A browser already signed in to the service confirms the code as that account, with no trip to your PDS (it also offers another account); otherwise the page asks for your handle. Naming a handle (languid login you.example.com) skips the question, and a browser signed in as someone else goes to your PDS. Otherwise login opens the service's sign-in page, which sends you to your PDS (OAuth). The grant proves who you are and lets the service create and manage your agent spaces, which belong to your own account; it gives no access to your public repo or to any other space. Back on the service, a page shows a code; approve only if your terminal shows the same one. That step is what stops a sign-in link someone sends you from signing their terminal in as you. The terminal then gets a session token (30 days), kept in state.json; the service keeps only its hash. Unless this computer already runs tools for that service, login then asks whether to set it up for your agents, and on yes does what languid computer setup does (see Computers); without a terminal to ask in, it prints that command instead.

Signing in to another account keeps the one before, so languid account use switches back without a browser. Each account remembers the agent it opens. A lapsed account is marked in account list, and account use offers to sign in to it again. logout alone ends the current account's sign-in; logout <handle> ends another's. An account can be named by its full handle, its DID, or the handle's first label (bob for bob.example.com). The computer's runner still belongs to the account that set it up (one runner per languid home; see Computers), so an agent of another account runs tools here only from a home of its own.

  • Every call is scoped to the signed-in owner: agents, threads, runs and computers of other owners are reported as not found.
  • Sign-in is invite-only: the installation owner, owners who signed up with an invite (see Inviting owners), owners of existing agents, and DIDs in allowedDids in the service's state.json.
  • Authorization servers must be able to fetch the service's client metadata, so the service's URL (--url / LANGUID_URL) has to be HTTPS on port 443. A loopback URL (http://127.0.0.1:2590) also works, for development. Anything else (a tailnet http:// address) gets no sign-in, and the service says so at startup.
  • The installation's own token (LANGUID_SERVER_TOKEN, or generated by languid serve) still works and acts as the installation owner. Clients on the service host use it without signing in.
  • When the service's URL is public (HTTPS, so sign-in is on, and not loopback), that token is accepted only from the service's host and its tailnet (100.64.0.0/10, fd7a:115c:a1e0::/48); everyone else signs in. It's decided by the connection's own address, not a header. A request that carries the proxy's client-address header (LANGUID_CLIENT_IP_HEADER) came through the proxy, so it never counts as local. If you put a proxy on the service's own host, set that header, or the proxy's traffic all looks local.
  • On the dev stack, start the service with LANGUID_PLC=http://127.0.0.1:2582 so it resolves DIDs in the private PLC.

In a browser #

The service's own URL serves a landing page at /, with a sign-in form. Signing in there goes through your PDS the same way, with no code to confirm, because the browser that starts the sign-in is the one that finishes it. Back on /, you see who you're signed in as, your agents, and the commands for a terminal: languid login, languid computer setup and languid chat. Sign out from the same page.

Each agent on that page links to its chat, /agents/<name>: its threads (most recently active first, the latest one open), and a box to talk in. A message starts a service-side run, the same as languid run, sent via: web; the page polls it and shows the reply as it streams, with each tool call and its result. Each call is labeled by its call_intention; the approval question shows it too, above the command itself, since it's the agent's own description. Before a bash, edit or write call, the run stops and asks in the page, and the call waits until you allow or deny it (denied after 5 minutes without an answer). "Permissions" (shown once you have a computer) switches that to "Allow all", the same as languid run --yes: those calls run without asking, and the pill turns amber while it's set. It applies from the next message, never to a run already going, and is remembered in the browser, per agent. A question about a call on a named computer also offers "Always allow": it allows the call, and from then on that tool runs on that computer for that agent without asking, in later runs, in languid run without --yes, and for any other call in the same run already waiting on it. The rules are listed under "Permissions", where "Ask again" removes one. They're kept in the agent's space, one ai.languid.computer.permissions record per computer, and pi goes by the same rules. Removing a computer (languid computer remove) removes its rules too. While a run goes, a line above the message box says what it's doing (the running call's intention, or that it's writing) or that it's waiting for you. stop ends the run and denies anything waiting. "Model" lists the models this service can call, by provider, with their prices; picking one saves it to the agent's config record, the same as pi's /model, so pi and languid run use it too. "Works on" picks the computer the agent works on, the same as --computer: its computer tools run there unless it names another, starting in that computer's home directory. "Any computer" lets the service place each call; the choice is remembered in the browser, per agent. Reloading picks a run back up, including a pending question. Calls with no computer named run on any connected computer of yours.

  • The browser's session is a cookie (languid_session: HttpOnly, SameSite=Lax, Secure on HTTPS, 30 days). It opens the service's pages and the chat's own calls, never XRPC methods: those still need a bearer token.
  • The chat's calls that change anything (send, approve, stop) must carry this service's Origin and a JSON body, which a form on another site can't send. The chat page is the only page that runs a script (/chat.js, no inline scripts, script-src 'self'), and the script puts everything from the service into the page as text, never HTML.
  • The same invite list applies. Someone not on it sees a page with their DID to send to whoever runs the service.
  • Without a sign-in-capable URL (see above), / still shows the landing page, saying why sign-in is off.
  • Sign-in works only on the service's own origin. www.<host> redirects there; under any other name (the tailnet address, say) / links to the origin instead of showing the form.
  • With a public URL, languid serve gives clients on its own computer a direct address (http://127.0.0.1:<port> when it listens everywhere) in state.json, since the installation token isn't accepted through the proxy. Invites print the service's public address for the join command.

Once signed in, languid agent create <name> asks the service for an agent: an account for it on the service's PDS, and its space, which the service creates as you, on your PDS, under your DID (at://<your DID>/space/ai.languid.space.agent/<name>). Your PDS has to run atproto Spaces. A signed-in owner can have 5 agents (LANGUID_MAX_AGENTS_PER_OWNER). The service keeps your OAuth session (in oauth/sessions.json beside its state) for this and gives it up when your last session signs out; if it has lapsed, creating an agent asks you to sign in again.

For any of this to work, authorization servers must be able to resolve the space type ai.languid.space.agent: languid admin publish-lexicon (on the service host) publishes its declaration from the installation owner's repo and prints the DNS record that points at it (_lexicon.space.languid.ai), or for the dev PDS, the PDS_LEXICON_AUTHORITY_DID line for .dev/pds.env. Without it a PDS refuses the sign-in ("Unable to retrieve space declarations"), and caches that refusal for five minutes.

Not there yet: per-owner model keys (owners use the service's, within their budget). Agent names are unique per service, not per owner (computer names are per owner: two owners can each have a laptop). A signed-in owner's public repo gets no agent.link record, since the grant doesn't cover it. Not tried: an owner whose PDS is a different one from the service's.

Inviting owners #

The installation owner invites people. Each invite is a one-time link to the service's /signup page, where the invitee picks a handle and a password. The service makes them an account on its own PDS (<handle>.languid.ai on the hosted one) and adds them to the owners who may sign in. Then they sign in like anyone else.

languid admin invite-owner --budget 10 --model openrouter/deepseek/deepseek-v4-flash   # prints the link; --days 7 by default, --uses 20 for a room
languid admin owners                      # who signed up, their agents, and what their model calls have cost
languid admin budget alice.languid.ai 20  # change a budget; `none` removes it
  • The service keeps only a hash of each invite code. A link works once; if making the account fails (the handle is taken, the PDS is down), the link still works.
  • The password goes from the sign-up form to the PDS and isn't kept by the service. The PDS has no email set up, so there's no reset by email; com.atproto.admin.updateAccountPassword on the PDS is the way back in.
  • --model is the model the owner's new agents get when they don't name one.
  • admin prune never deletes an invited owner's account.

Budgets #

Model calls run on the service's credentials. An owner with a budget (in US dollars) can spend that much: every model call their agents make (pi turns, languid run, compaction summaries) is refused once it's spent, with 402 BudgetExhausted, and each call's cost is added when it ends. The cost is pi-ai's: the provider's billed cost when it reports one (OpenRouter does), otherwise the catalog price. A model with no price (a subscription login) can't be metered, so owners with a budget can't use one. The installation owner, and owners invited without --budget, have no limit. Owners see what's left on the service's page.

Rate limits #

The service limits requests with token buckets kept in memory (src/limits.ts). Over a limit, it answers 429 with Retry-After. The defaults are well above what languid's own clients do:

what keyed by burst per minute
starting a sign-in (CLI or browser) client address 10 2
other sign-in steps (CLI poll, browser redirects, approval) client address 60 60
computer registration (invite code) client address 10 2
pages (landing, docs, chat), and chat calls without a session client address 60 120
wrong tokens (bearer or runner); when used up, the address gets 429s for everything until it refills client address 30 6
every XRPC call, and the chat's calls from a signed-in browser owner DID 300 600
model calls and runs (they spend the service's model credentials) owner DID 60 60
creating agents (each is a permanent account and DID) owner DID 10 2
runner polls and results runner 300 600

Owners also get at most 8 model streams at once. Requests without a token don't count as wrong tokens, health checks and /oauth/client-metadata.json aren't limited, and IPv6 addresses are grouped by /64.

  • Behind a proxy, every request comes from the proxy's address. Set LANGUID_CLIENT_IP_HEADER to the header the proxy puts the client's address in (fly-client-ip on Fly). Only set it behind such a proxy: otherwise clients choose their own address. It also marks requests as proxied for the installation token (see "Signing in").
  • LANGUID_RATE_LIMITS=off turns the limits off.

Computers #

The service runs agents' computer tools (pi's read, bash, edit, write, grep, find, ls) on runners on your own computers. grep and find need rg and fd; pi downloads them on first use if they aren't installed. A runner only dials out: it long-polls the service over HTTPS for tool calls and posts the results back. So a computer needs no open port, no public address and no VPN, only a route to the service.

# your own computer, where the service is configured (state.json has its URL and the owner token):
languid computer setup                            # registers this computer and starts its runner now and at login

# a computer that shouldn't hold the owner token: invite it from one that does
bun run languid computer invite --agent scout     # prints a one-time join command (15 min)

# on the new computer (with languid checked out and installed)
bun run languid computer join https://<service> <code> [--name laptop]
bun run languid computer run                      # later: start its runner again

bun run languid computer list                     # which runners are connected
languid computer attach laptop --agent scout,blip  # let existing agents use this computer
bun run languid computer remove laptop            # revoke it

# pick the computer an agent works on, per session or run
bun run pi scout --computer fly
bun run languid run scout --computer fly "check disk space"

computer setup starts the runner now and at login: a LaunchAgent (ai.languid.runner) on macOS, or a systemd user unit (languid-runner.service) on Linux. Both restart it after failures, except when its token was revoked. On macOS, run setup from a logged-in desktop session; logs are in ~/Library/Logs/languid/runner.log. Stop it with launchctl bootout gui/$(id -u)/ai.languid.runner; run setup again to restart it. On systems without either service manager, keep languid computer run going yourself. Each languid home (LANGUID_HOME) holds one sign-in and one computer registration, and gets its own runner: the default home uses the names above, and any other home adds a suffix from its path (ai.languid.runner.<id>, languid-runner-<id>.service, runner-<id>.log), so two accounts can run tools on the same computer from two homes. The old languid computer commands remain supported as aliases; stored data and API field names are unchanged.

To grant an agent created later access to an already-registered computer, use languid computer attach <name> --agent <agent[,agent…]>. Both the computer and every named agent must belong to you. This is safe to repeat, preserves existing assignments, and doesn't change the runner token or require a restart. It grants access to run tools on that computer; it does not automatically attach future agents.

For other computers to reach a service, either run languid serve --tailnet, which listens only on this node's Tailscale address so runners on your tailnet dial out to it, or give it a public HTTPS address (--host 0.0.0.0 --url https://… behind TLS). With a public address, owners sign in and the installation token works only from the host and its tailnet (see Signing in).

With --computer <name>, the agent's computer tools run on that computer unless the model names another, and its context says which computer it's on. An unknown name is rejected and the known ones are listed. Offline computers are marked [offline] in the agent's context, and calls to them fail at once.

How it's secured:

  • Joining. The invite code (96 random bits) proves you sent it, expires, and works once. The service writes the computer's ai.languid.computer.node record into each invited agent's space and returns a runner token. The computer keeps the token; the service keeps only its SHA-256.
  • Calls. Runner endpoints (ai.languid.runner.poll, ai.languid.runner.result) accept only a runner token, and a runner gets only the calls assigned to its computer. The owner's token doesn't work there, and a runner token doesn't work anywhere else. languid computer remove revokes the token, and the runner exits.
  • Background jobs. bash runs each command as a job (src/jobs.ts). If it finishes within 10s, the call returns its output as usual. Otherwise the call returns the output so far and a job id, and the command keeps running with no time limit (unless the call passed timeout). The service records an ai.languid.tool.job record, and the agent's context lists recent jobs in <jobs>. The job's shell writes its output to ~/.languid/jobs/<id>/output.log and its exit code to a file. Because the runner doesn't write either one, a job survives the runner restarting. The runner reports each job's end (ai.languid.runner.jobDone) once it can reach the service, with the last 50 lines of output. job_stop kills a job's whole process group. At most 32 jobs run at once per computer, and finished jobs' logs are deleted after 7 days. By default it sees the result in <jobs> on its next turn. languid wakeups jobs <agent> on opts into a separate, bounded tool-free review when a recorded job ends; see wakeups.
  • At most once. A call the runner loses (it restarted, or a poll response never arrived) fails with an error saying so, rather than being sent again, since a shell command may already have run. Calls an online runner doesn't pick up within 30s, or doesn't finish within 660s, fail; the runner is told to kill a call that timed out.

Permissions #

What an agent may do without asking is set on its settings page (/agents/<name>/settings) or from the terminal, and both change the same records:

languid permissions scout                                 # every rule, per computer, plus record writes and script rules
languid permissions tool scout laptop edit allow          # bash, edit, write: ask (default), allow or deny
languid permissions command scout laptop allow git status # a bash command, by its first words, that runs without asking
languid permissions command scout laptop deny rm -rf      # one it may never run, even under "Allow all"
languid permissions write scout app.bsky.feed.post --ask  # let scripts write a collection, asking you first
languid permissions policy scout rules.json               # replace the script rules (print them without a file; --default resets)

Anything no rule covers asks you first, in the web chat or on Discord. See src/permissions.ts for how commands are matched.

Automated reviews #

languid wakeups add <agent> --at <ISO-time> [--every <seconds>] <prompt…> creates a record-backed schedule. languid wakeups jobs <agent> on opts into reviews of completed background jobs. Each wakeup gets one bounded, tool-free model response in its own thread; pending work is recovered from records after restart. See wakeups for commands, ATProto records, and limits.

How it works #

 owner ──▶ pi + pi-languid ─┐            ┌──▶ model (pi-ai)
           Harness (headless) ─▶ AgentStore
                                 │  ▲
                   space records │  │ compile context every request
                (blocks, msgs,   ▼  │
                 calls, results) PDS (Spaces)
                                 │
                                 └◀──HTTPS long poll── runner on owner's computer (pi's tools)
  • manager (src/manager.ts) creates the accounts on the installation's PDS: the owner (once per installation) and an account per agent. Each agent's space is at://<owner DID>/space/ai.languid.space.agent/<agent name>, a memberspace whose authority is the owner's own account, with the owner and agent as read/write members. The manager creates it as the owner: with the installation owner's password, or for an owner who signed in, through the OAuth session they granted (ai.languid.agent.create). There are no extra accounts. The manager also writes public agent.profile/agent.owner records on the agent, agent.link on the installation owner, and the initial config, blocks and tool definitions in the space.

    Older agents have a space under an account the installation made: one per owner (<owner>-spaces, in state.authorities), or before that one per agent (<name>-space, skey self). languid admin migrate-authority <agent> [--apply] moves one under its owner's DID (src/migrate.ts; installation owner's agents only): it copies every record of the agent's repo in the old space into the new one, keeping collection, rkey and value (rewriting any mention of the old space ref, such as the public agent.owner record's space), checks the counts and values per collection, and only then switches the agent's space in state.json. Old spaces and their authority accounts are left in place for deletion by hand. The alpha's own migration endpoints don't fit: their archives name the space they came from, so they move a space between hosts under the same ref, not to a new ref. The service reopens an agent's store when its space changes, but run the migration while the agent is idle.

  • store (src/store.ts) is the agent's state in its space, shared by every client. It loads the agent's records, compiles the model context from them, persists turns as records, and executes languid tools (block edits and xrpc scripts in-process, computer tools on a runner).

  • service (src/server.ts, languid serve) is the only reader and writer of agent records. Clients call it over XRPC with a bearer token that stands for an owner (a languid login session, or the installation's token), and see only that owner's agents; agent credentials never leave it. Sign-in is in src/oauth.ts; its pages are under /oauth/. It serializes writes per agent, since Spaces has no compare-and-swap.

    method type what
    ai.languid.agent.getContext query the next request's full transcript, compiled from records
    ai.languid.agent.describe query name, DID, space, model, blocks, computers, threads
    ai.languid.thread.create procedure new thread
    ai.languid.thread.list query the agent's threads, most recently active first, with message counts and a preview
    ai.languid.message.record procedure record a user/assistant/toolResult message; for assistant messages, returns each tool call's computer and whether it needs approval
    ai.languid.tool.execute procedure run a recorded call (block edits in the service, computer tools on runners); writes need approved: true
    ai.languid.agent.setModel procedure change the agent's model
    ai.languid.agent.run procedure start a run inside the service (prompt, optional thread or continue, approval: "ask", "allow" or "deny"; older clients pass approveWrites); returns {run, thread} right away
    ai.languid.agent.getRun query a run's status and its events (text, tool calls, results, and approval events with the request URI to answer) from since on
    ai.languid.approval.list query calls waiting for the owner's yes (thread optional): each open ai.languid.approval.request with its URI, tool, arguments, intention, computer, always-allow rule, expiry and the run waiting on it
    ai.languid.approval.answer procedure answer one (request URI, approved, optional always and via): writes the owner's ai.languid.tool.approval and wakes the run; NotWaiting (409) once it's answered, expired or nothing waits on it
    ai.languid.model.list query models the service has credentials for
    ai.languid.model.stream procedure one model call for an agent's thread, streamed as NDJSON pi-ai events; context from records, model from the config record, the service's keys
    ai.languid.thread.compact procedure summarize the thread's older messages now (pi's /compact); force: false only if over the threshold
    ai.languid.session.get / .delete query / procedure who the caller is and their agents; end a login session
    ai.languid.agent.create procedure create an agent for the caller: { name, model? }; its space is made under the caller's DID
    ai.languid.computer.invite procedure one-time join code (agents, ttlMinutes)
    ai.languid.computer.list query registered computers and whether their runners are connected
    ai.languid.computer.attach procedure attach a registered computer to existing agents (name, agents); same owner only
    ai.languid.computer.remove procedure delete a computer's records and revoke its runner token
    ai.languid.computer.register procedure a new computer joins with an invite code; returns its runner token (no owner token)
    ai.languid.runner.poll / .result procedure the runner's long poll for calls and its results (runner token)
    ai.languid.runner.jobDone procedure a background job ended; only the agent whose call started it, on that computer, accepts it (runner token)

    The ai.languid.computer.* methods above (not the permissions ones) were ai.languid.machine.* until Nov 15. The service still answers the old names, and still sends the old field names (machine, machines) alongside the new, for runners and CLIs installed before then.

    Service-side runs use pi's credentials on the service host, so subscription logins work there too. Each thread has one run at a time, and an agent's threads run at the same time, each holding one of the owner's concurrent model streams (TooManyRuns past the limit). A message sent into a thread that already has a run joins it (accepted: "queued", with the run to follow and where its events start): the run answers it at its next model request, or goes round again if it arrived during the last one. The message is a record before the call returns. A client can pass its own clientMessageId; sending the same one again returns the first message (accepted: "duplicate") instead of starting another turn. While a run is active, pi can't record into its thread (ThreadBusy). By default no one is asked, so bash, edit and write are denied; approval: "allow" (or approveWrites: true) runs them, and approval: "ask" waits for the owner to answer each over ai.languid.approval.answer, as the web chat does, denying it after 5 minutes. Edits to existing records (blocks, config) go through one exclusive lock in the store, so a run and a pi session can't overwrite each other's block edits.

  • client (src/client.ts) wraps those calls.

  • pi-languid (packages/pi-languid) attaches pi to an agent through the client (see above).

  • harness (src/harness.ts) runs the agent headlessly (languid run; later the hosted harness) on pi-agent-core's Agent. Each thread's turn has its own pi-agent-core Agent over the agent's one shared store, so threads run at the same time; pi-agent-core owns each loop: model calls, parallel tool execution and abort. languid owns the state. User messages are records before a turn sees them, and a turn runs while its thread ends in one, which is how a message sent mid-turn gets answered. Before every model call, prepareRequest rebuilds the transcript from records: system prompt, then in-context blocks in full, then other blocks by label, then computers, then the thread: its latest summary, if any, and the messages after it. The message_end listeners write each assistant turn (plus a tool.call per call) and tool result as records. Each assistant message records the newest message its context had (contextEnd), so a message that arrived while it was written goes after it in the transcript. Listeners are awaited, so a call's record exists before the call runs.

  • runner (src/runner.ts) executes computer tools on the computer it runs on, taking calls from the service's hub (src/hub.ts), which keeps a queue per computer. The store assigns each call to exactly one computer (pinned if the model or session names one, otherwise an online computer, the service's own first), so runners never race.

Compaction #

When a thread's next request would come within reserveTokens (16k, or a quarter of a small window) of the model's context window, the service summarizes its older messages before calling the model (src/compaction.ts):

  • Summary records. The summary goes in an ai.languid.conversation.summary record naming the first message kept verbatim. The compiled thread becomes that summary, then the messages after it. Messages are never deleted, so evicted turns stay in the space for search later.
  • Recent turns kept whole. About keepRecentTokens (20k) of the newest messages stay verbatim, starting at a user turn when possible, and capped so the result fits with room to grow. A manual /compact keeps only the latest turn.
  • Rolling summaries. Each summary folds in the previous one. Spans too big for one request are summarized in passes. The agent's own model writes it, in the first person, with lookup hints for details it had to leave out. Blocks aren't repeated, since they're always in context.
  • Memory pressure. Past 80% of the threshold, the system prompt tells the agent its oldest messages are about to be summarized, so it can save what matters to its blocks first.
  • pi. pi's /compact, its automatic compaction and its overflow recovery all call the service, so pi never summarizes its own copy.

Tune per agent with compaction: { reserveTokens, keepRecentTokens } in the config record. The approach borrows from pi (token-based cut, rolling summary) and Codex (summary as a handoff, the user's words kept).

Scripts: the xrpc tool #

The agent looks things up by writing JavaScript, not by calling one tool per lookup. xrpc runs a script in pi's QuickJS sandbox (@earendil-works/pi-codemode; src/codemode.ts) whose only capability is calling XRPC methods: no fetch, timers, modules or filesystem. Calls inside a script can run in parallel, and only the script's output enters the context.

const [msgs, notes] = await Promise.all([
  tools.ai_languid_memory_searchRecords({ collection: 'ai.languid.conversation.message', text: 'deploy' }),
  tools.com_atproto_repo_getRecord({ collection: 'ai.languid.memory.block', rkey: 'notes' }),
])
return { hits: msgs.records.length, notes: notes.value.value }

Methods (src/methods.ts):

method type what
com.atproto.repo.describeRepo query a repo's DID, handle and collections
com.atproto.repo.listRecords query one collection, newest first, paged; long strings shortened
com.atproto.repo.getRecord query one record in full (a block: collection ai.languid.memory.block, rkey its label)
ai.languid.memory.searchRecords query the agent's own records by exact field values (where) and text, leaving out the turn the script runs in
ai.languid.memory.createBlock / appendBlock / replaceBlock / rewriteBlock procedure block edits, with the block tools' checks
ai.languid.memory.pinBlock procedure pin a block (pinned: true, shown in full every turn) or unpin it (listed by label); changes nothing else, so it works on read-only blocks
  • Where reads go. Without repo (or with "self"), the repo methods read the agent's own space from the service's copy, so they see exactly what the context is compiled from. With a handle or DID, they make unauthenticated queries to that account's PDS. Those requests never carry the agent's token, refuse private, loopback and tailnet addresses (src/atproto/identity.ts), don't follow redirects, and time out after 10 s. Addresses are checked before connecting, so DNS rebinding isn't covered. The installation's own PDS and PLC (LANGUID_PLC, default plc.directory) are exempt, which is how a dev stack's handles resolve. A DID the configured PLC doesn't know is looked up on plc.directory, so a dev service still reads real accounts.

  • Discovery. The system prompt lists the methods the agent's policy allows and the collections in its space, under <xrpc>. That depends only on the policy, so it doesn't change between turns. Inside a script, ALL_TOOLS lists the methods, describeTool(name) returns one's TypeScript declaration, and searchTools(query) finds them by words.

  • Policy (src/policy.ts). Each call is decided by method, collection, and repo (self or network), first matching rule wins, and nothing matched means denied. Methods no rule could allow are hidden. The default allows the three repo reads anywhere and ai.languid.memory.*. Set policy in the config record to change it, for example to read only conversations:

    { "rules": [{ "method": "com.atproto.repo.*", "collection": "ai.languid.conversation.*", "effect": "allow" }] }
    

    A malformed policy allows nothing. approve is accepted, but scripts can't ask the owner yet, so it denies for now. Below every policy is a floor: com.atproto.server.*, admin.*, identity.*, space.* and temp.* are never callable, and nor are generic record writes to ai.languid.* collections.

  • Records. The methods a script called (arguments, status, errors, duration) are recorded on its tool.result, as nestedCalls.

  • Limits. 60 s and 64 MB per script; output past 30,000 characters is cut off.

  • xrpc doesn't take the agent's write lock; its block edits take it one at a time, so a slow network read doesn't hold up other edits. block_load is gone: agents created before this have their prompt's mention of it rewritten when the service loads them.

Records #

NSID rkey where
ai.languid.agent.owner self agent public repo
ai.languid.agent.link agent DID owner public repo
ai.languid.owner.profile self owner space (at://<owner>/space/ai.languid.space.owner/self)
ai.languid.agent.config self agent space
ai.languid.memory.block label agent space
ai.languid.conversation.thread tid agent space
ai.languid.conversation.message tid agent space
ai.languid.conversation.summary tid agent space
ai.languid.tool.definition name agent space
ai.languid.tool.call tid agent space
ai.languid.tool.result tid agent space
ai.languid.computer.node computer name agent space (see below); ai.languid.machine.node until Nov 15, moved when the service opens the agent
ai.languid.computer.permissions computer name agent space

Shapes are in src/records.ts. There are no published lexicons yet; src/methods.ts describes the xrpc methods' inputs and outputs as JSON Schema. Arbitrary model JSON (tool arguments, schemas) is stored as JSON strings, because the atproto data model has no floats.

What the Spaces alpha does and doesn't give us #

Verified against the alpha PDS image of the Nov 12 release (PDS 0.5.57; atproto@d4def6e per its release notes):

  • Space refs look like at://<authority DID>/space/<type>/<skey>. A record URI appends /<repo DID>/<collection>/<rkey>.
  • createSpace anchors the space on the calling account, so the owner's account is the authority of its agents' spaces. Over OAuth it needs the scope space:<type>?manage=create (members: manage=update); the authority defaults to the granting account, and the PDS must be able to resolve the space type's lexicon. skey is chosen by the caller (languid uses the agent name), so one authority holds many spaces of a type.
  • deleteSpace deletes only the authority's own repo in the space; other members' repos stay until each member clears its own (clearRecords).
  • No compare-and-swap. space.putRecord has no swapRecord and space.applyWrites has no swapCommit. languid runs one harness per agent, and the agent is the only writer to its own repo in the space.
  • Each member writes only its own repo. Reading another member's repo needs a space credential (getDelegationToken → authorizeSpaceSync → signed request). A bearer session gets RepoNotFound.
  • listRecords returns records in descending rkey order and has no ordering parameter (reverse was removed Nov 12 and is ignored); SpaceRepo.list sorts what it gets.
  • Members are set in batches: memberspace.putMembers takes { space, members: [{ did, read, write }] }. createSpace and getSpace return the ref as space.
  • Migration has exportSpaceMeta/importSpaceMeta and getRepo/importRepo (STAR files).

Deviations from the design #

  • computer.node records live in the agent's repo in its space, not the owner's, because cross-member reads need space credentials, which aren't implemented yet.
  • A block is pinned (pinned: true: shown in full every turn, under <pinned_blocks>) or unpinned (listed by label and description under <unpinned_blocks>, and read with getRecord). The agent pins and unpins with block_pin { label, pinned }, which changes only that flag. Blocks written before the rename carry inContext instead; the service rewrites them as pinned when it loads the agent, and updates the system prompt's sentences about blocks the same way.
  • A block can name a subject DID, the account it is about (the agent sets it with block_create, as self, owner, a handle or a DID). The harness renders the subject's current verified handle and relation on the block tag, so blocks never hold a copy of a handle. New agents' persona is about the agent and owner about the owner; older owner blocks are migrated on load, dropping the "My owner's handle is …" line.
  • User turns are written into the agent's repo, with the sender's DID in author (the authenticated caller on the service; the owner for a local languid run) and the client in via: an open label, with cli, pi, web and api the recommended ones; any client can send its own short lowercase label (discord, say), and a turn without one is api. The model sees each one in an envelope: <message from="alice.languid.ai" did="did:plc:…" relation="owner" via="pi" at="…" uri="at://…" cid="…">…</message>. uri and cid identify the stored message record. from is shown only for a handle that resolves back to the DID. The system prompt's <messages> section, rendered by the harness rather than stored in the config, explains the envelope.

What's left to build is in ROADMAP.md.

Development #

pnpm typecheck
pnpm test        # e2e against ./dev/stack (faux model, real PDS, real runner)
./dev/stack logs pds
bun run languid admin prune   # delete dev PDS accounts your state doesn't know about
./dev/stack reset   # delete all dev identities