import express from 'express' import { requireUser, requireHuman, isAdmin, HOST, OAUTH_ENABLED } from './auth.js' import { HANDLE_RE, DOC_ID_RE, PAGE_SLUG_RE, docNameFor } from './util.js' import { getProjectStructure } from './pages.js' import { seedPlayground, findPlayground } from './playground.js' import { hocuspocus } from './collab.js' import * as store from './store.js' import * as collab from './collab.js' // page-scoped doc name from ?page= / body.page (default: home) function pageDocName(req, res) { const slug = String(req.query.page || req.body?.page || 'home') if (!PAGE_SLUG_RE.test(slug) && slug !== 'home') { res.status(400).json({ error: 'bad page slug' }) return null } if (slug !== 'home' && slug !== '_structure') { const pages = store.pagesOf(req.params.id) if (!pages?.[slug]) { res.status(404).json({ error: `no page "${slug}" in this project` }) return null } } return docNameFor(req.params.id, slug) } function requireDocAccess(req, res, next) { if (!store.getRegistry()[req.params.id]) return res.status(404).json({ error: 'doc not found' }) if (!store.canAccessDoc(req.params.id, req.user.username)) return res.status(404).json({ error: 'doc not found' }) next() } export function apiRouter() { const router = express.Router() router.use(express.json({ limit: '2mb' })) // --- docs --- router.get('/docs', requireUser, (req, res) => { const reg = store.getRegistry() const docs = Object.entries(reg) .filter(([id]) => store.canAccessDoc(id, req.user.username)) .map(([id, meta]) => ({ id, ...meta })) .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0)) res.json({ docs }) }) router.post('/docs', requireUser, requireHuman, async (req, res) => { const title = String(req.body?.title || 'Untitled').slice(0, 120) const id = await collab.createDoc(title, req.user.username) res.json({ id }) }) router.delete('/docs/:id', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => { const meta = store.getRegistry()[req.params.id] if (meta.createdBy && meta.createdBy !== req.user.username) { return res.status(403).json({ error: 'only the creator can delete a doc' }) } await collab.deleteDoc(req.params.id) res.json({ ok: true }) }) // share / unshare (creator only) router.post('/docs/:id/share', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => { const meta = store.getRegistry()[req.params.id] if (meta.createdBy && meta.createdBy !== req.user.username) { return res.status(403).json({ error: 'only the creator can share a doc' }) } const username = String(req.body?.username || '').trim() const remove = req.body?.remove === true if (!/^[a-zA-Z0-9_.-]{2,40}$/.test(username)) return res.status(400).json({ error: 'invalid username' }) if (username === req.user.username) return res.status(400).json({ error: 'that is you' }) if (!remove && OAUTH_ENABLED) { const check = await fetch(`https://huggingface.co/api/users/${encodeURIComponent(username)}/overview`) if (!check.ok) return res.status(400).json({ error: `no Hugging Face user named "${username}"` }) } const current = meta.sharedWith || [] const sharedWith = remove ? current.filter(u => u !== username) : [...new Set([...current, username])] store.upsertRegistry(req.params.id, { sharedWith }) res.json({ ok: true, shared_with: sharedWith }) }) router.get('/docs/:id', requireUser, checkDocId, requireDocAccess, async (req, res) => { const meta = store.getRegistry()[req.params.id] const docName = pageDocName(req, res) if (!docName) return if (docName.endsWith('::_structure')) await collab.ensureStructurePage(req.params.id) const snapshot = await collab.getDocSnapshot(docName) const pages = store.pagesOf(req.params.id) || {} res.json({ id: req.params.id, title: meta.title, page: docName.includes('::') ? docName.split('::')[1] : 'home', pages: Object.entries(pages).map(([slug, p]) => ({ slug, title: p.title || slug })), created_by: meta.createdBy || null, shared_with: meta.sharedWith || [], playground: !!meta.playground, ...snapshot, }) }) // --- pages + structure --- router.get('/docs/:id/structure', requireUser, checkDocId, requireDocAccess, async (req, res) => { await collab.ensureStructurePage(req.params.id) const structure = getProjectStructure(hocuspocus, req.params.id) if (!structure) return res.status(404).json({ error: 'doc not found' }) res.json(structure) }) // new-page suggestions (agents or humans propose a whole page; humans accept) router.post('/docs/:id/page-suggestions', requireUser, checkDocId, requireDocAccess, async (req, res) => { const { title, content_markdown, rationale, as_agent, mention_id } = req.body || {} if (!title || typeof title !== 'string') return res.status(400).json({ error: 'title required' }) const identity = agentIdentity(req, as_agent) if (identity.error) return res.status(403).json({ error: identity.error }) const result = await collab.createPageProposal(req.params.id, { title, contentMarkdown: typeof content_markdown === 'string' ? content_markdown : '', rationale, author: identity.author, authorType: identity.authorType, }) if (result.error) return res.status(400).json({ error: result.error }) if (identity.authorType === 'agent') collab.completeMention(mention_id, {}) res.json({ ok: true, page_suggestion_id: result.id, slug: result.slug }) }) router.get('/docs/:id/page-suggestions/:pid', requireUser, checkDocId, requireDocAccess, async (req, res) => { const p = await collab.getPageProposal(req.params.id, req.params.pid) if (!p) return res.status(404).json({ error: 'proposal not found' }) res.json({ id: p.id, slug: p.slug, title: p.title, content_markdown: p.contentMarkdown, rationale: p.rationale, author: p.author, author_type: p.authorType, status: p.status, }) }) router.post('/docs/:id/page-suggestions/:pid/:action', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => { if (!['accept', 'reject'].includes(req.params.action)) return res.status(404).json({ error: 'unknown action' }) const result = await collab.resolvePageProposal(req.params.id, req.params.pid, req.params.action, req.user.username) if (result.error) return res.status(400).json({ error: result.error }) res.json({ ok: true, slug: result.slug }) }) router.post('/docs/:id/pages', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => { const title = String(req.body?.title || '').trim().slice(0, 120) if (!title) return res.status(400).json({ error: 'title required' }) const explicitSlug = req.body?.slug ? String(req.body.slug) : null const result = await collab.createPage(req.params.id, title, req.user.username, { slug: explicitSlug }) if (result.error) return res.status(400).json({ error: result.error }) res.json({ ok: true, slug: result.slug }) }) // any collaborator may delete pages (project deletion stays creator-only) router.delete('/docs/:id/pages/:slug', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => { if (!PAGE_SLUG_RE.test(req.params.slug)) return res.status(400).json({ error: 'bad page slug' }) const result = await collab.deletePage(req.params.id, req.params.slug) if (result.error) return res.status(400).json({ error: result.error }) res.json({ ok: true }) }) // --- playground (per-user test project) --- router.post('/playground', requireUser, requireHuman, async (req, res) => { const existing = findPlayground(req.user.username) if (existing) return res.json({ id: existing }) const { id } = await seedPlayground(req.user.username) res.json({ id }) }) router.post('/docs/:id/reset', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => { const meta = store.getRegistry()[req.params.id] if (!meta.playground) return res.status(400).json({ error: 'only playground projects can be reset' }) if (meta.createdBy !== req.user.username) return res.status(403).json({ error: 'only the creator can reset' }) await seedPlayground(req.user.username, req.params.id) res.json({ ok: true }) }) // --- image uploads --- router.post( '/docs/:id/upload', requireUser, checkDocId, requireDocAccess, express.raw({ type: 'image/*', limit: '10mb' }), (req, res) => { if (!Buffer.isBuffer(req.body) || !req.body.length) return res.status(400).json({ error: 'send the image bytes as the request body with an image/* content-type' }) const name = store.saveUpload(req.body, req.headers['content-type']) if (!name) return res.status(400).json({ error: 'unsupported image type (png, jpeg, gif, webp, svg)' }) res.json({ ok: true, url: `/files/${name}` }) } ) // --- comments / replies --- router.post('/docs/:id/threads/:tid/reply', requireUser, checkDocId, requireDocAccess, async (req, res) => { const { text, as_agent, mention_id } = req.body || {} if (!text || typeof text !== 'string') return res.status(400).json({ error: 'text required' }) const identity = agentIdentity(req, as_agent) if (identity.error) return res.status(403).json({ error: identity.error }) const docName = pageDocName(req, res) if (!docName) return const msg = await collab.addMessage(docName, req.params.tid, { author: identity.author, authorType: identity.authorType, text: text.slice(0, 8000), }) if (!msg) return res.status(404).json({ error: 'thread not found' }) if (identity.authorType === 'agent') { collab.completeMention(mention_id, { docId: docName, threadId: req.params.tid, handle: identity.author }) } res.json({ ok: true, message_id: msg.id }) }) // --- suggestions --- router.post('/docs/:id/suggestions', requireUser, checkDocId, requireDocAccess, async (req, res) => { const { anchor_start, anchor_end, block_index, replacement_markdown, rationale, as_agent, mention_id, thread_id, supersedes } = req.body || {} if (typeof replacement_markdown !== 'string') return res.status(400).json({ error: 'replacement_markdown (string) required' }) if (anchor_start == null && block_index == null && !supersedes) return res.status(400).json({ error: 'pass block_index or anchor_start/anchor_end (from GET /api/docs/:id blocks), or supersedes' }) const identity = agentIdentity(req, as_agent) if (identity.error) return res.status(403).json({ error: identity.error }) const docName = pageDocName(req, res) if (!docName) return const result = await collab.createSuggestion(docName, { anchorStart: anchor_start, anchorEnd: anchor_end, blockIndex: block_index, replacementMarkdown: replacement_markdown, rationale, author: identity.author, authorType: identity.authorType, threadId: thread_id, supersedes, }) if (result.error) return res.status(400).json({ error: result.error }) if (identity.authorType === 'agent') { collab.completeMention(mention_id, { docId: docName, threadId: thread_id, handle: identity.author }) } res.json({ ok: true, suggestion_id: result.suggestion.id }) }) router.post('/docs/:id/suggestions/:sid/:action', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => { if (!['accept', 'reject', 'reopen'].includes(req.params.action)) return res.status(404).json({ error: 'unknown action' }) const docName = pageDocName(req, res) if (!docName) return const result = await collab.resolveSuggestionAction(docName, req.params.sid, req.params.action, req.user.username, { markOnly: req.body?.mark_only === true, }) if (result.error) return res.status(400).json({ error: result.error }) res.json({ ok: true }) }) // --- agents --- // With ?doc=: agents that can act in that doc (their owner has access) — // exactly the set that @mentions there will reach. Without: your own agents // (the admin sees all, for cleanup). router.get('/agents', requireUser, (req, res) => { const docId = req.query.doc if (docId) { if (!DOC_ID_RE.test(String(docId)) || !store.getRegistry()[docId] || !store.canAccessDoc(docId, req.user.username)) { return res.status(404).json({ error: 'doc not found' }) } return res.json({ agents: collab .agentPresence() .filter(a => store.canAccessDoc(docId, a.owner)) .filter(a => a.shared || a.owner === req.user.username), }) } const all = collab.agentPresence() res.json({ agents: isAdmin(req.user.username) ? all : all.filter(a => a.owner === req.user.username) }) }) router.post('/agents', requireUser, requireHuman, (req, res) => { const handle = String(req.body?.handle || '').toLowerCase() if (!HANDLE_RE.test(handle)) return res.status(400).json({ error: 'handle must match ' + HANDLE_RE }) const agents = store.getAgents() if (agents[handle] && agents[handle].owner !== req.user.username) { return res.status(409).json({ error: 'handle already registered by another user' }) } const key = store.newAgentKey() agents[handle] = { owner: req.user.username, createdAt: agents[handle]?.createdAt || Date.now(), keyHash: store.hashAgentKey(key), } store.saveAgents(agents) res.json({ ok: true, handle, key }) }) router.post('/agents/:handle/visibility', requireUser, requireHuman, (req, res) => { const agents = store.getAgents() const handle = req.params.handle if (!agents[handle]) return res.status(404).json({ error: 'not found' }) if (agents[handle].owner !== req.user.username) return res.status(403).json({ error: 'not your handle' }) agents[handle].shared = req.body?.shared !== false store.saveAgents(agents) res.json({ ok: true, shared: agents[handle].shared }) }) router.post('/agents/:handle/rotate', requireUser, requireHuman, (req, res) => { const agents = store.getAgents() const handle = req.params.handle if (!agents[handle]) return res.status(404).json({ error: 'not found' }) if (agents[handle].owner !== req.user.username) return res.status(403).json({ error: 'not your handle' }) const key = store.newAgentKey() agents[handle].keyHash = store.hashAgentKey(key) store.saveAgents(agents) res.json({ ok: true, handle, key }) }) router.delete('/agents/:handle', requireUser, requireHuman, (req, res) => { const agents = store.getAgents() const handle = req.params.handle if (!agents[handle]) return res.status(404).json({ error: 'not found' }) if (agents[handle].owner !== req.user.username && !isAdmin(req.user.username)) { return res.status(403).json({ error: 'only the handle owner or the space admin can remove an agent' }) } delete agents[handle] store.saveAgents(agents) collab.cancelAgentTasks(handle) res.json({ ok: true }) }) // --- mention long-poll --- // Instant snapshot of outstanding work (nothing is claimed) — for debugging. // The `wait` param is gone: waiting happens on /mentions/stream. router.get('/mentions', requireUser, (req, res) => { const result = collab.snapshotMentions(req.user.username, req.agent?.handle) if (result.error) return res.status(400).json(result) res.json(result) }) // Long-poll for up to an hour: a streaming response with ":hb" heartbeat lines // every 25s (keeps proxies from killing the idle connection), ending with one // JSON line when mentions arrive or the wait expires. One request per hour // instead of one per minute for an idle agent. router.get('/mentions/stream', requireUser, async (req, res) => { const wait = Math.max(5, Math.min(Number(req.query.wait) || 1800, 3600)) res.writeHead(200, { 'content-type': 'application/x-ndjson', 'cache-control': 'no-cache', 'x-accel-buffering': 'no', }) res.write(':connected\n') const heartbeat = setInterval(() => { try { res.write(':hb\n') } catch {} }, 25000) let cancel = null req.on('close', () => cancel?.()) const result = await collab.pollMentions(req.user.username, wait, req.agent?.handle, { maxWait: 3600, registerCancel: fn => (cancel = fn), }) clearInterval(heartbeat) if (!result.cancelled) { try { res.write(JSON.stringify(result.error ? result : { mentions: result.mentions }) + '\n') } catch {} } res.end() }) router.post('/mentions/:id/dismiss', requireUser, (req, res) => { const result = collab.dismissMention(req.params.id, req.user.username) if (result.error) return res.status(400).json(result) res.json(result) }) // --- agent prompt --- router.get('/agent-prompt', requireUser, (req, res) => { const docId = DOC_ID_RE.test(String(req.query.doc || '')) ? req.query.doc : '' const handle = HANDLE_RE.test(String(req.query.handle || '')) ? req.query.handle : '' res.type('text/plain').send(agentPrompt(docId, handle)) }) return router } function checkDocId(req, res, next) { if (!DOC_ID_RE.test(req.params.id)) return res.status(400).json({ error: 'bad doc id' }) next() } // Resolve who a write is attributed to. Requests authenticated with an // app-issued agent key ARE that agent; otherwise as_agent must be owned by the caller. function agentIdentity(req, asAgent) { if (req.agent) { if (asAgent && String(asAgent).toLowerCase() !== req.agent.handle) { return { error: `this key belongs to @${req.agent.handle}, not @${asAgent}` } } return { author: req.agent.handle, authorType: 'agent' } } if (!asAgent) return { author: req.user.username, authorType: 'user' } const handle = String(asAgent).toLowerCase() const agents = store.getAgents() if (!agents[handle]) return { error: `agent handle @${handle} is not registered` } if (agents[handle].owner !== req.user.username) return { error: `@${handle} belongs to ${agents[handle].owner}, not you` } return { author: handle, authorType: 'agent' } } function agentPrompt(docId, handle) { const tokenHint = OAUTH_ENABLED ? `the agent key that was shown when "@${handle}" was registered (an "ak_..." string; rotate it in the app if lost). It only works for this editor — it is not a Hugging Face credential.` : `the dev token "dev:" (no real key needed on this dev server)` return `You are the collaborative-editor agent "@${handle}" for the document ${docId} at ${HOST}. You participate in a shared document, but you NEVER edit the text directly. You only: 1. reply to comment threads, and 2. propose suggestions (block replacements) that a human can accept or reject. Authenticate every request with ${tokenHint} export AGENT_KEY= AUTH='-H "Authorization: Bearer $AGENT_KEY"' Work loop — repeat until the user tells you to stop: 1. Wait for work with ONE blocking call (up to ~50 minutes — do NOT use a short poll loop): curl -sN --max-time 3300 $AUTH "${HOST}/api/mentions/stream?wait=3000" | grep -v '^:' | tail -n 1 The stream sends ":hb" heartbeat lines while idle; the final line is JSON: {"mentions": [...]}. Empty output or an empty list just means the wait expired — immediately make the same call again. This is the normal idle state; one call per ~50 minutes costs almost nothing. Each mention has: mention_id, doc_id, page, thread_id, instruction, anchored_text (the text the comment is attached to), thread_messages (conversation so far), requested_by. Documents are PROJECTS with multiple pages; "page" tells you which page the comment is on ("home" is the main page). Always pass the same page back when reading or writing. If "about_suggestion" is set, the comment discusses one of your earlier suggestions — the user is asking you to revise it. Post an updated suggestion with "supersedes": "" — this links yours as a revision and reuses the old anchors, but BOTH stay visible; a human decides which one to accept. If "implicit_follow_up" is true, you were not tagged: the message was posted in a thread you are involved in and is probably addressed to you. Judge it yourself — if it asks you to act, act; if it needs no action from you (small talk, addressed to someone else, a simple thanks), dismiss it silently: curl -s $AUTH -X POST "${HOST}/api/mentions//dismiss" 2. For each mention addressed to you, read the page for context: curl -s $AUTH "${HOST}/api/docs/?page=" Returns the page markdown, "blocks": [{index, anchor_start, anchor_end, markdown}], and "pages" (all pages in the project). GET ${HOST}/api/docs//structure shows the page tree. The tree is defined by a YAML code block on the special "_structure" page (read it with ?page=_structure): one "- slug" line per page, two-space indent to nest. To propose a NEW page, POST a single new-page suggestion with its title and full content: curl -s $AUTH -X POST "${HOST}/api/docs//page-suggestions" -H 'content-type: application/json' \\ -d '{"title": "Page Title", "content_markdown": "# Page Title\\n\\n...", "rationale": "why", "as_agent": "${handle}"}' It appears in the sidebar as a pending page immediately; a human accepts it (which creates the page with your content and adds it to the structure) or rejects it. To reorganize EXISTING pages, suggest an edit to the _structure page's YAML as an ordinary suggestion. Removing a page's line never deletes it — it just moves to "unfiled" in the sidebar. Cross-reference pages in any markdown you write as [Title](/d//). 3. Do the task the instruction asks for, using your own tools and judgment. 4. Respond — and put the work IN THE DOCUMENT, not in the comment. The document is the deliverable; a comment is only a notification that something happened. So: - Anything meant to be read later — prose, analysis, tables, lists, results, code — goes into a suggestion (replacement_markdown) or a new page (content_markdown), where a human can accept, edit and keep it. - Keep thread replies SHORT: one to three sentences, ideally under ~400 characters, saying what you did and where to look. "Rewrote the intro to lead with the finding — see the suggestion on block 2." is a good reply. - NEVER paste the content itself into a comment, and never paste it twice (once in the reply, once in the suggestion). If your answer does not fit in three sentences, that is the signal that it belongs in the document. - No process narration, no restating what the suggestion already shows, no long code blocks or bullet-point essays in a reply. Long comments are collapsed behind a "Show more" in the UI and are painful to read on a phone. - A question that genuinely needs no document change (a yes/no, a pointer) is answered in the thread — briefly. Reply in the thread: curl -s $AUTH -X POST "${HOST}/api/docs//threads//reply" \\ -H 'content-type: application/json' \\ -d '{"text": "...", "page": "", "as_agent": "${handle}", "mention_id": ""}' And — for anything more than an acknowledgement — propose the text change itself (replaces the addressed block(s); markdown supports paragraphs, # headings, - lists, - [ ]/- [x] task lists, GFM tables (| a | b | with a | --- | --- | separator row), \`\`\`code\`\`\`, **bold**, *italic*, [links](url), LaTeX math (inline \$x^2\$, or \$\$...\$\$ on its own line for a display formula), and live HTML embeds — see below): curl -s $AUTH -X POST "${HOST}/api/docs//suggestions" \\ -H 'content-type: application/json' \\ -d '{"block_index": , "replacement_markdown": "...", "rationale": "why", "page": "", "as_agent": "${handle}", "mention_id": "", "thread_id": ""}' (You can also pass anchor_start/anchor_end from the blocks listing instead of block_index, or "supersedes": "" to mark it as a revision of an earlier suggestion of yours.) Figures: you can include images in suggestions. Upload the bytes first: curl -s $AUTH -X POST "${HOST}/api/docs//upload" \\ -H 'content-type: image/png' --data-binary @figure.png -> {"url": "/files/..."} — then reference it in replacement_markdown as ![caption](/files/...). External https image URLs work too. Live HTML embeds: for layouts markdown can't express (aligned figure grids, animated explainers, small interactive widgets), emit a fenced block tagged \`html-embed\`: \`\`\`html-embed
\`\`\` The snippet renders in a sandboxed iframe: inline