Something went wrong. Try again.
Open source agent hosting on the AT Protocol
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440// Manager: mints accounts on the hosted PDS and sets up each agent's space.//// Accounts it creates:// - the installation owner (once; other owners sign in with their own atproto account)// - per agent, the agent account (its own DID; authors its records)// and per agent a space, at://<owner DID>/space/ai.languid.space.agent/<agent name>: a memberspace// whose authority is the owner's own account, with owner and agent as read/write members. The// space is created as the owner: with the installation owner's password, or for an owner who// signed in, with the OAuth session they granted (src/oauth.ts). The owner's PDS must run Spaces.//// Older agents have a space under an account this installation made: one per owner// (`State.authorities`, "<owner>-spaces") or, before that, one per agent (`AgentEntry.authority`,// skey "self"). `languid admin migrate-authority` moves them (src/migrate.ts).
import crypto from 'node:crypto'import fs from 'node:fs'import { Session, XrpcError, xrpc, type PdsCall } from './atproto/xrpc.ts'import { SpaceRepo } from './atproto/space.ts'import { NSID, now, ONBOARDING_DESCRIPTION, ONBOARDING_LABEL, type AgentConfig, type Block } from './records.ts'import { type Account, type AgentEntry, type State, saveState, updateState } from './state.ts'import { BLOCK_READ_HINT, BLOCKS_INTRO, COMPUTERS_INTRO, toolDefinitionRecords } from './tools.ts'
export const DEFAULT_MODEL = { provider: 'anthropic', model: 'claude-haiku-5-5' }
function adminPassword(): string { if (process.env.LANGUID_PDS_ADMIN_PASSWORD) return process.env.LANGUID_PDS_ADMIN_PASSWORD const env = new URL('../.dev/pds.env', import.meta.url) const m = fs.existsSync(env) && fs.readFileSync(env, 'utf8').match(/^PDS_ADMIN_PASSWORD=(\S+)$/m) if (!m) throw new Error('Set LANGUID_PDS_ADMIN_PASSWORD (or run ./dev/stack up for a local PDS)') return m[1]}
const adminAuth = () => ({ authorization: 'Basic ' + Buffer.from('admin:' + adminPassword()).toString('base64') })
/** The PDS's handle suffix, the first one it offers: ".test" on the dev PDS, ".languid.ai" hosted. */export async function handleDomain(pds: string): Promise<string> { const d = await xrpc(pds, 'com.atproto.server.describeServer') const domain = d.availableUserDomains?.[0] if (!domain) throw new Error(`${pds} offers no handle domains (PDS_SERVICE_HANDLE_DOMAINS)`) return domain.startsWith('.') ? domain : `.${domain}`}
/** DID registered for a handle on this PDS, or null if the handle is free. */export async function resolveHandle(pds: string, handle: string): Promise<string | null> { try { const r = await xrpc(pds, 'com.atproto.identity.resolveHandle', { params: { handle } }) return r.did } catch (e) { if (e instanceof XrpcError && e.status === 400) return null throw e }}
/** Accounts on the PDS that this installation's state does not reference. */export async function findOrphans(state: State): Promise<{ did: string; handle: string }[]> { const known = new Set<string>() for (const a of knownAccounts(state)) known.add(a.did) // Invited owners' accounts are theirs; the service never deletes them. for (const did of Object.keys(state.owners ?? {})) known.add(did) const dids: string[] = [] let cursor: string | undefined do { const page = await xrpc(state.pds, 'com.atproto.sync.listRepos', { params: { limit: 1000, cursor } }) dids.push(...page.repos.map((r: any) => r.did)) cursor = page.cursor } while (cursor) const orphans = dids.filter((d) => !known.has(d)) const out: { did: string; handle: string }[] = [] for (let i = 0; i < orphans.length; i += 50) { const params = new URLSearchParams() for (const d of orphans.slice(i, i + 50)) params.append('dids', d) const res = await fetch(new URL(`/xrpc/com.atproto.admin.getAccountInfos?${params}`, state.pds), { headers: adminAuth() }) if (!res.ok) throw new XrpcError('com.atproto.admin.getAccountInfos', res.status) for (const info of (await res.json()).infos) out.push({ did: info.did, handle: info.handle }) } return out.sort((a, b) => a.handle.localeCompare(b.handle))}
export async function deleteAccount(pds: string, did: string) { await xrpc(pds, 'com.atproto.admin.deleteAccount', { body: { did }, headers: adminAuth() })}
/** How long a deleted agent can be restored before its account is deleted for good. */export const DELETE_GRACE_DAYS = 30
/** * Delete an agent the reversible way: deactivate its PDS account (its repo stops being served, its * handle stays taken) and move it from `agents` to `deletedAgents`, out of everything that lists or * runs agents. The account itself is deleted once the grace period ends (purgeDeletedAgents), and * until then restoreAgent undoes this. Deactivation comes first: if the PDS refuses, nothing changes. */export async function deactivateAgent(state: State, name: string, at = new Date()) { const entry = state.agents[name] if (!entry) throw new Error(`no agent named "${name}"`) const purgeAfter = new Date(at.getTime() + DELETE_GRACE_DAYS * 86400000) const session = await Session.login(state.pds, entry.agent.did, entry.agent.password) await session.call('com.atproto.server.deactivateAccount', { body: { deleteAfter: purgeAfter.toISOString() } }) updateState(state, (s) => { const e = s.agents[name] if (!e) return delete s.agents[name] if (s.defaultAgent === name) delete s.defaultAgent s.deletedAgents = { ...s.deletedAgents, [name]: { ...e, deletedAt: at.toISOString(), purgeAfter: purgeAfter.toISOString() } } }) return { purgeAfter }}
/** Bring back an agent deleted within its grace period: reactivate its account and list it again. */export async function restoreAgent(state: State, name: string) { const gone = state.deletedAgents?.[name] if (!gone) throw new Error(`no deleted agent named "${name}"`) if (state.agents[name]) throw new Error(`an agent named "${name}" exists`) const session = await Session.login(state.pds, gone.agent.did, gone.agent.password) await session.call('com.atproto.server.activateAccount', { method: 'POST' }) updateState(state, (s) => { const d = s.deletedAgents?.[name] if (!d) return const { deletedAt: _, purgeAfter: __, ...entry } = d s.agents[name] = entry delete s.deletedAgents![name] })}
/** Delete, for good, the accounts of deleted agents whose grace period is over. Returns their names. */export async function purgeDeletedAgents(state: State, now = new Date()) { const purged: string[] = [] for (const [name, d] of Object.entries(state.deletedAgents ?? {})) { if (Date.parse(d.purgeAfter) > now.getTime()) continue for (const a of [d.agent, d.authority]) { if (!a) continue try { await deleteAccount(state.pds, a.did) } catch (e) { // Already gone is done; anything else waits for the next sweep. if (!(e instanceof XrpcError && e.status === 400)) throw e } } updateState(state, (s) => { if (s.deletedAgents) delete s.deletedAgents[name] }) purged.push(name) } return purged}
/** * Names that can't be handles. With a handle domain like ".languid.ai", a handle is also a hostname * beside the PDS and the site, so an account must not be able to take one of theirs. */const RESERVED = new Set( ('pds www api app admin root languid mail smtp imap ftp ns1 ns2 docs blog status help support about ' + 'auth oauth login signup account accounts cdn static assets dev test staging plc relay appview xrpc ops sites').split(' '),)
export function checkHandle(handle: string) { const label = handle.split('.')[0].toLowerCase() if (RESERVED.has(label)) throw new Error(`"${label}" is a reserved name; choose another`)}
/** Change an account's handle on its PDS (and so in its DID document). */export async function moveHandle(pds: string, account: Account, handle: string) { checkHandle(handle) const session = await Session.login(pds, account.did, account.password) await session.call('com.atproto.identity.updateHandle', { body: { handle } }) account.handle = handle}
/** Every account this installation made: the owner, space authorities (per owner, and old per-agent ones) and agents. */export function knownAccounts(state: State): Account[] { return [ state.owner, state.ops, ...Object.values(state.authorities ?? {}), ...Object.values(state.agents).flatMap((a) => [a.agent, a.authority]), // Deleted agents' accounts are deactivated, not gone, until their grace period ends. ...Object.values(state.deletedAgents ?? {}).flatMap((a) => [a.agent, a.authority]), ].filter((a): a is Account => !!a)}
/** * Move every account this installation made (owner, space authorities, agents) to a handle * domain: "scout.pds.languid.ai" becomes "scout.languid.ai". DIDs don't change. With `apply` false, * only reports what would move. State is saved after each account, so a failure can be resumed. */export async function rehandle(state: State, domain: string, apply: boolean) { const accounts = knownAccounts(state) const moves: { did: string; from: string; to: string }[] = [] for (const account of accounts) { const to = `${account.handle.split('.')[0]}${domain}` if (account.handle === to) continue moves.push({ did: account.did, from: account.handle, to }) if (!apply) continue await moveHandle(state.pds, account, to) saveState(state) } return moves}
export async function createAccount(pds: string, handle: string, password = crypto.randomBytes(24).toString('base64url'), opts: { reserved?: boolean } = {}): Promise<Account> { if (!opts.reserved) checkHandle(handle) const { code } = await xrpc(pds, 'com.atproto.server.createInviteCode', { body: { useCount: 1 }, headers: adminAuth() }) const res = await xrpc(pds, 'com.atproto.server.createAccount', { body: { handle, email: `${handle}@languid.invalid`, password, inviteCode: code }, }) return { handle, did: res.did, password }}
export async function ensureOwner(state: State, handle: string): Promise<Account> { if (state.owner) { if (state.owner.handle !== handle) throw new Error(`Owner already set to ${state.owner.handle}`) return state.owner } state.owner = await createAccount(state.pds, handle) saveState(state) return state.owner}
const DEFAULT_SYSTEM_PROMPT = `You are an agent with your own atproto identity. Your state (blocks, messages, tool calls and results) is stored as records in your private space, so it persists across sessions and hosts.
${BLOCKS_INTRO} ${BLOCK_READ_HINT}
${COMPUTERS_INTRO} Prefer reading and listing before changing anything, keep shell commands non-interactive, and say what you are about to do before doing anything destructive.`
function initialBlocks(name: string, agentDid: string, ownerDid: string, ownerAbout = '', onboarding?: string): Block[] { const t = now() const setup: Block[] = onboarding ? [{ label: ONBOARDING_LABEL, description: ONBOARDING_DESCRIPTION, value: onboarding, limit: 5000, readOnly: false, pinned: true, subject: ownerDid, updatedAt: t }] : [] return [ { label: 'persona', description: 'Who you are: your name, character, and how you work.', value: `I am ${name}, an agent hosted by languid. I am curious, direct, and careful with my owner's computers.`, limit: 5000, readOnly: false, pinned: true, subject: agentDid, updatedAt: t, }, { label: 'owner', description: 'What you know about your owner: preferences, projects, context.', value: ownerAbout, limit: 5000, readOnly: false, pinned: true, subject: ownerDid, updatedAt: t, }, { label: 'notes', description: 'Scratch notes: longer-lived facts that do not need to be in every turn.', value: '', limit: 20000, readOnly: false, pinned: false, updatedAt: t, }, ...setup, ]}
/** Clean up what someone typed into a web form ("My Agent" -> "my-agent") before checkAgentName. */export function normalizeAgentName(raw: string): string { return raw .trim() .toLowerCase() .replace(/[\s_]+/g, '-') .replace(/-+/g, '-') .replace(/^-+|-+$/g, '')}
export function checkAgentName(name: string) { if (!/^[a-z][a-z0-9-]{0,30}$/.test(name) || name.endsWith('-') || name.includes('--')) { throw new Error('Agent name: lowercase letters, digits, single dashes (cannot end with a dash)') }}
/** An agent's space: anchored on its owner's DID, keyed by the agent's name. */export const agentSpaceRef = (authorityDid: string, name: string) => `at://${authorityDid}/space/${NSID.spaceAgent}/${name}`
/** The authority DID a space ref is anchored on. */export const spaceAuthorityDid = (space: string) => space.split('/')[2]
/** An account acting as the authority of its own spaces. */export interface Authority { did: string call: PdsCall}
/** The installation owner as the authority of their agents' spaces, signed in with the password this installation holds. */export async function installationAuthority(state: State): Promise<Authority> { const owner = state.owner if (!owner) throw new Error('no owner account yet; create one first with: languid init') const session = await Session.login(state.pds, owner.did, owner.password) return { did: owner.did, call: (nsid, opts) => session.call(nsid, opts) }}
/** * The service's ops account, signed in: made on this installation's PDS (as ops.<handle domain>) the * first time it's needed, and kept in state like the owner's. `read`/`save` are the service's state. */let opsMaking: Promise<Account> | undefinedexport async function opsAuthority(read: () => State, save: (s: State) => void = saveState): Promise<Authority> { let account = read().ops if (!account) { opsMaking ??= (async () => { const state = read() if (state.ops) return state.ops const made = await createAccount(state.pds, `ops${await handleDomain(state.pds)}`, undefined, { reserved: true }) const fresh = read() fresh.ops = made save(fresh) return made })().finally(() => { opsMaking = undefined }) account = await opsMaking } const session = await Session.login(read().pds, account.did, account.password) return { did: account.did, call: (nsid, opts) => session.call(nsid, opts) }}
/** * Create (or reopen) the agent space `name` under `authority`, with `members` as read/write members. * Reopening an existing space keeps its records; that is what lets a failed migration be re-run. */export async function openAgentSpace(authority: Authority, name: string, members: string[]): Promise<string> { const space = agentSpaceRef(authority.did, name) try { await authority.call('com.atproto.space.getSpace', { params: { space } }) } catch (e) { if (!(e instanceof XrpcError && e.error === 'SpaceNotFound')) throw e const created = await authority.call('com.atproto.space.createSpace', { body: { spaceType: NSID.spaceAgent, skey: name, policy: { $type: 'com.atproto.memberspace.policy' } }, }) if (created.space !== space) throw new Error(`createSpace returned ${created.space}, expected ${space}`) } await authority.call('com.atproto.memberspace.putMembers', { body: { space, members: members.map((did) => ({ did, read: true, write: true })) }, }) return space}
/** * Create an agent: its account on this PDS, and its space under its owner's DID. Without `owner` * the agent belongs to the installation owner. For any other owner, pass who they are and a way * to act as them on their PDS (their OAuth session). */export async function createAgent( state: State, name: string, opts: { model?: { provider: string; model: string } owner?: { did: string; handle: string; call: PdsCall } /** What the owner block starts with: what the owner said they use Languid for (ownerProfileMemory). */ ownerAbout?: string /** The onboarding block's value (onboardingMemory), for an owner's first agent only. */ onboarding?: string } = {},): Promise<AgentEntry> { if (state.agents[name]) throw new Error(`Agent "${name}" already exists`) if (state.deletedAgents?.[name]) throw new Error(`Agent "${name}" was deleted and can be restored until ${state.deletedAgents[name].purgeAfter.slice(0, 10)}; choose another name`) checkAgentName(name) const local = !opts.owner || opts.owner.did === state.owner?.did const authority: Authority = local ? await installationAuthority(state) : { did: opts.owner!.did, call: opts.owner!.call } const owner = { did: authority.did, handle: local ? state.owner!.handle : opts.owner!.handle }
// Check the handle before creating anything, so a clash can't leave half an agent behind. const domain = await handleDomain(state.pds) const handle = `${name}${domain}` if (await resolveHandle(state.pds, handle)) { throw new Error( `can't create agent "${name}": the handle ${handle} is already registered on ${state.pds}, but not by this installation.\n` + ` Use a different agent name, or see leftover accounts with: languid admin prune`, ) } // The owner's PDS creates the space; find out that it can before making an account that would be left over. try { await authority.call('com.atproto.space.getSpace', { params: { space: agentSpaceRef(authority.did, name) } }) throw new Error(`${owner.handle} already has a space for an agent named "${name}"; use a different name`) } catch (e) { if (!(e instanceof XrpcError)) throw e if (e.error !== 'SpaceNotFound') throw new Error(`can't create a space as ${owner.handle}: ${e.message}. Their PDS has to support atproto Spaces.`) } const agent = await createAccount(state.pds, handle) let space: string try { space = await openAgentSpace(authority, name, [owner.did, agent.did]) } catch (e) { await deleteAccount(state.pds, agent.did).catch(() => {}) throw e }
const entry: AgentEntry = { name, agent, owner: owner.did, space } updateState(state, (s) => { s.agents[name] = entry })
// The only public records: the owner link, provable from both sides (PUBLIC_COLLECTIONS). The // agent's name and everything else is private, in the space. const agentSession = await Session.login(state.pds, agent.handle, agent.password) const t = now() const putPublic = (s: Session, collection: string, rkey: string, record: object) => s.call('com.atproto.repo.putRecord', { body: { repo: s.did, collection, rkey, record: { $type: collection, ...record } }, }) await putPublic(agentSession, NSID.agentOwner, 'self', { owner: owner.did, space, createdAt: t }) // The owner's half of the link goes in the owner's public repo. Only the installation owner's: // a signed-in owner grants nothing on their repo. if (local) { const ownerSession = await Session.login(state.pds, state.owner!.did, state.owner!.password) await putPublic(ownerSession, NSID.agentLink, agent.did, { agent: agent.did, createdAt: t }) }
// Private state in the agent space, authored by the agent. const repo = new SpaceRepo(agentSession, space) const model = opts.model ?? DEFAULT_MODEL const config: AgentConfig = { ...model, systemPrompt: DEFAULT_SYSTEM_PROMPT, createdAt: t, updatedAt: t, } // One commit, not one per record: a room making agents at once queues on the PDS's writes. const create = (collection: string, rkey: string, value: object) => ({ op: 'create' as const, collection, rkey, value: { $type: collection, ...value } }) const writes = [ create(NSID.agentConfig, 'self', config), ...initialBlocks(name, agent.did, owner.did, opts.ownerAbout, opts.onboarding).map((b) => create(NSID.block, b.label, b)), ...toolDefinitionRecords().map((d) => create(NSID.toolDefinition, d.name, d)), ] for (let i = 0; i < writes.length; i += 100) await repo.applyWrites(writes.slice(i, i + 100)) return entry}
export async function agentSession(state: State, entry: AgentEntry) { // By DID: a handle can change under a running store (settings), and the DID can't. return Session.login(state.pds, entry.agent.did, entry.agent.password)}