Something went wrong. Try again.
Open source agent hosting on the AT Protocol
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214// The docs site: a page per Markdown file, each written for one reader, rendered into the docs// shell with the site's pages down the left. Every page is also served as its Markdown// (/docs/<slug>.md), and /llms.txt lists them all, so agents can read the docs as easily as people.
import fs from 'node:fs'import { Marked, type Tokens } from 'marked'import { TURN_MAP_HTML } from './docs-turn.ts'import { COPY_INNER, DOCS_JS_HREF, esc, installCommand, installCommandWindows, LOGO, loginCommand, page, type Page } from './web.ts'
const SOURCE = 'https://tangled.org/cameron.stream/languid'
export interface DocPage { /** The page's path under /docs; '' is /docs itself. */ slug: string title: string /** Who reads it and what it gets them, in one line: the sidebar's tooltip and llms.txt's entry. */ description: string section: string /** The Markdown, relative to the repo root. */ file: string}
export const DOC_PAGES: DocPage[] = [ { slug: '', title: 'Quick start', section: 'Get started', file: 'docs/site/quickstart.md', description: 'Install the CLI, sign in, and talk to your first agent.' }, { slug: 'windows', title: 'Windows', section: 'Get started', file: 'docs/site/windows.md', description: 'Set up Languid on a Windows PC: make your account, install the CLI and tray, connect the computer, and use Languid MCP.' }, { slug: 'computers', title: 'Computers', section: 'Get started', file: 'docs/site/computers.md', description: 'Let your agents read files and run commands on your computers, and choose what they may do without asking.' }, { slug: 'models', title: 'Models', section: 'Get started', file: 'docs/site/models.md', description: "Choose an agent's model: Languid's hosted models on your credit, or your own ChatGPT plan, Anthropic key or OpenRouter account." }, { slug: 'agents', title: 'Agents and memory', section: 'Using Languid', file: 'docs/site/agents.md', description: 'What an agent is: threads, memory blocks, pinning, and its instructions.' }, { slug: 'discord', title: 'Discord', section: 'Using Languid', file: 'docs/site/discord.md', description: 'Give an agent a Discord bot and talk to it there.' }, { slug: 'mcp', title: 'Languid MCP', section: 'Using Languid', file: 'docs/site/mcp.md', description: "Use your agents from any MCP client, such as Claude, ChatGPT, Claude Code or your own scripts." }, { slug: 'notifications', title: 'Notifications', section: 'Using Languid', file: 'docs/site/notifications.md', description: 'Let your agents reach you on Discord, by email or in your browser, from a chat or a Machine.' }, { slug: 'machines', title: 'Machines', section: 'Using Languid', file: 'docs/site/machines.md', description: 'Background work your agent does on a schedule or after a conversation, and asking your agent to set one up.' }, { slug: 'sites', title: 'Sites', section: 'Using Languid', file: 'docs/site/sites.md', description: 'Let an agent publish a small static website to its own atproto repo.' }, { slug: 'approvals', title: 'Approvals for apps', section: 'Using Languid', file: 'docs/site/approvals.md', description: "Run your agents from your own app, and answer the calls they ask you about." }, { slug: 'api', title: 'Speech and models API', section: 'Using Languid', file: 'docs/site/api.md', description: 'Turn speech into text and run models from your own code, billed to your credit.' }, { slug: 'evals', title: 'Evals', section: 'Using Languid', file: 'docs/evals.md', description: 'Test an agent before you change it, let it improve itself against cases it can\'t game, and keep every trial as training data.' }, { slug: 'commands', title: 'Commands', section: 'Using Languid', file: 'docs/site/commands.md', description: 'Every languid command an owner uses, and what it does.' }, { slug: 'self-host', title: 'Self-host', section: 'Self-hosting', file: 'docs/hosting.md', description: 'Run your own Languid on Fly.io: the PDS, the service and runners.' }, { slug: 'how-it-works', title: 'How it works', section: 'How it works', file: 'docs/site/how-it-works.md', description: 'How Languid keeps agents on atproto: accounts, Spaces, records and the service.' }, { slug: 'turn', title: 'A turn, step by step', section: 'How it works', file: 'docs/site/turn.md', description: 'What happens between Send and the answer: which machine does each part, what is written where, and what has to stay running.' }, { slug: 'records', title: 'Records', section: 'How it works', file: 'docs/site/records.md', description: "The ai.languid.* records that hold an agent's state, and where each one lives." },]
const href = (p: DocPage) => (p.slug ? `/docs/${p.slug}` : '/docs')const mdHref = (p: DocPage) => `/docs/${p.slug || 'index'}.md`
/** The page at a path under /docs (`/docs`, `/docs/computers`), and whether it asks for the Markdown. */export function docAt(pathname: string): { doc: DocPage; markdown: boolean } | undefined { const m = /^\/docs(?:\/([a-z-]+?))?(\.md)?\/?$/.exec(pathname) if (!m) return undefined const slug = m[1] === 'index' ? '' : (m[1] ?? '') if (m[2] && !m[1]) return undefined const doc = DOC_PAGES.find((p) => p.slug === slug) return doc && { doc, markdown: !!m[2] }}
const sources = new Map<string, string>()const read = (file: string) => { let s = sources.get(file) if (s === undefined) sources.set(file, (s = fs.readFileSync(new URL(`../${file}`, import.meta.url), 'utf8'))) return s}
/** * A page's Markdown, with this service's own commands filled in, and links between files turned * into links that work wherever it's read: other docs pages by their path, repo files on Tangled. */export function docMarkdown(doc: DocPage, origin: string): string { const fileDir = doc.file.slice(0, doc.file.lastIndexOf('/') + 1) return read(doc.file) .replaceAll('@INSTALL_WINDOWS@', installCommandWindows(origin) ?? `irm ${origin}/install.ps1 | iex`) .replaceAll('@INSTALL@', installCommand(origin) ?? `curl -fsSL ${origin}/install | sh`) .replaceAll('@LOGIN@', loginCommand(origin)) .replaceAll('@SERVICE@', origin) .replace(/\]\((?!https?:|\/|#|mailto:)([^)\s]+)\)/g, (_, target: string) => { const [path, hash] = target.split('#') const file = new URL(path, `file:///${fileDir}`).pathname.slice(1) const page = DOC_PAGES.find((p) => p.file === file) const to = page ? href(page) : `${SOURCE}/blob/main/${file}` return `](${to}${hash ? `#${hash}` : ''})` })}
const slugify = (s: string) => s .toLowerCase() .replace(/<[^>]+>|&[a-z#0-9]+;/g, '') .replace(/[^a-z0-9]+/g, '-') .replace(/^-|-$/g, '')
function safeHref(raw: string | null | undefined): string | undefined { if (!raw) return undefined const trimmed = raw.trim() if (/^(?:https?:|mailto:)/i.test(trimmed)) return trimmed if (trimmed.startsWith('/') && !trimmed.startsWith('//') && !trimmed.startsWith('/\\')) return trimmed if (trimmed.startsWith('#')) return trimmed return undefined}
/** The Markdown as HTML for the docs shell: ids on headings, copy buttons on one-line commands. */export function renderDoc(md: string): { html: string; title: string; headings: { id: string; text: string }[] } { let title = '' const headings: { id: string; text: string }[] = [] const marked = new Marked({ gfm: true, renderer: { heading({ tokens, depth }: Tokens.Heading) { const text = this.parser.parseInline(tokens) if (depth === 1) { title ||= text.replace(/<[^>]+>/g, '') return `<h1>${text}</h1>` } const id = slugify(text) if (depth === 2) headings.push({ id, text: text.replace(/<[^>]+>/g, '') }) // already escaped by parseInline return `<h${depth} id="${id}">${text}</h${depth}>` }, code({ text, lang }: Tokens.Code) { if ((lang === 'sh' || lang === 'bash') && !text.includes('\n') && !text.includes('#')) return `<div class="cmd"><pre><code>${esc(text)}</code></pre><button type="button" class="copy" aria-label="Copy command" hidden>${COPY_INNER}</button></div>` return `<pre><code>${esc(text)}</code></pre>` }, table(token: Tokens.Table) { const cell = (c: Tokens.TableCell, tag: string) => `<${tag}>${this.parser.parseInline(c.tokens)}</${tag}>` return ( `<div class="tbl"><table><thead><tr>${token.header.map((c) => cell(c, 'th')).join('')}</tr></thead>` + `<tbody>${token.rows.map((r) => `<tr>${r.map((c) => cell(c, 'td')).join('')}</tr>`).join('')}</tbody></table></div>` ) }, blockquote({ tokens }: Tokens.Blockquote) { return `<div class="note">${this.parser.parse(tokens)}</div>` }, html({ text }: Tokens.HTML | Tokens.Tag) { // Pictures drawn in code, where the Markdown marks them; all other raw HTML is escaped. if (text.trim() === '<!-- turn-map -->') return TURN_MAP_HTML return esc(text) }, link({ href, title, tokens }: Tokens.Link) { const label = this.parser.parseInline(tokens) const safe = safeHref(href) if (!safe) return label const titleAttr = title ? ` title="${esc(title)}"` : '' return `<a href="${esc(safe)}"${titleAttr}>${label}</a>` }, image({ href, title, text }: Tokens.Image) { const safe = safeHref(href) if (!safe) return esc(text) const titleAttr = title ? ` title="${esc(title)}"` : '' return `<img src="${esc(safe)}" alt="${esc(text)}"${titleAttr}>` }, }, }) const html = marked.parse(md, { async: false }) as string return { html, title, headings }}
const rendered = new Map<string, ReturnType<typeof renderDoc>>()
/** A docs page: the site's pages down the left (this one's sections under it), the page beside them. */export function docsPage(doc: DocPage, origin: string): Page { const key = `${doc.slug}\n${origin}` let r = rendered.get(key) if (!r) rendered.set(key, (r = renderDoc(docMarkdown(doc, origin)))) const sections = [...new Set(DOC_PAGES.map((p) => p.section))] const list = (current: boolean) => sections .map( (s) => `<p class="toc-head">${esc(s)}</p><ul>` + DOC_PAGES.filter((p) => p.section === s) .map((p) => p === doc ? `<li><a href="${href(p)}" class="on" aria-current="page">${esc(p.title)}</a>` + (current && r.headings.length ? `<ul class="subs">${r.headings.map((h) => `<li><a class="sub" href="#${h.id}">${h.text}</a></li>`).join('')}</ul>` : '') + `</li>` : `<li><a href="${href(p)}" title="${esc(p.description)}">${esc(p.title)}</a></li>`, ) .join('') + `</ul>`, ) .join('') const i = DOC_PAGES.indexOf(doc) const next = DOC_PAGES[i + 1] const path = href(doc) return page( 200, doc.slug ? `${doc.title} · Languid docs` : 'Languid docs', `<aside class="docs-panel"><a class="mark" href="/">${LOGO}<span><b>Languid</b><span class="path">/docs</span></span></a><hr>` + `<nav class="docs-toc" aria-label="Docs">${list(true)}</nav></aside>` + `<details class="docs-pages"><summary>${esc(doc.section)} · ${esc(doc.title)}</summary><nav class="docs-toc" aria-label="Docs pages">${list(false)}</nav></details>` + `<article class="docs">${r.html}` + `<p class="docs-foot">` + (next ? `<a href="${href(next)}">Next: ${esc(next.title)}</a>` : '<span></span>') + `<a href="${mdHref(doc)}" class="muted">This page as Markdown</a></p>` + `</article><script src="${DOCS_JS_HREF}" defer></script>`, { path, script: true, bodyClass: 'docs', headers: { link: `<${mdHref(doc)}>; rel="alternate"; type="text/markdown"` } }, )}
/** /llms.txt: what Languid is and every docs page, as Markdown links an agent can follow. */export function llmsTxt(origin: string): string { const sections = [...new Set(DOC_PAGES.map((p) => p.section))] return ( `# Languid\n\n` + `> Stateful agents on the AT Protocol. Each agent is its own atproto account, its memory and conversations are records in a private Space, and its tools run on its owner's own computers.\n\n` + `Every docs page is Markdown at the address below. Source: ${SOURCE}\n\n` + sections .map((s) => `## ${s}\n\n${DOC_PAGES.filter((p) => p.section === s).map((p) => `- [${p.title}](${origin}${mdHref(p)}): ${p.description}`).join('\n')}\n`) .join('\n') )}