visual-comments 0.1.0 → 0.2.0

package/dist/core/threads.svelte.js

@@ -7,17 +7,35 @@ export class Threads {
     threads = $state([]);
     spaceName = $state('');
     loading = $state(true);
+    /** Whether `viewer` is known: from the server's answer, or given when the page loaded. */
+    viewerKnown = $state(false);
     /** A failed action, shown until dismissed. */
     error = $state(null);
     /** Ticks every 30 seconds so relative times stay current. */
     now = $state(Date.now());
+    /** This tab's event stream, as the server named it, while it is open. */
+    connection = $state();
+    /** Everyone present in the space, this tab included, while the event stream is open. */
+    participants = $state.raw([]);
+    /** The space's agents once listed; undefined until then, or when the space has them turned off. */
+    agents = $state.raw();
     api;
     refreshing;
     queued = false;
     listening;
     nextPending = -1;
-    constructor(api) {
+    presence;
+    /** The last presence sent, with its connection, so an unchanged one is not sent again. */
+    posted = '';
+    /** The participants as last received, so an unchanged list does not wake every listener. */
+    received = '[]';
+    /** `viewer`: who is signed in, when the page already knows it; undefined to wait for the server. */
+    constructor(api, viewer) {
         this.api = api;
+        if (viewer !== undefined) {
+            this.viewer = viewer;
+            this.viewerKnown = true;
+        }
     }
     get unreadCount() {
         return this.threads.filter((thread) => thread.unread && !thread.resolvedAt).length;
@@ -46,6 +64,7 @@ export class Threads {
                     throw new Error();
                 const snapshot = (await response.json());
                 this.viewer = snapshot.viewer;
+                this.viewerKnown = true;
                 this.spaceName = snapshot.space.name;
                 // Keep replies that are still on their way to the server.
                 const pending = new Map(this.threads.map((t) => [t.id, t.comments.filter((c) => c.pending)]));
@@ -75,6 +94,19 @@ export class Threads {
     stopListening() {
         this.listening?.abort();
         this.listening = undefined;
+        this.disconnected();
+    }
+    /** Without the stream, who is present is unknown, and the server has already let this tab go. */
+    disconnected() {
+        this.connection = undefined;
+        this.setParticipants([]);
+    }
+    setParticipants(participants) {
+        const json = JSON.stringify(participants);
+        if (json === this.received)
+            return;
+        this.received = json;
+        this.participants = participants;
     }
     /** Follows the event stream; after a dropped connection, catches up on anything missed. */
     listen() {
@@ -101,8 +133,7 @@ export class Threads {
                         buffer += value;
                         let end;
                         while ((end = buffer.indexOf('\n\n')) !== -1) {
-                            if (/^event: change$/m.test(buffer.slice(0, end)))
-                                void this.refresh();
+                            this.receive(buffer.slice(0, end));
                             buffer = buffer.slice(end + 2);
                         }
                     }
@@ -112,12 +143,65 @@ export class Threads {
                 }
                 if (controller.signal.aborted)
                     break;
+                this.disconnected();
                 await new Promise((done) => setTimeout(done, 3000));
             }
             if (this.listening === controller)
                 this.listening = undefined;
         })();
     }
+    /** One message of the event stream. Servers without presence send only `change`. */
+    receive(message) {
+        const event = /^event: (.*)$/m.exec(message)?.[1];
+        if (event === 'change')
+            return void this.refresh();
+        if (event !== 'hello' && event !== 'presence')
+            return;
+        let data;
+        try {
+            data = JSON.parse(message.match(/^data: ?(.*)$/gm)?.map((line) => line.replace(/^data: ?/, '')).join('\n') ?? '');
+        }
+        catch {
+            return;
+        }
+        if (event === 'hello' && typeof data?.connection === 'string') {
+            this.connection = data.connection;
+            // A new connection is a new participant: tell the server what this tab is doing.
+            void this.postPresence();
+        }
+        else if (event === 'presence' && Array.isArray(data?.participants)) {
+            this.setParticipants(data.participants);
+        }
+    }
+    /**
+     * 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, again = false) {
+        this.presence = presence;
+        void this.postPresence(again);
+    }
+    async postPresence(again = false) {
+        const connection = this.connection;
+        if (!connection || !this.presence)
+            return;
+        const body = JSON.stringify({ connection, ...this.presence });
+        if (body === this.posted && !again)
+            return;
+        this.posted = body;
+        try {
+            const response = await this.api.fetch('/presence', {
+                method: 'POST', headers: { 'Content-Type': 'application/json' }, body
+            });
+            if (!response.ok && this.posted === body)
+                this.posted = '';
+        }
+        catch {
+            // The next change, or the next connection, sends it again.
+            if (this.posted === body)
+                this.posted = '';
+        }
+    }
     async request(method, path, body) {
         const response = await this.api.fetch(path, {
             method,
@@ -216,4 +300,37 @@ export class Threads {
     async markAllRead() {
         await Promise.all(this.threads.filter((t) => t.unread).map((t) => this.markRead(t.id, true)));
     }
+    // Agents.
+    async loadAgents() {
+        try {
+            this.agents = (await this.request('GET', '/agents')).agents;
+        }
+        catch {
+            this.agents = undefined;
+        }
+    }
+    /** Takes an agent out of the space at once: its token stops working. */
+    async removeAgent(id) {
+        this.agents = this.agents?.filter((agent) => agent.id !== id);
+        try {
+            await this.request('DELETE', `/agents/${encodeURIComponent(id)}`);
+        }
+        catch (error) {
+            this.error = error.message;
+            void this.loadAgents();
+        }
+    }
+    /** An agent asking to join, for the person approving it. Throws when it has expired or was answered. */
+    async agentRequest(id) {
+        return (await this.request('GET', `/agents/requests/${encodeURIComponent(id)}`)).request;
+    }
+    async approveAgent(id) {
+        const { agent } = await this.request('POST', `/agents/requests/${encodeURIComponent(id)}/approve`);
+        if (this.agents)
+            this.agents = [...this.agents.filter((a) => a.id !== agent.id), agent];
+        return agent;
+    }
+    async denyAgent(id) {
+        await this.request('DELETE', `/agents/requests/${encodeURIComponent(id)}`);
+    }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { VisualComments, pageOf, type VisualCommentsOptions, type SurfaceInfo, type CommentFilters } from './visual-comments.svelte.js';
+export { VisualComments, pageOf, type VisualCommentsOptions, type SurfaceInfo, type CommentFilters, type PresenceLocation } from './visual-comments.svelte.js';
 export type * from './shared/types.js';
 import { VisualComments, type VisualCommentsOptions } from './visual-comments.svelte.js';
 /** Adds comments to the page. Call once, in the browser. */

package/dist/server/env.d.ts

@@ -0,0 +1,78 @@
+import type { Viewer } from '../shared/types.js';
+import { type CommentsUser, type Handle } from './index.js';
+import { type CommentsEnv } from './variables.js';
+export { commentsVariables, type CommentsEnv, type CommentsEnvName } from './variables.js';
+export interface CommentsSignInOptions {
+    /**
+     * More host names the development sign-in works on, besides localhost: e.g.
+     * the machine's address on a private network, to open the dev server from
+     * another machine. Whoever reaches the site there can sign in as anyone.
+     */
+    devHosts?: string[];
+}
+export interface CommentsEnvOptions {
+    /**
+     * Whether the dev server is running: `dev` from `$app/env` (`$app/environment`
+     * before SvelteKit 3). Needed for `VISUAL_COMMENTS_ENABLED=dev`, and for the
+     * development sign-in.
+     */
+    dev?: boolean;
+    /**
+     * Sign people in to the comments apart from the site's own accounts, with
+     * `@cnvx/sign-in` (install it beside this package): at the provider of
+     * the `VISUAL_COMMENTS_OIDC_*` variables, or, while the dev server runs without
+     * them, with any name on localhost. Its routes are at `VISUAL_COMMENTS_AUTH`;
+     * its session is the `visual_comments_session` cookie. Without it, the site's
+     * own sign-in says who comments (`sveltekit(user)`).
+     */
+    signIn?: boolean | CommentsSignInOptions;
+}
+/** What the browser needs to reach the comments, for `<Comments config>` of `visual-comments/sveltekit`. */
+export interface CommentsClientConfig {
+    /** Where this site answers comment requests, e.g. `/_comments`. */
+    endpoint: string;
+    /** Where this site's sign-in routes are, e.g. `/auth`. */
+    auth: string;
+    /**
+     * Who is signed in to the comments, as the server knows it when the page
+     * loads (`load`): null for nobody, so the toolbar shows them at once.
+     * Undefined: the browser asks.
+     */
+    viewer?: Viewer | null;
+}
+export interface CommentsFromEnv {
+    /** Whether comments are on. */
+    readonly enabled: boolean;
+    /** For the browser, e.g. returned by the root layout's `load`. Null while comments are off. */
+    readonly client: CommentsClientConfig | null;
+    /**
+     * `client` with who is signed in to the comments' own sign-in, for the root
+     * layout's `load`: `load: (event) => comments.load(event)`. Without the own
+     * sign-in, or while off, it is `client`.
+     */
+    load(event: {
+        request: Request;
+    }): Promise<CommentsClientConfig | null>;
+    /** Answers comment requests as `user`; undefined for any other request, and for every request while off. */
+    handle(request: Request, user: CommentsUser): Promise<Response | undefined>;
+    /**
+     * SvelteKit's `handle` hook. With the comments' own sign-in, it answers its
+     * routes and comments as the person signed in there; put it first. Otherwise
+     * put it after the site's sign-in: by default the person is
+     * `event.locals.user`. While off it passes every request on.
+     */
+    sveltekit<E extends {
+        request: Request;
+        locals: object;
+    }>(user?: (event: E) => CommentsUser | Promise<CommentsUser>): Handle<E>;
+}
+/**
+ * Sets up comments from `VISUAL_COMMENTS_*` variables. They are off unless
+ * `VISUAL_COMMENTS_ENABLED` is `true`, or `dev` while the dev server runs;
+ * on, `VISUAL_COMMENTS_SERVER`, `VISUAL_COMMENTS_SPACE` and
+ * `VISUAL_COMMENTS_SECRET` must be set, and with `signIn` outside the dev
+ * server the `VISUAL_COMMENTS_OIDC_*` ones and `VISUAL_COMMENTS_SESSION_SECRET`.
+ * Throws on a missing or invalid value, so a deployment fails at start rather
+ * than when someone comments.
+ */
+export declare function commentsFromEnv(env: CommentsEnv, options?: CommentsEnvOptions): CommentsFromEnv;

package/dist/server/env.js

@@ -0,0 +1,94 @@
+// Comments set up from environment variables, so each deployment turns them on
+// or off without a new build: on in development and staging, say, and absent
+// in production. Off, the site answers no comment requests and the browser
+// never loads the comments' code. (To leave them out of a build altogether, see
+// `visual-comments/vite`.)
+import { commentsProxy } from './index.js';
+import { invalid, read } from './variables.js';
+export { commentsVariables } from './variables.js';
+/** The comments' own sign-in's cookie. */
+const COOKIE = 'visual_comments_session';
+const OIDC = ['VISUAL_COMMENTS_OIDC_ISSUER', 'VISUAL_COMMENTS_OIDC_CLIENT_ID', 'VISUAL_COMMENTS_OIDC_CLIENT_SECRET'];
+/**
+ * Sets up comments from `VISUAL_COMMENTS_*` variables. They are off unless
+ * `VISUAL_COMMENTS_ENABLED` is `true`, or `dev` while the dev server runs;
+ * on, `VISUAL_COMMENTS_SERVER`, `VISUAL_COMMENTS_SPACE` and
+ * `VISUAL_COMMENTS_SECRET` must be set, and with `signIn` outside the dev
+ * server the `VISUAL_COMMENTS_OIDC_*` ones and `VISUAL_COMMENTS_SESSION_SECRET`.
+ * Throws on a missing or invalid value, so a deployment fails at start rather
+ * than when someone comments.
+ */
+export function commentsFromEnv(env, options = {}) {
+    const flag = read(env, 'VISUAL_COMMENTS_ENABLED') ?? 'false';
+    if (flag === 'dev' && options.dev === undefined) {
+        throw invalid('VISUAL_COMMENTS_ENABLED', 'is dev, so commentsFromEnv needs { dev }: `dev` from $app/env');
+    }
+    const enabled = flag === 'true' || (flag === 'dev' && options.dev === true);
+    if (!enabled) {
+        return {
+            enabled: false,
+            client: null,
+            load: async () => null,
+            handle: async () => undefined,
+            sveltekit: () => ({ event, resolve }) => Promise.resolve(resolve(event))
+        };
+    }
+    const required = (name) => read(env, name) ?? (() => { throw invalid(name, 'must be set while comments are on'); })();
+    const path = (read(env, 'VISUAL_COMMENTS_PATH') ?? '/_comments').replace(/(.)\/+$/, '$1');
+    const auth = (read(env, 'VISUAL_COMMENTS_AUTH') ?? '/auth').replace(/(.)\/+$/, '$1');
+    const proxy = commentsProxy({
+        server: required('VISUAL_COMMENTS_SERVER'),
+        space: required('VISUAL_COMMENTS_SPACE'),
+        secret: required('VISUAL_COMMENTS_SECRET'),
+        path
+    });
+    const client = { endpoint: path, auth };
+    if (!options.signIn)
+        return { enabled: true, client, load: async () => client, handle: proxy.handle, sveltekit: proxy.sveltekit };
+    // The comments' own sign-in: at the provider, or in development with any name.
+    const provider = OIDC.some((name) => read(env, name)) || !options.dev;
+    const [issuer, clientId, clientSecret] = OIDC.map((name) => (provider ? required(name) : undefined));
+    // In development the space's secret makes the key when there is no session secret, so the
+    // sessions outlast restarts of the dev server.
+    const secret = provider
+        ? required('VISUAL_COMMENTS_SESSION_SECRET')
+        : read(env, 'VISUAL_COMMENTS_SESSION_SECRET') ?? `visual-comments dev sign-in:${required('VISUAL_COMMENTS_SECRET')}`;
+    const devHosts = typeof options.signIn === 'object' ? options.signIn.devHosts : undefined;
+    let module;
+    // Loaded on the first request, so sites without it can use the rest of this module.
+    const load = () => (module ??= import('@cnvx/sign-in/server').then(({ createSignIn, withCookies }) => ({
+        signIn: createSignIn({ issuer, clientId, clientSecret, secret, path: auth, cookie: COOKIE, devLogin: !provider, devHosts }),
+        withCookies
+    }), (error) => { throw new Error('The comments’ own sign-in needs @cnvx/sign-in: install it beside visual-comments.', { cause: error }); }));
+    // One check per request: the layout's `load` and the hook share it, and the hook sets the
+    // cookies it renews.
+    const sessions = new WeakMap();
+    const check = (request) => {
+        let session = sessions.get(request);
+        if (!session)
+            sessions.set(request, (session = load().then(({ signIn }) => signIn.check(request))));
+        return session;
+    };
+    return {
+        enabled: true,
+        client,
+        load: async ({ request }) => ({ ...client, viewer: (await check(request)).user ?? null }),
+        handle: proxy.handle,
+        sveltekit: () => async ({ event, resolve }) => {
+            const { signIn, withCookies } = await load();
+            const answered = await signIn.handle(event.request);
+            if (answered)
+                return answered;
+            const { pathname } = new URL(event.request.url);
+            if (pathname === path || pathname.startsWith(`${path}/`)) {
+                const session = await check(event.request);
+                const response = await proxy.handle(event.request, session.user);
+                if (response)
+                    return withCookies(response, session.cookies);
+            }
+            const response = await resolve(event);
+            const session = sessions.get(event.request);
+            return session ? withCookies(response, (await session).cookies) : response;
+        }
+    };
+}

package/dist/server/index.d.ts

@@ -31,3 +31,4 @@ export declare function commentsProxy(options: CommentsProxyOptions): {
         locals: object;
     }>(user?: (event: E) => CommentsUser | Promise<CommentsUser>) => Handle<E>;
 };
+export { commentsFromEnv, commentsVariables, type CommentsClientConfig, type CommentsEnv, type CommentsEnvName, type CommentsEnvOptions, type CommentsFromEnv, type CommentsSignInOptions } from './env.js';

package/dist/server/index.js

@@ -1,7 +1,8 @@
 // For the site's server: passes the browser's comment requests on to the
-// comment server, with the space's secret and the person signed in on the site.
+// comment server, with the space's secret and the person signed in on the site,
+// or the token of an agent of the space.
 // Uses only the Fetch API, so it runs in Node, Bun, Deno and Workers.
-import { USER_HEADER } from '../shared/protocol.js';
+import { AGENT_HEADER, AGENT_TOKEN_PREFIX, USER_HEADER } from '../shared/protocol.js';
 const REQUEST_HEADERS = ['content-type', 'accept', 'last-event-id'];
 const RESPONSE_HEADERS = ['content-type', 'cache-control', 'content-security-policy', 'x-content-type-options', 'x-accel-buffering'];
 export function commentsProxy(options) {
@@ -19,7 +20,12 @@ export function commentsProxy(options) {
             if (value)
                 headers.set(name, value);
         }
-        if (user) {
+        // An agent's token speaks for the agent, even from a browser where someone is signed in.
+        // Any other bearer token is the site's business and stays here.
+        const token = /^Bearer (\S+)$/.exec(request.headers.get('authorization') ?? '')?.[1];
+        if (token?.startsWith(AGENT_TOKEN_PREFIX))
+            headers.set(AGENT_HEADER, token);
+        else if (user) {
             const { sub, name, email, picture } = user;
             headers.set(USER_HEADER, base64url(JSON.stringify({ sub, name, email, picture })));
         }
@@ -65,3 +71,4 @@ function base64url(text) {
         binary += String.fromCharCode(byte);
     return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
+export { commentsFromEnv, commentsVariables } from './env.js';

package/dist/server/variables.d.ts

@@ -0,0 +1,28 @@
+/** The variables `commentsFromEnv` reads. */
+export type CommentsEnvName = 'VISUAL_COMMENTS_ENABLED' | 'VISUAL_COMMENTS_SERVER' | 'VISUAL_COMMENTS_SPACE' | 'VISUAL_COMMENTS_SECRET' | 'VISUAL_COMMENTS_PATH' | 'VISUAL_COMMENTS_AUTH' | 'VISUAL_COMMENTS_OIDC_ISSUER' | 'VISUAL_COMMENTS_OIDC_CLIENT_ID' | 'VISUAL_COMMENTS_OIDC_CLIENT_SECRET' | 'VISUAL_COMMENTS_SESSION_SECRET';
+/**
+ * Where the variables come from: `process.env`, SvelteKit's `$app/env/private`
+ * (`import * as env from '$app/env/private'`) or `$env/dynamic/private` before
+ * SvelteKit 3. Values that are not strings count as unset.
+ */
+export type CommentsEnv = {
+    readonly [K in CommentsEnvName]?: unknown;
+};
+export declare function invalid(name: CommentsEnvName, message: string): Error;
+/** A variable's value, checked; undefined when unset or empty. */
+export declare function read(env: CommentsEnv, name: CommentsEnvName): string | undefined;
+/**
+ * The variables for SvelteKit's `src/env.ts`, all private and read when the
+ * app starts, so one build serves every deployment:
+ *
+ * ```ts
+ * import { defineEnvVars } from '@sveltejs/kit/env';
+ * import { commentsVariables } from 'visual-comments/server';
+ *
+ * export const variables = defineEnvVars({ ...commentsVariables });
+ * ```
+ */
+export declare const commentsVariables: { readonly [K in CommentsEnvName]: {
+    description: string;
+    schema: (value: string | undefined) => string | undefined;
+}; };

package/dist/server/variables.js

@@ -0,0 +1,73 @@
+// The variables `commentsFromEnv` reads, with their checks. Kept apart from it, so a build
+// without the comments (`visual-comments/vite`) still declares them.
+const isPath = (value) => (value.startsWith('/') ? undefined : 'must be a path that starts with /, e.g. /_comments');
+const isUrl = (value) => (URL.canParse(value) && /^https?:$/.test(new URL(value).protocol) ? undefined : 'must be an http(s) URL');
+const isSecret = (value) => (value.length >= 32 ? undefined : 'must be at least 32 characters');
+const CHECKS = {
+    VISUAL_COMMENTS_ENABLED: {
+        description: 'Whether comments are on: `true`, `false` or `dev` (only while the dev server runs). Default `false`.',
+        check: (value) => (['true', 'false', 'dev'].includes(value) ? undefined : 'must be true, false or dev')
+    },
+    VISUAL_COMMENTS_SERVER: {
+        description: 'The comment server, e.g. `https://comments.convex.works`. Required while comments are on.',
+        check: isUrl
+    },
+    VISUAL_COMMENTS_SPACE: {
+        description: "The site's space on the comment server. Required while comments are on."
+    },
+    VISUAL_COMMENTS_SECRET: {
+        description: "The space's secret, at least 32 characters. Required while comments are on. Never sent to browsers.",
+        check: isSecret
+    },
+    VISUAL_COMMENTS_PATH: {
+        description: 'Where the site answers comment requests, base path included. Default `/_comments`.',
+        check: isPath
+    },
+    VISUAL_COMMENTS_AUTH: {
+        description: "Where the site's sign-in routes are, base path included. Default `/auth`.",
+        check: isPath
+    },
+    VISUAL_COMMENTS_OIDC_ISSUER: {
+        description: "With the comments' own sign-in: the OpenID Connect provider, e.g. `https://id.convex.works`.",
+        check: isUrl
+    },
+    VISUAL_COMMENTS_OIDC_CLIENT_ID: {
+        description: "With the comments' own sign-in: their confidential client at the provider."
+    },
+    VISUAL_COMMENTS_OIDC_CLIENT_SECRET: {
+        description: "With the comments' own sign-in: that client's secret."
+    },
+    VISUAL_COMMENTS_SESSION_SECRET: {
+        description: "With the comments' own sign-in: encrypts their session cookie. At least 32 characters. Optional under the dev server.",
+        check: isSecret
+    }
+};
+export function invalid(name, message) {
+    return new Error(`${name} ${message}.`);
+}
+/** A variable's value, checked; undefined when unset or empty. */
+export function read(env, name) {
+    const value = env[name];
+    if (typeof value !== 'string' || value === '')
+        return undefined;
+    const problem = CHECKS[name].check?.(value);
+    if (problem)
+        throw invalid(name, problem);
+    return value;
+}
+/**
+ * The variables for SvelteKit's `src/env.ts`, all private and read when the
+ * app starts, so one build serves every deployment:
+ *
+ * ```ts
+ * import { defineEnvVars } from '@sveltejs/kit/env';
+ * import { commentsVariables } from 'visual-comments/server';
+ *
+ * export const variables = defineEnvVars({ ...commentsVariables });
+ * ```
+ */
+export const commentsVariables = Object.fromEntries(Object.entries(CHECKS).map(([name, { description }]) => [name, {
+        description,
+        // Optional, and checked when the app starts.
+        schema: (value) => read({ [name]: value }, name)
+    }]));

package/dist/shared/protocol.d.ts

@@ -1,2 +1,6 @@
 /** The header with who is signed in on the site: their `Viewer` as base64url-encoded JSON. */
 export declare const USER_HEADER = "visual-comments-user";
+/** The header with an agent's token, passed on by the site's server instead of `USER_HEADER`. */
+export declare const AGENT_HEADER = "visual-comments-agent";
+/** Agent tokens start with this, so the site's server can tell them from other bearer tokens. */
+export declare const AGENT_TOKEN_PREFIX = "vca_";

package/dist/shared/protocol.js

@@ -1,3 +1,7 @@
 // How a site's server talks to the comment server.
 /** The header with who is signed in on the site: their `Viewer` as base64url-encoded JSON. */
 export const USER_HEADER = 'visual-comments-user';
+/** The header with an agent's token, passed on by the site's server instead of `USER_HEADER`. */
+export const AGENT_HEADER = 'visual-comments-agent';
+/** Agent tokens start with this, so the site's server can tell them from other bearer tokens. */
+export const AGENT_TOKEN_PREFIX = 'vca_';

package/dist/shared/types.d.ts

@@ -3,6 +3,13 @@ export interface Author {
     sub: string;
     name: string;
     picture?: string;
+    /** Set when the author is an agent: it joined the space when a person approved it. */
+    agent?: {
+        addedBy: {
+            sub: string;
+            name: string;
+        };
+    };
 }
 /** The person signed in on the site. */
 export interface Viewer extends Author {
@@ -91,3 +98,60 @@ export interface NewThreadInput {
     body: string;
     images?: number[];
 }
+/** What someone present is doing. */
+export type PresenceState = 'viewing' | 'typing' | 'working';
+/** Someone in the space right now: one per browser tab, or one per task of an agent. */
+export interface Participant {
+    /** Stable while they stay. */
+    id: string;
+    author: Author;
+    state: PresenceState;
+    page?: string;
+    surface?: string;
+    thread?: number;
+    /** What they are doing, in their words, e.g. `Tightening the table`. */
+    note?: string;
+    /** When the state last changed, in milliseconds since the epoch. */
+    since: number;
+}
+/** What a client sends to `POST /presence`. */
+export interface PresenceUpdate {
+    /** A browser's connection, from the event stream's `hello` event. Agents leave it out. */
+    connection?: string;
+    /** Agents only: one participant per key, so one agent can work on several things at once. Default `''`. */
+    key?: string;
+    /** `gone` removes the participant. */
+    state: PresenceState | 'gone';
+    page?: string;
+    surface?: string;
+    thread?: number;
+    note?: string;
+}
+/** An agent of the space. */
+export interface Agent {
+    id: string;
+    name: string;
+    addedBy: {
+        sub: string;
+        name: string;
+    };
+    createdAt: number;
+    lastSeenAt: number | null;
+}
+/** An agent asking to join the space, waiting for a person to approve it. */
+export interface AgentRequest {
+    id: string;
+    name: string;
+    /** Shown to the agent and to the person approving, so both know it is the same request. */
+    code: string;
+    expiresAt: number;
+}
+/** The request as the agent that asked gets it: with the secret it collects its token with. */
+export interface NewAgentRequest extends AgentRequest {
+    secret: string;
+}
+/** What `GET /agent/next` answers: the threads with something new for the agent. */
+export interface AgentInbox {
+    threads: CommentThread[];
+    participants: Participant[];
+}