visual-comments 0.1.0 → 0.2.0

package/README.md

@@ -6,8 +6,8 @@ they mean, and start a thread pinned to it. One self-hosted comment server
 holds the threads of many sites; each site signs its own people in and passes
 their comment requests on through its own server.
 
-This package is the browser library (Svelte 5), the server-side proxy, and the
-script-tag build. The comment server and full documentation live in the
+This package is the browser library (Svelte 5), the server-side proxy, the
+SvelteKit adapter, the command for coding agents, and the script-tag build. The comment server and full documentation live in the
 [repository](https://github.com/Convex-Works/visual-comments).
 
 ```sh
@@ -56,6 +56,23 @@ comment server at `/v1/visual-comments.js` and also shipped here as
 `visual-comments/widget.js`; see the
 [markup reference](https://github.com/Convex-Works/visual-comments/blob/main/docs/MARKUP.md).
 
+## SvelteKit
+
+`visual-comments/sveltekit` sets the comments up from environment variables
+(`VISUAL_COMMENTS_ENABLED`, `_SERVER`, `_SPACE`, `_SECRET`): a hook, a layout
+`load`, and `<Comments>` with a `<Toolbar>` at the bottom of the window. They
+can sign people in on their own, apart from the app's accounts, and the
+`visualComments()` Vite plugin from `visual-comments/vite` leaves them out of
+production builds. See the
+[SvelteKit guide](https://github.com/Convex-Works/visual-comments/blob/main/docs/SVELTEKIT.md).
+
+## Coding agents
+
+The package's `visual-comments` command lets a coding agent join a space:
+`npx visual-comments connect <site>`, then `next` to wait for new comments,
+`reply` and `presence`. See
+[coding agents](https://github.com/Convex-Works/visual-comments/blob/main/docs/CODING-AGENTS.md).
+
 ## License
 
 MIT

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// The `visual-comments` command, for coding agents: join a site's comment space
+// once a person allows it, wait for new comments, reply, and say what you are
+// doing. It talks only to the site's comments route (`/_comments`), with the
+// agent's token. Node built-ins only, and compiled, because Node does not strip
+// types in node_modules.
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { parseArgs } from 'node:util';
+const DEFAULT_PATH = '/_comments';
+/** The server holds `/agent/next` and the token request up to 50 s; give it room. */
+const LONG_POLL_MS = 80_000;
+const REQUEST_MS = 30_000;
+const MAX_BACKOFF_MS = 30_000;
+const IMAGE_EXTENSIONS = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp' };
+const HELP = {
+    main: `Usage: visual-comments <command> [options]
+
+Lets a coding agent take part in a site's comments. A person allows it once in
+the browser; then it waits for new comments, replies, and shows what it is doing.
+
+Commands:
+  connect <site>     Ask to join the site's comments, and wait for a person to allow it.
+  next               Wait for new comments; print them as JSON.
+  reply <thread>     Reply in a thread, with --body or stdin.
+  presence <state>   Say what you are doing: viewing, working or gone.
+  agents             List the space's agents.
+  disconnect         Leave the space and forget the token.
+
+Options:
+  --site <site>      Which connected site, when there are several. Or set VISUAL_COMMENTS_SITE.
+  -h, --help         Help for a command: visual-comments <command> --help
+
+Tokens are kept in \${XDG_CONFIG_HOME:-~/.config}/visual-comments/agents.json.
+Exit codes: 0 done, 1 error, 2 not connected or the token was rejected.`,
+    connect: `Usage: visual-comments connect <site> [--name <name>] [--path <path>]
+
+Asks to join the site's comments, prints the address where a person allows it
+(and opens it in the browser), waits, then saves the token.
+
+  --name <name>   The name people see on your comments. Default "Agent".
+  --path <path>   Where the site answers comment requests. Default /_comments.
+
+Example: visual-comments connect http://localhost:5173 --name Claude`,
+    next: `Usage: visual-comments next [--site <site>]
+
+Waits, as long as it takes, until a thread has something new for you, then
+prints { site, threads, participants } as JSON and exits. The threads are then
+read for you. Images are downloaded; each gets a "path". Network errors are
+retried. Run it again at once to keep listening.`,
+    reply: `Usage: visual-comments reply <thread> [--body <text>] [--site <site>]
+
+Replies in thread #<thread>. Without --body, the text is read from stdin.
+Prints { thread: { id, url, comment } }.
+
+Example: echo "Done: the table is tighter." | visual-comments reply 12`,
+    presence: `Usage: visual-comments presence <viewing|working|gone> [options]
+
+Says what you are doing, for everyone in the space to see. Each update states
+the whole presence: options left out are cleared.
+
+  --key <key>       One presence per key, to work on several things at once. Default "".
+  --thread <n>      The thread it is about.
+  --surface <id>    The surface (e.g. a frame) it is about.
+  --page <page>     The page it is about.
+  --note <text>     What you are doing, e.g. "Tightening the table".
+  --site <site>     Which connected site.
+
+Example: visual-comments presence working --key 12 --thread 12 --note "Tightening the table"
+         visual-comments presence gone --key 12`,
+    agents: `Usage: visual-comments agents [--site <site>]
+
+Prints the space's agents as JSON: { site, me, agents }.`,
+    disconnect: `Usage: visual-comments disconnect [--site <site>]
+
+Removes you from the space and forgets the token.`
+};
+/** Ends the command with a message and an exit code. */
+class CliError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** A failed request. Status 0 when the site could not be reached. */
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const log = (message) => process.stderr.write(`${message}\n`);
+/** Asked for, so on stdout; usage errors go to stderr. */
+const help = (text) => process.stdout.write(`${text}\n`);
+const print = (value) => process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+function parse(command, args, options) {
+    try {
+        return parseArgs({ args, options: { ...options, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        throw new CliError(1, `${error.message}\n\n${HELP[command]}`);
+    }
+}
+// Sites and saved tokens
+/** A site as typed: `localhost:5173` works too. */
+function siteUrl(site) {
+    const withScheme = /^[a-z][a-z\d+.-]*:\/\//i.test(site)
+        ? site
+        : `${/^(localhost|127\.|\[::1\])/.test(site) ? 'http' : 'https'}://${site}`;
+    try {
+        const url = new URL(withScheme);
+        if (url.protocol === 'http:' || url.protocol === 'https:')
+            return url;
+    }
+    catch { /* below */ }
+    throw new CliError(1, `"${site}" is not a web address.`);
+}
+/** The site, with any path, and where it answers comment requests: `<origin><path>`, which keys the saved token. */
+function locate(site, path = DEFAULT_PATH) {
+    const url = siteUrl(site);
+    const route = `/${path.replace(/^\/+|\/+$/g, '')}`;
+    return { site: `${url.origin}${url.pathname.replace(/\/+$/, '')}`, endpoint: `${url.origin}${route === '/' ? '' : route}` };
+}
+function credentialsFile() {
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'visual-comments', 'agents.json');
+}
+function loadAll() {
+    const file = credentialsFile();
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return {};
+        throw new CliError(1, `${file} cannot be read: ${error.message}`);
+    }
+}
+function saveAll(all) {
+    const file = credentialsFile();
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    // Written whole, then moved over the old file, so a crash never leaves half of it. Only you can read it.
+    const temporary = `${file}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(all, null, '\t')}\n`, { mode: 0o600 });
+    renameSync(temporary, file);
+}
+/** The site the command is for, when it is connected. Set for the hint on a rejected token. */
+let current;
+function connected(site) {
+    const all = loadAll();
+    const endpoints = Object.keys(all);
+    const wanted = site ?? process.env.VISUAL_COMMENTS_SITE;
+    let matches = endpoints;
+    if (wanted) {
+        const url = siteUrl(wanted);
+        const exact = `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+        matches = endpoints.filter((endpoint) => endpoint === exact);
+        if (!matches.length)
+            matches = endpoints.filter((endpoint) => new URL(endpoint).origin === url.origin);
+        if (!matches.length)
+            throw new CliError(2, `Not connected to ${wanted}. Run: visual-comments connect ${wanted}`);
+    }
+    else if (!matches.length) {
+        throw new CliError(2, 'Not connected to any site. Run: visual-comments connect <site>');
+    }
+    if (matches.length > 1) {
+        throw new CliError(1, `Connected to several sites; choose one with --site or VISUAL_COMMENTS_SITE:\n  ${matches.join('\n  ')}`);
+    }
+    const endpoint = matches[0];
+    current = { endpoint, site: new URL(endpoint).origin, saved: all[endpoint] };
+    return current;
+}
+// Requests
+async function call(endpoint, route, init = {}) {
+    const headers = { accept: 'application/json' };
+    if (init.token)
+        headers.authorization = `Bearer ${init.token}`;
+    if (init.body !== undefined)
+        headers['content-type'] = 'application/json';
+    let response;
+    let text;
+    try {
+        response = await fetch(`${endpoint}${route}`, {
+            method: init.method ?? 'GET',
+            headers,
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+            signal: AbortSignal.timeout(init.timeout ?? REQUEST_MS)
+        });
+        text = await response.text();
+    }
+    catch (error) {
+        throw new HttpError(0, `${endpoint} cannot be reached (${reason(error)}).`);
+    }
+    let data;
+    try {
+        data = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        // HTML from the site itself, e.g. a sign-in page: the comments route is elsewhere.
+        const message = `${endpoint}${route} did not answer like a comments route (status ${response.status}). Is --path right?`;
+        throw new HttpError(response.ok ? 404 : response.status, message);
+    }
+    if (!response.ok) {
+        const error = data && typeof data === 'object' && 'error' in data ? data.error : undefined;
+        throw new HttpError(response.status, typeof error === 'string' ? error : `The site answered ${response.status}.`);
+    }
+    return { status: response.status, data: data };
+}
+function reason(error) {
+    if (error instanceof Error && error.name === 'TimeoutError')
+        return 'no answer in time';
+    if (!(error instanceof Error))
+        return String(error);
+    // fetch fails with "fetch failed"; the cause says why, e.g. ECONNREFUSED.
+    const cause = error.cause;
+    if (cause instanceof Error)
+        return 'code' in cause && typeof cause.code === 'string' ? cause.code : cause.message;
+    return error.message;
+}
+/** Worth trying again: the site could not be reached, or had a passing problem. */
+function transient(error) {
+    return error instanceof HttpError && (error.status === 0 || error.status === 408 || error.status === 429 || error.status >= 500);
+}
+function backoff(previous) {
+    return previous ? Math.min(previous * 2, MAX_BACKOFF_MS) : 1000;
+}
+// Commands
+async function connect(args) {
+    const { values, positionals } = parse('connect', args, { name: { type: 'string' }, path: { type: 'string' } });
+    if (values.help)
+        return help(HELP.connect);
+    if (positionals.length !== 1)
+        throw new CliError(1, HELP.connect);
+    const { site, endpoint } = locate(positionals[0], values.path);
+    const name = (values.name ?? 'Agent').trim();
+    if (!name || name.length > 60)
+        throw new CliError(1, 'The name must be 1 to 60 characters.');
+    // Joining again would add a second agent to the space; a saved token that still works is enough.
+    const existing = loadAll()[endpoint];
+    if (existing) {
+        try {
+            const { data } = await call(endpoint, '/agents', { token: existing.token });
+            const agent = data.agents.find((agent) => agent.id === existing.agent.id);
+            if (agent) {
+                log(`Already connected to ${site} as ${agent.name}. To join again, run visual-comments disconnect first.`);
+                return print({ site, agent });
+            }
+        }
+        catch (error) {
+            if (!(error instanceof HttpError && error.status === 401))
+                throw error;
+        }
+    }
+    const { data: request } = await call(endpoint, '/agents/requests', { method: 'POST', body: { name } });
+    const approval = `${site}/#vc-connect=${encodeURIComponent(request.id)}`;
+    log(`To let ${name} join, open\n\n  ${approval}\n\ncheck that it shows the code ${request.code}, and click Allow. Waiting…`);
+    openBrowser(approval);
+    // The server answers 404 once the request expires; this only ends retries against a site that stays down.
+    const deadline = Date.now() + Math.max(request.expiresAt - Date.now(), 0) + 60_000;
+    let delay = 0;
+    while (Date.now() < deadline) {
+        try {
+            const { data } = await call(endpoint, `/agents/requests/${encodeURIComponent(request.id)}/token`, {
+                method: 'POST',
+                body: { secret: request.secret },
+                timeout: LONG_POLL_MS
+            });
+            delay = 0;
+            if ('token' in data) {
+                saveAll({ ...loadAll(), [endpoint]: { token: data.token, agent: data.agent } });
+                log(`Connected to ${site} as ${data.agent.name}, added by ${data.agent.addedBy.name}.`);
+                return print({ site, agent: data.agent });
+            }
+        }
+        catch (error) {
+            if (error instanceof HttpError && error.status === 404)
+                throw new CliError(1, 'The request was denied, or it expired. Run connect again.');
+            if (!transient(error))
+                throw error;
+            delay = backoff(delay);
+            log(`${error.message} Trying again in ${delay / 1000} s.`);
+            await sleep(delay);
+        }
+    }
+    throw new CliError(1, 'The request expired. Run connect again.');
+}
+/** Best effort: the address is printed anyway. */
+function openBrowser(url) {
+    const [command, args] = process.platform === 'darwin' ? ['open', [url]]
+        : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsVerbatimArguments: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch { /* no browser here */ }
+}
+async function next(args) {
+    const { values } = parse('next', args, { site: { type: 'string' } });
+    if (values.help)
+        return help(HELP.next);
+    const { endpoint, site, saved } = connected(values.site);
+    // Each request is short; the loop is what waits, so no proxy times out a request held for hours.
+    let delay = 0;
+    for (;;) {
+        let inbox;
+        try {
+            ({ data: inbox } = await call(endpoint, '/agent/next?wait=50', { token: saved.token, timeout: LONG_POLL_MS }));
+            delay = 0;
+        }
+        catch (error) {
+            if (!transient(error))
+                throw error;
+            delay = backoff(delay);
+            log(`${error.message} Trying again in ${delay / 1000} s.`);
+            await sleep(delay);
+            continue;
+        }
+        if (!inbox.threads.length)
+            continue;
+        // The threads are marked read now, so from here nothing may fail: an image that will not download keeps no path.
+        await downloadImages(endpoint, saved.token, inbox.threads);
+        return print({ site, threads: inbox.threads, participants: inbox.participants });
+    }
+}
+async function downloadImages(endpoint, token, threads) {
+    const host = new URL(endpoint).host;
+    const folder = join(tmpdir(), 'visual-comments', process.platform === 'win32' ? host.replace(/:/g, '_') : host);
+    mkdirSync(folder, { recursive: true });
+    for (const comment of threads.flatMap((thread) => thread.comments)) {
+        for (const image of comment.images) {
+            const name = `${image.id}-${image.key}`;
+            // An image's address never changes, so one downloaded before is the same image.
+            const known = Object.values(IMAGE_EXTENSIONS).map((extension) => join(folder, `${name}.${extension}`)).find((path) => existsSync(path));
+            if (known) {
+                image.path = known;
+                continue;
+            }
+            try {
+                image.path = await downloadImage(`${endpoint}/images/${image.id}/${encodeURIComponent(image.key)}`, token, join(folder, name));
+            }
+            catch (error) {
+                log(`Image ${image.id} could not be downloaded: ${error.message}`);
+            }
+        }
+    }
+}
+async function downloadImage(url, token, base) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            const response = await fetch(url, { headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(REQUEST_MS) });
+            if (!response.ok)
+                throw new HttpError(response.status, `the site answered ${response.status}`);
+            const type = response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() ?? '';
+            const path = `${base}.${IMAGE_EXTENSIONS[type] ?? 'bin'}`;
+            writeFileSync(path, new Uint8Array(await response.arrayBuffer()));
+            return path;
+        }
+        catch (error) {
+            const failure = error instanceof HttpError ? error : new HttpError(0, reason(error));
+            if (attempt >= 3 || !transient(failure))
+                throw failure;
+            await sleep(1000 * attempt);
+        }
+    }
+}
+async function reply(args) {
+    const { values, positionals } = parse('reply', args, { body: { type: 'string' }, site: { type: 'string' } });
+    if (values.help)
+        return help(HELP.reply);
+    if (positionals.length !== 1 || !/^\d+$/.test(positionals[0].replace(/^#/, '')))
+        throw new CliError(1, HELP.reply);
+    const number = Number(positionals[0].replace(/^#/, ''));
+    const { endpoint, saved } = connected(values.site);
+    const body = (values.body ?? (process.stdin.isTTY ? '' : await readStdin())).trim();
+    if (!body)
+        throw new CliError(1, 'The reply is empty. Pass --body, or the text on stdin.');
+    const { data } = await call(endpoint, `/threads/${number}/comments`, { method: 'POST', token: saved.token, body: { body } });
+    print({ thread: { id: data.thread.id, url: data.thread.url, comment: data.thread.comments.at(-1)?.id } });
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function presence(args) {
+    const { values, positionals } = parse('presence', args, {
+        key: { type: 'string' },
+        thread: { type: 'string' },
+        surface: { type: 'string' },
+        page: { type: 'string' },
+        note: { type: 'string' },
+        site: { type: 'string' }
+    });
+    if (values.help)
+        return help(HELP.presence);
+    const state = positionals[0];
+    if (positionals.length !== 1 || (state !== 'viewing' && state !== 'working' && state !== 'gone'))
+        throw new CliError(1, HELP.presence);
+    const update = { state };
+    if (values.key !== undefined)
+        update.key = values.key;
+    if (values.thread !== undefined) {
+        const thread = Number(values.thread.replace(/^#/, ''));
+        if (!Number.isInteger(thread) || thread < 1)
+            throw new CliError(1, '--thread must be a thread number.');
+        update.thread = thread;
+    }
+    if (values.surface !== undefined)
+        update.surface = values.surface;
+    if (values.page !== undefined)
+        update.page = values.page;
+    if (values.note !== undefined)
+        update.note = values.note;
+    const { endpoint, saved } = connected(values.site);
+    await call(endpoint, '/presence', { method: 'POST', token: saved.token, body: update });
+}
+async function agents(args) {
+    const { values } = parse('agents', args, { site: { type: 'string' } });
+    if (values.help)
+        return help(HELP.agents);
+    const { endpoint, site, saved } = connected(values.site);
+    const { data } = await call(endpoint, '/agents', { token: saved.token });
+    print({ site, me: saved.agent.id, agents: data.agents });
+}
+async function disconnect(args) {
+    const { values } = parse('disconnect', args, { site: { type: 'string' } });
+    if (values.help)
+        return help(HELP.disconnect);
+    const { endpoint, site, saved } = connected(values.site);
+    try {
+        await call(endpoint, `/agents/${encodeURIComponent(saved.agent.id)}`, { method: 'DELETE', token: saved.token });
+    }
+    catch (error) {
+        // Already removed by a person, or expired: forgetting the token is all that is left.
+        if (!(error instanceof HttpError && error.status === 401))
+            throw error;
+    }
+    const all = loadAll();
+    delete all[endpoint];
+    saveAll(all);
+    log(`Disconnected from ${site}.`);
+    print({ deleted: saved.agent.id });
+}
+const COMMANDS = { connect, next, reply, presence, agents, disconnect };
+async function main(argv) {
+    const [command, ...args] = argv;
+    if (!command || command === '-h' || command === '--help' || command === 'help') {
+        help(HELP.main);
+        return;
+    }
+    const run = COMMANDS[command];
+    if (!run)
+        throw new CliError(1, `Unknown command "${command}".\n\n${HELP.main}`);
+    await run(args);
+}
+main(process.argv.slice(2)).catch((error) => {
+    if (error instanceof CliError) {
+        log(error.message);
+        process.exitCode = error.code;
+    }
+    else if (error instanceof HttpError && error.status === 401 && current) {
+        log(`${error.message} Run: visual-comments connect ${current.site}`);
+        process.exitCode = 2;
+    }
+    else {
+        log(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+});

package/dist/core/presence.d.ts

@@ -0,0 +1,13 @@
+import type { Author, Participant, PresenceState } from '../shared/types.js';
+/** Someone present, however many tabs or tasks they have. */
+export interface Present {
+    author: Author;
+    /** Their busiest participant's state. */
+    state: PresenceState;
+    /** Busiest first. */
+    participants: Participant[];
+}
+/** Participants grouped by who they are, in the order they arrived. */
+export declare function present(participants: Participant[]): Present[];
+/** What a participant is doing, as a sentence, or undefined while they only look. */
+export declare function activity(participant: Participant): string | undefined;

package/dist/core/presence.js

@@ -0,0 +1,25 @@
+const RANK = { viewing: 0, typing: 1, working: 2 };
+/** Participants grouped by who they are, in the order they arrived. */
+export function present(participants) {
+    const groups = new Map();
+    for (const participant of participants) {
+        const group = groups.get(participant.author.sub);
+        if (group)
+            group.push(participant);
+        else
+            groups.set(participant.author.sub, [participant]);
+    }
+    return [...groups.values()].map((group) => {
+        group.sort((a, b) => RANK[b.state] - RANK[a.state]);
+        return { author: group[0].author, state: group[0].state, participants: group };
+    });
+}
+/** What a participant is doing, as a sentence, or undefined while they only look. */
+export function activity(participant) {
+    const { name } = participant.author;
+    if (participant.state === 'typing')
+        return `${name} is typing…`;
+    if (participant.state === 'working')
+        return participant.note ? `${name} is working: ${participant.note}` : `${name} is working…`;
+    return undefined;
+}

package/dist/core/threads.svelte.d.ts

@@ -1,5 +1,7 @@
 import type { Api } from './api.js';
-import type { CommentImage, CommentThread, NewThreadInput, Viewer } from '../shared/types.js';
+import type { Agent, AgentRequest, CommentImage, CommentThread, NewThreadInput, Participant, PresenceUpdate, Viewer } from '../shared/types.js';
+/** What this tab says about itself; its connection is added once the event stream names it. */
+export type OwnPresence = Omit<PresenceUpdate, 'connection' | 'key'>;
 /**
  * The space's threads, kept current with the server's event stream. Actions
  * show their result at once and resync with the server when they fail.
@@ -9,23 +11,48 @@ export declare class Threads {
     threads: CommentThread[];
     spaceName: string;
     loading: boolean;
+    /** Whether `viewer` is known: from the server's answer, or given when the page loaded. */
+    viewerKnown: boolean;
     /** A failed action, shown until dismissed. */
     error: string | null;
     /** Ticks every 30 seconds so relative times stay current. */
     now: number;
+    /** This tab's event stream, as the server named it, while it is open. */
+    connection: string | undefined;
+    /** Everyone present in the space, this tab included, while the event stream is open. */
+    participants: Participant[];
+    /** The space's agents once listed; undefined until then, or when the space has them turned off. */
+    agents: Agent[] | undefined;
     private api;
     private refreshing?;
     private queued;
     private listening?;
     private nextPending;
-    constructor(api: Api);
+    private presence?;
+    /** The last presence sent, with its connection, so an unchanged one is not sent again. */
+    private posted;
+    /** The participants as last received, so an unchanged list does not wake every listener. */
+    private received;
+    /** `viewer`: who is signed in, when the page already knows it; undefined to wait for the server. */
+    constructor(api: Api, viewer?: Viewer | null);
     get unreadCount(): number;
     start(): () => void;
     /** Coalesces overlapping refreshes into at most one more request. */
     refresh(): Promise<void>;
     private stopListening;
+    /** Without the stream, who is present is unknown, and the server has already let this tab go. */
+    private disconnected;
+    private setParticipants;
     /** Follows the event stream; after a dropped connection, catches up on anything missed. */
     private listen;
+    /** One message of the event stream. Servers without presence send only `change`. */
+    private receive;
+    /**
+     * Says what this tab is doing, unless it said so already. `again` sends it
+     * even so, as the heartbeat that keeps `typing` from lapsing.
+     */
+    setPresence(presence: OwnPresence, again?: boolean): void;
+    private postPresence;
     private request;
     private apply;
     /** Runs an action, showing its error and resyncing with the server if it fails. */
@@ -43,4 +70,11 @@ export declare class Threads {
     resolve(threadId: number, resolved: boolean): Promise<void>;
     markRead(threadId: number, read: boolean): Promise<void>;
     markAllRead(): Promise<void>;
+    loadAgents(): Promise<void>;
+    /** Takes an agent out of the space at once: its token stops working. */
+    removeAgent(id: string): Promise<void>;
+    /** An agent asking to join, for the person approving it. Throws when it has expired or was answered. */
+    agentRequest(id: string): Promise<AgentRequest>;
+    approveAgent(id: string): Promise<Agent>;
+    denyAgent(id: string): Promise<void>;
 }