@dzbot/dzstudio-mcp 0.0.0-stage → 0.1.1

package/dist/mcp/agent.js

@@ -0,0 +1,1148 @@
+import { join } from 'node:path';
+import { SessionStore } from '../config/sessions.js';
+import { agentClient, CollabClient } from '../protocol/client.js';
+import { AlreadyRunning, CollabSession, displayName, STATUS_MAX_BYTES, } from '../protocol/session.js';
+import { CollabError, HttpTransport, UnreachableError } from '../protocol/transport.js';
+import { BuildError, normalizeAngle, OpBuilder } from '../scene/edits.js';
+import { readFloat32, readVec3, writeFloat32, writeVec3 } from '../scene/float32.js';
+import { PROJECT_ID } from '../scene/ids.js';
+import { loadProject, LoadRefused, neededForLoad } from '../scene/projectload.js';
+export const MAX_HELD = 20_000;
+export const PAGE_SIZE = 500;
+export const IDLE_LEAVE_MS = 30 * 60_000;
+/** The project state of a session is written to disk at most this often while operations arrive. */
+export const STATE_SAVE_MS = 5000;
+const GROUP_COLOURS = ['#60A5FA', '#F87171', '#34D399', '#FBBF24', '#A78BFA', '#F472B6', '#22D3EE', '#FB923C'];
+/** A failure the agent should read: the message is the tool result. */
+export class ToolError extends Error {
+}
+const PHASE_TEXT = { waiting: 'waiting for work', working: 'working', review: 'waiting for review' };
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+function validateStatus(status) {
+    if (/[\r\n]/.test(status) || /[\u0000-\u001f\u007f]/.test(status))
+        throw new ToolError('Status must be one line');
+    if (Buffer.byteLength(status, 'utf8') > STATUS_MAX_BYTES)
+        throw new ToolError('Status too long (at most 200 bytes)');
+}
+/** A float32 as the JSON number of its shortest text, so 1234.5679 does not show as 1234.56787109375. */
+function f32(x) {
+    return Number(writeFloat32(x));
+}
+function vec(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        return readVec3(text).map(f32);
+    }
+    catch {
+        return text;
+    }
+}
+function num(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        return f32(readFloat32(text));
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Everything the tools do, without the MCP wiring: servers and logins, the sessions the agent is in, and the edits
+ * it makes in them.
+ */
+export class Agent {
+    opts;
+    sessions = new Map();
+    current;
+    nextHandle = 1;
+    logins = new Map();
+    infos = new Map();
+    agentEvents = [];
+    idleTimer;
+    saved;
+    /** Settles once the sessions of the last run are restored (or given up); tools wait for it. */
+    ready;
+    /** The class data, for opening a project from its files; set by the world tools. */
+    classes;
+    constructor(opts) {
+        this.opts = opts;
+        this.idleTimer = setInterval(() => void this.leaveIdle(), 60_000);
+        this.idleTimer.unref();
+        this.saved = new SessionStore(join(opts.store.dir, 'sessions'));
+        this.ready = this.restoreAll();
+    }
+    get store() {
+        return this.opts.store;
+    }
+    client(server) {
+        return new CollabClient(this.opts.transport ? this.opts.transport(server.url) : new HttpTransport(server.url));
+    }
+    credential(server) {
+        const c = this.store.credential(server.name);
+        if (!c)
+            throw new ToolError(`Not signed in to ${server.name} — call login`);
+        return c;
+    }
+    async info(server, fresh = false) {
+        const cached = this.infos.get(server.name);
+        if (!fresh && cached && Date.now() - cached.at < 60_000)
+            return cached.info;
+        try {
+            const info = await this.client(server).info();
+            this.infos.set(server.name, { info, at: Date.now() });
+            return info;
+        }
+        catch (e) {
+            throw new ToolError(e instanceof UnreachableError ? 'Server not reachable' : e.message);
+        }
+    }
+    /** Runs a request that needs the login; a rejected token drops the stored one. */
+    async authed(server, fn) {
+        const cred = this.credential(server);
+        try {
+            return await fn(this.client(server), cred.token);
+        }
+        catch (e) {
+            if (e instanceof CollabError && ['token_invalid', 'token_expired', 'auth_required'].includes(e.code)) {
+                this.store.setCredential(server.name, undefined);
+                throw new ToolError(`Not signed in to ${server.name} — call login`);
+            }
+            if (e instanceof UnreachableError)
+                throw new ToolError('Server not reachable');
+            throw e;
+        }
+    }
+    close() {
+        clearInterval(this.idleTimer);
+        for (const r of this.sessions.values())
+            clearTimeout(r.stateTimer);
+    }
+    /**
+     * Stops without leaving: every session is saved with its state, and the next start returns to it with `resume`.
+     * The server takes the agent out on its own if it does not come back.
+     */
+    async shutdown() {
+        this.close();
+        await this.ready.catch(() => undefined);
+        for (const r of this.sessions.values()) {
+            const c = r.collab;
+            if (!c || !c.active || r.idleLeft)
+                continue;
+            this.persist(r);
+            this.writeState(r);
+            await c.stop();
+        }
+    }
+    // ------------------------------------------------------------ returning after a restart
+    persist(r) {
+        const c = r.collab;
+        if (!c || !c.participantId)
+            return;
+        this.saved.save({
+            handle: r.handle,
+            server: r.server,
+            sessionId: r.sessionId,
+            projectName: r.projectName,
+            map: r.map,
+            participantId: c.participantId,
+            prefix: c.prefix,
+            clientSeq: c.nextClientSeq,
+            lockSeq: c.lockSeq,
+            phase: c.phase,
+            status: c.status,
+            lastWorkMs: r.lastWorkMs,
+        });
+    }
+    writeState(r) {
+        clearTimeout(r.stateTimer);
+        r.stateTimer = undefined;
+        const c = r.collab;
+        if (c?.active)
+            this.saved.saveState(r.server, r.sessionId, c.appliedSeq, c.scene.stateText());
+    }
+    /** Keeps a session on disk from now on: counters at once, the state when it changed, at most every few seconds. */
+    attach(r) {
+        const c = r.collab;
+        r.saved = undefined;
+        c.onPersist = (what) => {
+            if (what === 'meta')
+                this.persist(r);
+            else if (!r.stateTimer) {
+                r.stateTimer = setTimeout(() => this.writeState(r), STATE_SAVE_MS);
+                r.stateTimer.unref();
+            }
+        };
+        this.persist(r);
+        this.writeState(r);
+    }
+    /** The agent is out of a session for good. */
+    drop(r) {
+        clearTimeout(r.stateTimer);
+        this.saved.remove(r.server, r.sessionId);
+        this.sessions.delete(r.handle);
+        if (this.current === r.handle)
+            this.current = undefined;
+    }
+    async restoreAll() {
+        const limit = this.opts.idleLeaveMs ?? IDLE_LEAVE_MS;
+        for (const s of this.saved.list().sort((a, b) => a.handle.localeCompare(b.handle, 'en', { numeric: true }))) {
+            const handle = this.sessions.has(s.handle) || !/^s[0-9]+$/.test(s.handle) ? `s${this.nextHandle}` : s.handle;
+            this.nextHandle = Math.max(this.nextHandle, Number(handle.slice(1)) + 1);
+            const r = {
+                handle,
+                server: s.server,
+                sessionId: s.sessionId,
+                projectName: s.projectName,
+                map: s.map,
+                collab: undefined,
+                idleLeft: false,
+                lastWorkMs: s.lastWorkMs,
+                saved: s,
+            };
+            this.sessions.set(handle, r);
+            if (s.phase === 'waiting' && Date.now() - s.lastWorkMs >= limit) {
+                // it would have left by now
+                await this.leaveSaved(r, s);
+                this.drop(r);
+                continue;
+            }
+            this.current ??= handle;
+            await this.restore(r).catch(() => undefined);
+        }
+    }
+    async leaveSaved(r, s) {
+        try {
+            const server = this.store.server(r.server);
+            const token = this.store.credential(server.name)?.token;
+            if (token)
+                await this.client(server).request('session/leave', { sessionId: s.sessionId, participantId: s.participantId }, token);
+        }
+        catch {
+            // the server takes it out on its own
+        }
+    }
+    /** Back into a saved session: with `resume` from the saved state, otherwise joined anew. */
+    async restore(r) {
+        const s = r.saved;
+        let server;
+        let cred;
+        try {
+            server = this.store.server(r.server);
+            cred = this.credential(server);
+        }
+        catch (e) {
+            this.drop(r);
+            throw e;
+        }
+        try {
+            const back = await CollabSession.rejoin(this.sessionOptions(server, r, cred), s, this.saved.state(r.server, r.sessionId));
+            if (back) {
+                r.collab = back;
+                this.agentEvents.push(`[${r.handle}] Back in ${r.projectName || r.sessionId} after a restart`);
+            }
+            else {
+                r.collab = await this.connect(server, r, cred);
+                r.collab.setPhase(s.phase, s.status);
+                this.agentEvents.push(`[${r.handle}] Joined ${r.projectName || r.sessionId} again after a restart (the server could not continue the old place)`);
+            }
+            this.attach(r);
+        }
+        catch (e) {
+            if (e instanceof UnreachableError || (e instanceof ToolError && e.message === 'Server not reachable'))
+                throw e;
+            this.drop(r);
+            const why = e instanceof CollabError && e.code === 'not_participant' ? 'the agent was removed' : e.message;
+            this.agentEvents.push(`[${r.handle}] Could not return to ${r.projectName || r.sessionId} after a restart: ${why}`);
+            throw e;
+        }
+    }
+    // ------------------------------------------------------------ events
+    /** Events since the last result, of every session; applies what they mean for the phase. */
+    collectEvents() {
+        const out = this.agentEvents.splice(0);
+        for (const r of this.sessions.values()) {
+            const c = r.collab;
+            if (!c)
+                continue;
+            for (const e of c.drainEvents()) {
+                this.onEvent(r, c, e);
+                out.push(`[${r.handle}] ${e.text}`);
+            }
+        }
+        return out;
+    }
+    onEvent(r, c, e) {
+        if (e.kind === 'saved' && c.phase === 'review' && Number(e.data?.savedSeq) >= c.lastOwnSeq)
+            c.setPhase('waiting', '');
+        if (e.kind === 'ended' || e.kind === 'removed')
+            this.drop(r);
+    }
+    async waitEvents(handle, ms) {
+        const first = this.collectEvents();
+        if (first.length || ms <= 0)
+            return first;
+        const records = handle ? [this.record(handle)] : [...this.sessions.values()];
+        const live = records.map((r) => r.collab).filter((c) => !!c);
+        if (!live.length)
+            return [];
+        await Promise.race(live.map((c) => c.waitForEvents(ms)));
+        return this.collectEvents();
+    }
+    // ------------------------------------------------------------ servers and login
+    async listServers() {
+        const servers = this.store.load().servers;
+        const rows = await Promise.all(servers.map(async (s) => {
+            const cred = this.store.credential(s.name);
+            const row = { name: s.name, url: s.url, signedIn: !!cred };
+            if (cred)
+                row.signedInAs = cred.name;
+            try {
+                const info = await this.info(s, true);
+                row.agents = info.capabilities.includes('agents');
+                row.reachable = true;
+            }
+            catch {
+                row.reachable = false;
+            }
+            return row;
+        }));
+        return { text: rows.length ? `${plural(rows.length, 'server')}` : 'No server configured — call add_server', data: { servers: rows } };
+    }
+    async addServer(name, url) {
+        if (this.store.load().servers.some((s) => s.name === name))
+            throw new ToolError(`A server named ${name} already exists`);
+        const entry = { name, url };
+        let info;
+        try {
+            info = await this.client(entry).info();
+        }
+        catch {
+            throw new ToolError('Server not reachable');
+        }
+        let saved;
+        try {
+            saved = this.store.addServer(name, url);
+        }
+        catch (e) {
+            throw new ToolError(e.message);
+        }
+        this.infos.set(name, { info, at: Date.now() });
+        const agents = info.capabilities.includes('agents');
+        return {
+            text: `Added ${name} (${info.name})${agents ? '' : ' — this server knows no agents yet; joining its sessions is not possible'}`,
+            data: { name, url: saved.url, serverName: info.name, agents, login: info.auth.map((a) => a.method) },
+        };
+    }
+    async login(serverName, displayName) {
+        const server = this.resolveServer(serverName);
+        const info = await this.info(server, true);
+        const client = this.client(server);
+        const methods = info.auth.map((a) => a.method);
+        if (!methods.includes('code') || !info.capabilities.includes('auth.code')) {
+            if (methods.includes('name') && displayName) {
+                const res = await client.nameLogin(displayName, agentClient(this.store.load().agentName));
+                this.store.setCredential(server.name, { token: res.token, name: res.name });
+                return { text: `Signed in to ${server.name} as ${res.name}` };
+            }
+            if (methods.includes('name'))
+                throw new ToolError(`${server.name} only offers login by name — call login with a name`);
+            throw new ToolError(`${server.name} offers no login this MCP can use (code login is needed)`);
+        }
+        const pending = this.logins.get(server.name);
+        if (!pending || pending.expiresAt <= Date.now()) {
+            const start = await client.codeStart(agentClient(this.store.load().agentName));
+            this.logins.set(server.name, {
+                loginCode: start.loginCode,
+                url: start.url,
+                expiresAt: Date.now() + start.expiresInSeconds * 1000,
+                intervalMs: start.intervalSeconds * 1000,
+            });
+            const code = start.loginCode.length === 8 ? `${start.loginCode.slice(0, 4)}-${start.loginCode.slice(4)}` : start.loginCode;
+            return {
+                text: `Ask the user to open ${start.url} and confirm the code ${code}. Then call login again to finish.`,
+                data: { code, url: start.url, expiresInSeconds: start.expiresInSeconds },
+            };
+        }
+        const deadline = Math.min(pending.expiresAt, Date.now() + (this.opts.loginWaitMs ?? 60_000));
+        for (;;) {
+            const st = await client.codePoll(pending.loginCode);
+            if (st.state === 'confirmed') {
+                this.logins.delete(server.name);
+                const cred = { token: st.token, name: st.name };
+                if (st.expiresInSeconds !== undefined)
+                    cred.expiresAt = Date.now() + st.expiresInSeconds * 1000;
+                this.store.setCredential(server.name, cred);
+                return { text: `Signed in as ${st.name}` };
+            }
+            if (st.state === 'expired') {
+                this.logins.delete(server.name);
+                throw new ToolError('Code expired');
+            }
+            if (st.state === 'denied') {
+                this.logins.delete(server.name);
+                throw new ToolError('Sign-in denied');
+            }
+            if (Date.now() + pending.intervalMs > deadline)
+                break;
+            await new Promise((r) => setTimeout(r, pending.intervalMs));
+        }
+        return { text: `Still waiting for the confirmation at ${pending.url} — call login again after the user confirmed` };
+    }
+    resolveServer(name) {
+        try {
+            return this.store.server(name);
+        }
+        catch (e) {
+            throw new ToolError(e.message);
+        }
+    }
+    // ------------------------------------------------------------ projects and sessions
+    async listProjects(serverName) {
+        const server = this.resolveServer(serverName);
+        const info = await this.info(server);
+        return this.authed(server, async (client, token) => {
+            const sessions = await client.sessionsList(token);
+            const projects = info.capabilities.includes('hosted') ? (await client.projectList(token)).projects : [];
+            return {
+                text: `${plural(projects.length, 'project')}, ${plural(sessions.length, 'session')} to join on ${server.name}`,
+                data: {
+                    projects: projects.map((p) => ({
+                        key: p.hostedRef?.key,
+                        name: p.projectName,
+                        map: p.map,
+                        sessionRunning: typeof p.sessionId === 'string',
+                        canSave: !!p.canSave,
+                    })),
+                    sessions: sessions.map((s) => ({
+                        sessionId: s.sessionId,
+                        kind: s.kind,
+                        project: s.projectName,
+                        map: s.map,
+                        host: s.host?.name,
+                        participants: s.participants,
+                        access: s.access,
+                    })),
+                },
+            };
+        });
+    }
+    async openProject(serverName, project) {
+        const server = this.resolveServer(serverName);
+        const info = await this.info(server);
+        if (!info.capabilities.includes('hosted'))
+            throw new ToolError(`${server.name} has no projects on the server`);
+        if (!info.capabilities.includes('agents'))
+            throw new ToolError('Server knows no agents');
+        const found = await this.authed(server, async (client, token) => {
+            const { projects } = await client.projectList(token);
+            const want = project.toLowerCase();
+            const p = projects.find((x) => x.hostedRef?.key === project) ?? projects.find((x) => String(x.projectName).toLowerCase() === want);
+            if (!p)
+                throw new ToolError(`No project ${project} on ${server.name}`);
+            if (typeof p.sessionId === 'string')
+                return { sessionId: p.sessionId };
+            const running = await client.sessionsList(token, p.hostedRef);
+            if (running[0])
+                return { sessionId: running[0].sessionId };
+            return { project: p };
+        });
+        if (found.sessionId)
+            return this.joinSession(server.name, found.sessionId);
+        return this.openFromFiles(server, found.project);
+    }
+    /** No session is running: load the files, build the state as dzStudio does, and start a session with it. */
+    async openFromFiles(server, p) {
+        const notSaver = `No session is running for ${p.projectName}, and only someone who may save can start one. Ask a person to open it in dzStudio.`;
+        if (!p.canSave)
+            throw new ToolError(notSaver);
+        const { head, files } = await this.authed(server, (client, token) => client.projectLoad(token, p.hostedRef, neededForLoad)).catch((e) => {
+            if (e instanceof CollabError)
+                throw new ToolError(`Cannot open ${p.projectName}: ${e.message}`);
+            throw e;
+        });
+        if (typeof head.sessionId === 'string')
+            return this.joinSession(server.name, head.sessionId);
+        if (!head.canSave)
+            throw new ToolError(notSaver);
+        const lookup = this.classes ? await this.classes().catch(() => null) : null;
+        const rec = {
+            handle: `s${this.nextHandle++}`,
+            server: server.name,
+            sessionId: '',
+            projectName: String(head.projectName ?? p.projectName ?? ''),
+            map: String(head.map ?? p.map ?? ''),
+            collab: undefined,
+            idleLeft: false,
+            lastWorkMs: Date.now(),
+        };
+        const by = this.author(rec);
+        let loaded;
+        const build = (scene) => {
+            loaded = loadProject({ files, ids: scene.ids, ...by, ...(lookup ? { classKnown: (n) => lookup.knows(n) } : {}) });
+            const res = scene.apply(loaded.op);
+            if (res.result !== 'applied')
+                throw new LoadRefused(`The project's state does not open (${res.result})`);
+        };
+        const cred = this.credential(server);
+        try {
+            rec.collab = await CollabSession.createHosted(this.sessionOptions(server, rec, cred), { projectName: rec.projectName, map: rec.map, hostedRef: p.hostedRef, hostedRevision: String(head.hostedRevision ?? '') }, build);
+        }
+        catch (e) {
+            if (e instanceof LoadRefused)
+                throw new ToolError(`Cannot open ${rec.projectName} from its files: ${e.message}`);
+            if (e instanceof AlreadyRunning)
+                return this.joinSession(server.name, e.sessionId);
+            this.joinError(server, e);
+        }
+        rec.sessionId = rec.collab.sessionId;
+        this.sessions.set(rec.handle, rec);
+        this.current = rec.handle;
+        this.attach(rec);
+        const notes = loaded.notes;
+        return {
+            text: `Opened ${rec.projectName} from its files (${plural(loaded.groups, 'group')}, ${plural(loaded.objects, 'object')}) ` +
+                `and started a session as ${rec.handle}; it is the current session` +
+                (notes.length ? `. On opening: ${notes.join('; ')}` : ''),
+            data: this.sessionRow(rec),
+        };
+    }
+    async joinSession(serverName, sessionId, code) {
+        const server = this.resolveServer(serverName);
+        const info = await this.info(server, true);
+        if (!info.capabilities.includes('agents'))
+            throw new ToolError('Server knows no agents');
+        const cred = this.credential(server);
+        let target = sessionId;
+        if (code) {
+            const res = await this.authed(server, (client, token) => client.inviteRedeem(token, code)).catch((e) => {
+                if (e instanceof CollabError)
+                    throw new ToolError(e.code === 'invite_invalid' || e.code === 'invite_used'
+                        ? 'This code is not valid (any more) — ask for a new one'
+                        : `Cannot join: ${e.message}`);
+                throw e;
+            });
+            target = res.sessionId;
+        }
+        if (!target)
+            throw new ToolError('Name a session id or an invitation code');
+        for (const r of this.sessions.values()) {
+            if (r.server === server.name && r.sessionId === target && r.collab?.active) {
+                this.current = r.handle;
+                return { text: `Already in this session as ${r.handle}`, data: this.sessionRow(r) };
+            }
+        }
+        const listed = await this.authed(server, (client, token) => client.sessionsList(token)).catch(() => []);
+        const meta = listed.find((s) => s.sessionId === target);
+        const handle = `s${this.nextHandle++}`;
+        const rec = {
+            handle,
+            server: server.name,
+            sessionId: target,
+            projectName: meta?.projectName ?? '',
+            map: meta?.map ?? '',
+            collab: undefined,
+            idleLeft: false,
+            lastWorkMs: Date.now(),
+        };
+        rec.collab = await this.connect(server, rec, cred);
+        this.sessions.set(handle, rec);
+        this.current = handle;
+        this.attach(rec);
+        return { text: `Joined ${rec.projectName || target} as ${handle}; it is the current session`, data: this.sessionRow(rec) };
+    }
+    sessionOptions(server, rec, cred) {
+        return {
+            client: this.client(server),
+            token: () => this.store.credential(server.name)?.token ?? cred.token,
+            clientInfo: agentClient(this.store.load().agentName),
+            position: () => this.position(rec),
+            ...(this.opts.timing ? { timing: this.opts.timing } : {}),
+        };
+    }
+    /** Turns an error of joining or creating into the message for the agent. */
+    joinError(server, e) {
+        if (e instanceof CollabError) {
+            if (['token_invalid', 'token_expired', 'auth_required'].includes(e.code)) {
+                this.store.setCredential(server.name, undefined);
+                throw new ToolError(`Not signed in to ${server.name} — call login`);
+            }
+            if (e.code === 'session_unknown' || e.code === 'session_ended')
+                throw new ToolError('This session is already over');
+            if (e.code === 'session_full')
+                throw new ToolError('Session is full');
+            throw new ToolError(`Cannot join: ${e.error.message ?? e.code}`);
+        }
+        if (e instanceof UnreachableError)
+            throw new ToolError('Server not reachable');
+        throw e;
+    }
+    async connect(server, rec, cred) {
+        try {
+            return await CollabSession.join(this.sessionOptions(server, rec, cred), rec.sessionId);
+        }
+        catch (e) {
+            this.joinError(server, e);
+        }
+    }
+    position(rec) {
+        const c = rec.collab;
+        if (!c)
+            return undefined;
+        const ids = c.held.size ? [...c.held] : c.lastTouched;
+        return c.view((scene) => {
+            let min;
+            let max;
+            for (const id of ids) {
+                const p = vec(scene.get(id)?.fields.get('pos'));
+                if (!Array.isArray(p))
+                    continue;
+                min = min ? [Math.min(min[0], p[0]), Math.min(min[1], p[1]), Math.min(min[2], p[2])] : [...p];
+                max = max ? [Math.max(max[0], p[0]), Math.max(max[1], p[1]), Math.max(max[2], p[2])] : [...p];
+            }
+            if (!min || !max)
+                return undefined;
+            return [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2].map((v) => Math.fround(v));
+        });
+    }
+    record(handle) {
+        const h = handle ?? this.current;
+        if (!h)
+            throw new ToolError('Not in a session');
+        const r = this.sessions.get(h) ?? [...this.sessions.values()].find((x) => x.sessionId === h);
+        if (!r)
+            throw new ToolError(`Not in a session ${h}`);
+        return r;
+    }
+    /** The session for a tool that works in it; rejoins one the agent left while idle. */
+    async live(handle, work = true) {
+        const r = this.record(handle);
+        if (r.saved) {
+            await this.restore(r).catch((e) => {
+                throw e instanceof ToolError ? e : new ToolError(`Not back in the session after a restart: ${e.message}`);
+            });
+        }
+        if (r.idleLeft) {
+            const server = this.resolveServer(r.server);
+            r.collab = await this.connect(server, r, this.credential(server));
+            r.idleLeft = false;
+            this.attach(r);
+            this.agentEvents.push(`[${r.handle}] Joined again after leaving while idle`);
+        }
+        const c = r.collab;
+        if (!c || !c.active) {
+            const text = c?.stateText || 'Not in a session';
+            this.drop(r);
+            throw new ToolError(text);
+        }
+        if (work) {
+            r.lastWorkMs = Date.now();
+            this.persist(r);
+        }
+        return { r, c };
+    }
+    async leaveIdle() {
+        const limit = this.opts.idleLeaveMs ?? IDLE_LEAVE_MS;
+        for (const r of this.sessions.values()) {
+            const c = r.collab;
+            if (!c || r.idleLeft || !c.active || c.phase !== 'waiting')
+                continue;
+            if (Date.now() - r.lastWorkMs < limit)
+                continue;
+            await c.leave();
+            r.idleLeft = true;
+            clearTimeout(r.stateTimer);
+            this.saved.remove(r.server, r.sessionId);
+            this.agentEvents.push(`[${r.handle}] Left after ${Math.round(limit / 60_000)} minutes without work; joins again on the next task`);
+        }
+    }
+    /** Exposed for tests: run the idle check now. */
+    checkIdle() {
+        return this.leaveIdle();
+    }
+    sessionRow(r) {
+        const c = r.collab;
+        return {
+            session: r.handle,
+            sessionId: r.sessionId,
+            server: r.server,
+            project: r.projectName,
+            map: r.map,
+            kind: c?.kind,
+            phase: c ? PHASE_TEXT[c.phase] : undefined,
+            status: c?.status,
+            current: this.current === r.handle,
+            state: r.idleLeft ? 'left while idle' : r.saved ? 'not back yet after a restart' : c?.state,
+        };
+    }
+    listSessions() {
+        const rows = [...this.sessions.values()].map((r) => this.sessionRow(r));
+        return { text: rows.length ? plural(rows.length, 'session') : 'Not in any session', data: { sessions: rows } };
+    }
+    switchSession(handle) {
+        const r = this.record(handle);
+        this.current = r.handle;
+        return { text: `Current session: ${r.handle}`, data: this.sessionRow(r) };
+    }
+    async leaveSession(handle, confirm) {
+        const r = this.record(handle);
+        const c = r.collab;
+        if (c && c.active) {
+            const open = await c.flush(10_000);
+            if (open && !confirm)
+                throw new ToolError(`${plural(open, 'change')} did not reach the server — call leave_session with confirm to leave anyway`);
+            await c.leave();
+        }
+        this.drop(r);
+        return { text: `Left ${r.handle}` };
+    }
+    async sessionInfo(handle) {
+        const { r, c } = await this.live(handle, false);
+        const pres = new Map(c.presence.map((p) => [p.participantId, p]));
+        const held = new Map(c.lockHolders.map((h) => [h.participantId, (h.elements ?? []).length]));
+        const participants = c.participants.map((p) => {
+            const pr = pres.get(p.participantId) ?? {};
+            const row = {
+                name: displayName(p),
+                kind: p.kind === 'agent' ? 'agent' : 'human',
+                you: p.participantId === c.participantId,
+                colour: p.colour,
+                role: p.role,
+                state: pr.state,
+                held: held.get(p.participantId) ?? 0,
+            };
+            if (pr.position)
+                row.location = pr.position;
+            if (p.kind === 'agent') {
+                row.phase = PHASE_TEXT[pr.phase ?? 'waiting'] ?? pr.phase;
+                if (pr.status)
+                    row.status = pr.status;
+            }
+            return row;
+        });
+        const s = c.saving;
+        const saving = {};
+        if (s) {
+            saving.state = s.state;
+            if (s.unsavedCount !== undefined)
+                saving.unsavedChanges = s.unsavedCount;
+            if (s.savedBy)
+                saving.lastSavedBy = s.savedBy.name;
+            if (s.savedSecondsAgo !== undefined)
+                saving.savedSecondsAgo = s.savedSecondsAgo;
+        }
+        return {
+            text: `${r.projectName || r.sessionId}: ${plural(participants.length, 'participant')}, you are ${PHASE_TEXT[c.phase]}`,
+            data: {
+                ...this.sessionRow(r),
+                participants,
+                rights: { canSave: c.rights.canSave, canManage: c.rights.canManage, canInvite: c.rights.canInvite },
+                selection: c.selection.size,
+                saving,
+            },
+        };
+    }
+    // ------------------------------------------------------------ reading the scene
+    async readScene(handle) {
+        const { r, c } = await this.live(handle, false);
+        return c.view((scene) => {
+            const project = scene.get(PROJECT_ID);
+            const groups = scene
+                .children(PROJECT_ID)
+                .map((id) => scene.get(id))
+                .filter((g) => g.kind === 'core:group')
+                .map((g) => {
+                let min;
+                let max;
+                const kids = scene.children(g.id);
+                for (const k of kids) {
+                    const p = vec(scene.get(k)?.fields.get('pos'));
+                    if (!Array.isArray(p))
+                        continue;
+                    min = min ? [Math.min(min[0], p[0]), Math.min(min[1], p[2])] : [p[0], p[2]];
+                    max = max ? [Math.max(max[0], p[0]), Math.max(max[1], p[2])] : [p[0], p[2]];
+                }
+                const row = {
+                    id: g.id,
+                    name: g.fields.get('name') ?? '',
+                    color: g.fields.get('color'),
+                    objects: kids.length,
+                    hidden: g.hidden,
+                    locked: g.locked,
+                };
+                if (g.fields.get('unreadable') === '1')
+                    row.unreadable = true;
+                if (min && max)
+                    row.bounds = { minX: f32(min[0]), minZ: f32(min[1]), maxX: f32(max[0]), maxZ: f32(max[1]) };
+                return row;
+            });
+            const objects = groups.reduce((n, g) => n + g.objects, 0);
+            return {
+                text: `${r.projectName || 'Project'} on ${r.map || 'unknown map'}: ${plural(groups.length, 'group')}, ${plural(objects, 'object')}`,
+                data: { project: r.projectName, map: r.map, loot: project?.fields.get('lootEnabled') === 'true', groups, objects },
+            };
+        });
+    }
+    holderNames(c) {
+        const byPid = new Map(c.participants.map((p) => [p.participantId, displayName(p)]));
+        const out = new Map();
+        for (const h of c.lockHolders) {
+            if (h.participantId === c.participantId)
+                continue;
+            for (const el of h.elements ?? [])
+                out.set(el, byPid.get(h.participantId) ?? h.participantId);
+        }
+        return out;
+    }
+    objectRow(scene, el, holders, mine) {
+        const row = {
+            id: el.id,
+            class: el.fields.get('name') ?? '',
+            group: el.parent,
+            position: vec(el.fields.get('pos')),
+            orientation: vec(el.fields.get('ypr')),
+            scale: num(el.fields.get('scale')),
+            hidden: el.hidden,
+            locked: el.locked,
+        };
+        if (el.fields.get('persist') === '1')
+            row.persist = true;
+        const cs = el.fields.get('customString');
+        if (cs)
+            row.customString = cs;
+        if (mine.has(el.id))
+            row.heldBy = 'you';
+        else if (holders.has(el.id))
+            row.heldBy = holders.get(el.id);
+        return row;
+    }
+    async queryObjects(handle, q) {
+        const { c } = await this.live(handle, false);
+        const holders = this.holderNames(c);
+        return c.view((scene) => {
+            const out = [];
+            const wantClass = q.class?.toLowerCase();
+            const candidates = q.ids?.length
+                ? q.ids.map((id) => scene.get(id)).filter((e) => !!e && e.kind === 'core:object')
+                : [...scene.walk()].filter((e) => e.kind === 'core:object');
+            const group = q.group ? this.findGroup(scene, q.group) : undefined;
+            for (const el of candidates) {
+                if (group && el.parent !== group)
+                    continue;
+                if (wantClass && (el.fields.get('name') ?? '').toLowerCase() !== wantClass)
+                    continue;
+                if (q.near || q.rect) {
+                    const p = vec(el.fields.get('pos'));
+                    if (!Array.isArray(p))
+                        continue;
+                    if (q.near && Math.hypot(p[0] - q.near.x, p[2] - q.near.z) > q.near.radius)
+                        continue;
+                    if (q.rect && (p[0] < q.rect.minX || p[0] > q.rect.maxX || p[2] < q.rect.minZ || p[2] > q.rect.maxZ))
+                        continue;
+                }
+                out.push(this.objectRow(scene, el, holders, c.selection));
+            }
+            const page = Math.max(0, Math.floor(q.page ?? 0));
+            const slice = out.slice(page * PAGE_SIZE, (page + 1) * PAGE_SIZE);
+            const data = { total: out.length, page, objects: slice };
+            if ((page + 1) * PAGE_SIZE < out.length)
+                data.nextPage = page + 1;
+            const missing = q.ids?.filter((id) => !scene.get(id));
+            if (missing?.length)
+                data.notFound = missing;
+            return {
+                text: `${plural(out.length, 'object')}${data.nextPage !== undefined ? `, page ${page + 1} of ${Math.ceil(out.length / PAGE_SIZE)}` : ''}`,
+                data,
+            };
+        });
+    }
+    /** A group by id or by its (unique) name. */
+    findGroup(scene, ref) {
+        const el = scene.get(ref);
+        if (el?.kind === 'core:group')
+            return ref;
+        const byName = scene
+            .children(PROJECT_ID)
+            .map((id) => scene.get(id))
+            .filter((g) => g.kind === 'core:group' && g.fields.get('name') === ref);
+        if (byName.length === 1)
+            return byName[0].id;
+        if (byName.length > 1)
+            throw new ToolError(`Several groups are called ${ref} — use the group id`);
+        throw new ToolError(`No group ${ref}`);
+    }
+    /** Map key and objects of a session for the world tools; undefined when no session is named and none is current. */
+    async sessionWorld(handle) {
+        if (handle === undefined && !this.current)
+            return undefined;
+        const { r, c } = await this.live(handle, false);
+        const objects = c.view((scene) => {
+            const out = [];
+            for (const el of scene.walk()) {
+                if (el.kind !== 'core:object')
+                    continue;
+                const pos = vec(el.fields.get('pos'));
+                if (!Array.isArray(pos))
+                    continue;
+                const ypr = vec(el.fields.get('ypr'));
+                const scale = num(el.fields.get('scale'));
+                out.push({
+                    id: el.id,
+                    class: el.fields.get('name') ?? '',
+                    position: pos,
+                    orientation: Array.isArray(ypr) ? ypr : [0, 0, 0],
+                    scale: typeof scale === 'number' && scale > 0 ? scale : 1,
+                });
+            }
+            return out;
+        });
+        return { key: `${r.server}/${r.sessionId}`, handle: r.handle, map: r.map, objects };
+    }
+    // ------------------------------------------------------------ changing the scene
+    author(r) {
+        const server = this.resolveServer(r.server);
+        return { author: this.store.load().installationId, authorName: this.credential(server).name };
+    }
+    checkConnection(c) {
+        if (c.interruptedMs >= 3000)
+            throw new ToolError('Connection interrupted — try again when it is back');
+    }
+    /** Locks the existing objects a step changes and the new ones it creates; changes nothing if one is denied. */
+    async lockFor(c, existing, created) {
+        const before = [...c.selection];
+        const want = new Set([...before, ...existing, ...created]);
+        if (want.size > MAX_HELD)
+            throw new ToolError('At most 20,000 objects can be edited at once');
+        const needed = new Set(existing);
+        if (existing.every((id) => c.selection.has(id) && c.held.has(id)) && created.length === 0)
+            return;
+        const res = await c.setLocks([...want]);
+        const denied = res.denied.filter((d) => needed.has(d.element));
+        if (!denied.length)
+            return;
+        await c.setLocks(before.filter((id) => !denied.some((d) => d.element === id)));
+        const byPid = new Map(c.participants.map((p) => [p.participantId, displayName(p)]));
+        const counts = new Map();
+        for (const d of denied) {
+            const who = d.holder ? (byPid.get(d.holder) ?? d.holder) : 'nobody (the session holds the most locks it can)';
+            counts.set(who, (counts.get(who) ?? 0) + 1);
+        }
+        throw new ToolError([...counts].map(([who, n]) => `${plural(n, 'object')} ${n === 1 ? 'is' : 'are'} being edited by ${who}`).join('; '));
+    }
+    /** Builds one operation on the scene with the own unconfirmed steps on top; the scene is unchanged afterwards. */
+    build(c, b, fn) {
+        try {
+            return c.view((scene) => {
+                try {
+                    fn(scene);
+                    return b.finish();
+                }
+                catch (e) {
+                    b.abort();
+                    throw e;
+                }
+            });
+        }
+        catch (e) {
+            if (e instanceof BuildError)
+                throw new ToolError(e.message);
+            throw e;
+        }
+    }
+    stepText(res, opId) {
+        switch (res.status) {
+            case 'applied':
+                return `Done in one step (${opId})`;
+            case 'unconfirmed':
+                return `Sent (${opId}); not confirmed yet — the outcome arrives in session_events`;
+            case 'dropped':
+            case 'rejected':
+                throw new ToolError(res.message);
+        }
+    }
+    async createObjects(handle, groups, objects) {
+        const { r, c } = await this.live(handle);
+        this.checkConnection(c);
+        if (!groups.length && !objects.length)
+            throw new ToolError('Nothing to create');
+        const type = groups.length ? 'projects:edit' : 'placement:edit';
+        const b = new OpBuilder(c.scene, type, this.author(r));
+        const createdObjects = [];
+        const refs = new Map();
+        const op = this.build(c, b, (scene) => {
+            const fileNames = new Set(scene
+                .children(PROJECT_ID)
+                .map((id) => scene.get(id).fields.get('file'))
+                .filter((f) => !!f));
+            groups.forEach((g, i) => {
+                if (refs.has(g.ref))
+                    throw new ToolError(`Group ref ${g.ref} is used twice`);
+                const color = (g.color ?? GROUP_COLOURS[(scene.childCount(PROJECT_ID) + i) % GROUP_COLOURS.length]).toUpperCase();
+                if (!/^#[0-9A-F]{6}$/.test(color))
+                    throw new ToolError(`Colour must be #RRGGBB: ${g.color}`);
+                const base = g.name
+                    .toLowerCase()
+                    .replace(/[^a-z0-9]+/g, '-')
+                    .replace(/^-|-$/g, '') || 'group';
+                let file = `${base}.json`;
+                for (let n = 2; fileNames.has(file); n++)
+                    file = `${base}-${n}.json`;
+                fileNames.add(file);
+                refs.set(g.ref, b.createGroup({ name: g.name, color, file }));
+            });
+            for (const o of objects) {
+                const group = refs.get(o.group) ?? this.findGroup(scene, o.group);
+                const spec = { group, name: o.class, pos: o.position };
+                if (o.orientation)
+                    spec.ypr = o.orientation;
+                if (o.scale !== undefined)
+                    spec.scale = o.scale;
+                createdObjects.push(b.createObject(spec));
+            }
+        });
+        await this.lockFor(c, [], createdObjects);
+        const res = await c.submit(op);
+        c.lastTouched = createdObjects;
+        const text = this.stepText(res, op.id);
+        return {
+            text: `${text}: ${plural(groups.length, 'group')}, ${plural(createdObjects.length, 'object')}`,
+            data: { step: op.id, groups: Object.fromEntries(refs), objects: createdObjects },
+        };
+    }
+    async modifyObjects(handle, changes) {
+        const { r, c } = await this.live(handle);
+        this.checkConnection(c);
+        if (!changes.length)
+            throw new ToolError('Nothing to change');
+        const structural = changes.some((ch) => ch.group !== undefined || ch.hidden !== undefined || ch.locked !== undefined || ch.name !== undefined || ch.color !== undefined);
+        const b = new OpBuilder(c.scene, structural ? 'projects:edit' : 'properties:edit', this.author(r));
+        const objects = [];
+        const op = this.build(c, b, (scene) => {
+            for (const ch of changes) {
+                const el = scene.get(ch.id);
+                if (!el)
+                    throw new ToolError(`No object or group ${ch.id}`);
+                if (el.kind === 'core:group') {
+                    if (ch.position ||
+                        ch.orientation ||
+                        ch.scale !== undefined ||
+                        ch.group ||
+                        ch.persist !== undefined ||
+                        ch.customString !== undefined) {
+                        throw new ToolError(`${ch.id} is a group: only name, color, hidden and locked can change`);
+                    }
+                    if (ch.name !== undefined)
+                        b.setField(ch.id, 'name', ch.name);
+                    if (ch.color !== undefined) {
+                        const color = ch.color.toUpperCase();
+                        if (!/^#[0-9A-F]{6}$/.test(color))
+                            throw new ToolError(`Colour must be #RRGGBB: ${ch.color}`);
+                        b.setField(ch.id, 'color', color);
+                    }
+                }
+                else if (el.kind === 'core:object') {
+                    if (ch.name !== undefined || ch.color !== undefined)
+                        throw new ToolError(`${ch.id} is an object: name and color belong to groups`);
+                    objects.push(ch.id);
+                    if (ch.position)
+                        b.setField(ch.id, 'pos', writeVec3(ch.position));
+                    if (ch.orientation)
+                        b.setField(ch.id, 'ypr', writeVec3(ch.orientation.map(normalizeAngle)));
+                    if (ch.scale !== undefined)
+                        b.setField(ch.id, 'scale', writeFloat32(ch.scale));
+                    if (ch.persist !== undefined)
+                        b.setField(ch.id, 'persist', ch.persist ? '1' : '0');
+                    if (ch.customString !== undefined)
+                        b.setField(ch.id, 'customString', ch.customString);
+                    if (ch.group !== undefined)
+                        b.move(ch.id, this.findGroup(scene, ch.group));
+                }
+                else {
+                    throw new ToolError(`${ch.id} cannot be changed by an agent`);
+                }
+                if (ch.hidden !== undefined)
+                    b.setFlag(ch.id, 'hidden', ch.hidden);
+                if (ch.locked !== undefined)
+                    b.setFlag(ch.id, 'locked', ch.locked);
+            }
+        });
+        if (!op.changes.length)
+            return { text: 'Nothing changed: every value is already as asked' };
+        await this.lockFor(c, objects, []);
+        const res = await c.submit(op);
+        c.lastTouched = objects;
+        return { text: `${this.stepText(res, op.id)}: ${plural(changes.length, 'element')} changed`, data: { step: op.id } };
+    }
+    async deleteObjects(handle, ids) {
+        const { r, c } = await this.live(handle);
+        this.checkConnection(c);
+        if (!ids.length)
+            throw new ToolError('Nothing to delete');
+        const objects = [];
+        let groups = 0;
+        const b = new OpBuilder(c.scene, 'placement:edit', this.author(r));
+        const op = this.build(c, b, (scene) => {
+            const unique = [...new Set(ids)];
+            for (const id of unique) {
+                const el = scene.get(id);
+                if (!el)
+                    throw new ToolError(`No object or group ${id}`);
+                if (el.kind === 'core:group') {
+                    groups++;
+                    objects.push(...scene.children(id));
+                }
+                else if (el.kind === 'core:object')
+                    objects.push(id);
+                else
+                    throw new ToolError(`${id} cannot be deleted by an agent`);
+            }
+            const inDeletedGroup = new Set(unique.filter((id) => scene.get(id).kind === 'core:group'));
+            for (const id of unique) {
+                const el = scene.get(id);
+                if (!el || inDeletedGroup.has(el.parent))
+                    continue;
+                b.deleteTree(id);
+            }
+        });
+        if (groups)
+            op.type = 'projects:edit';
+        await this.lockFor(c, objects, []);
+        const res = await c.submit(op);
+        const text = this.stepText(res, op.id);
+        if (res.status === 'applied')
+            await c.setLocks([...c.selection].filter((id) => !objects.includes(id)));
+        return { text: `${text}: ${plural(groups, 'group')}, ${plural(objects.length, 'object')} deleted`, data: { step: op.id } };
+    }
+    async release(handle, ids) {
+        const { c } = await this.live(handle);
+        const keep = ids?.length ? [...c.selection].filter((id) => !ids.includes(id)) : [];
+        const before = c.selection.size;
+        await c.setLocks(keep);
+        return { text: `Released ${plural(before - c.selection.size, 'object')}; ${c.selection.size} still held` };
+    }
+    async setStatus(handle, phase, status) {
+        if (status !== undefined)
+            validateStatus(status);
+        const { c } = await this.live(handle);
+        c.setPhase(phase, status ?? '');
+        if (phase === 'waiting' && c.selection.size)
+            await c.setLocks([]);
+        return { text: `Phase: ${PHASE_TEXT[phase]}${c.status ? ` — ${c.status}` : ''}` };
+    }
+    async requestReview(handle, status) {
+        if (status !== undefined)
+            validateStatus(status);
+        const { c } = await this.live(handle);
+        const open = await c.flush(10_000);
+        c.setPhase('review', status ?? '');
+        if (c.selection.size)
+            await c.setLocks([]);
+        return {
+            text: `Waiting for review${c.status ? ` — ${c.status}` : ''}${open ? `; ${plural(open, 'change')} not confirmed yet` : ''}. A person saves or discards.`,
+        };
+    }
+}
+//# sourceMappingURL=agent.js.map