agent-protocols 0.4.0 → 0.5.0

package/dist/local-connector/engine.js

@@ -0,0 +1,1234 @@
+// The stateful local connector engine. `LocalConnector` is transport-neutral:
+// it signs on the active agent's behalf, calls an Agent Discourse host over
+// HTTP, materializes local room state by projecting accepted records, derives
+// an actionable inbox, and holds drafts on a room-head mismatch — all behind a
+// single `callTool` dispatcher. The agent never sees the signing key or a
+// reusable request JWT. This is one deep module; its methods are mutually
+// recursive over `this`, so the class stays whole here while the data shapes
+// and pure projection live in sibling submodules.
+import { discourseEvent, eventType, roomCreateEvent, validateDiscourseEnvelope, validateRoomPath, verifyServerRecord, } from "../discourse.js";
+import { ClientNonceManager, DEFAULT_REQUEST_JWT_TTL_SECS, createRequestBinding, createRequestJwtClaims, publicKeyBytes, serviceOrigin, unixTimeMillis, unixTimeSecs, withMentions, } from "../identity.js";
+import { DiscourseClient, ProfileClient } from "../http-client.js";
+import { profileUpdateEvent, } from "../profile.js";
+import { TOOL_AGENT_STATUS_CLEAR, TOOL_AGENT_STATUS_GET, TOOL_AGENT_STATUS_LIST, TOOL_AGENT_STATUS_SET, TOOL_DRAFTS_LIST, TOOL_DRAFT_COMMIT, TOOL_DRAFT_DROP, TOOL_DRAFT_GET, TOOL_HOSTS_LIST, TOOL_IDENTITY_CURRENT, TOOL_INBOX_ACK, TOOL_INBOX_NEXT, TOOL_JOIN_REQUESTS_LIST, TOOL_JOIN_REQUEST_REVIEW, TOOL_PROFILE_UPDATE, TOOL_ROOMS_LIST, TOOL_ROOMS_SEARCH, TOOL_ROOM_CREATE, TOOL_ROOM_JOIN, TOOL_ROOM_JOIN_REQUEST, TOOL_ROOM_JOIN_WHEN_APPROVED, TOOL_ROOM_LEAVE, TOOL_ROOM_MARK_READ, TOOL_ROOM_MEMBERS_LIST, TOOL_ROOM_MEMBER_GET, TOOL_ROOM_OPEN, TOOL_ROOM_SEND_MESSAGE, TOOL_ROOM_STATE, TOOL_ROOM_SUBMIT_EVENT, TOOL_ROOM_TIMELINE, TOOL_ROOM_UNREAD, } from "./catalog.js";
+import { invalidPayload, isRecord, normalizeHost, permissionDenied, } from "./internal.js";
+import { applyRecordProjection, eventTypeAdvancesRoomHead, inboxEntryReady, isDuplicateRecord, materializeCreator, membershipFilter, recordAdvancesRoomHead, validateNextRecord, validateRecordBasePrecondition, } from "./projection.js";
+import { LocalConnectorState } from "./state.js";
+import { roomSummaryFromResponse, timelineItemFromRecord, } from "./views.js";
+function roomKeyString(key) {
+    return `${key.host} ${key.roomId}`;
+}
+function newLocalRoomState(host, room) {
+    return {
+        host,
+        room,
+        headSeq: 0,
+        syncedSeq: 0,
+        subscribed: false,
+        members: new Map(),
+        timeline: [],
+        records: [],
+        readSeq: 0,
+    };
+}
+function unreadCount(room) {
+    return room.timeline.filter((item) => item.seq > room.readSeq).length;
+}
+// ── Room metadata getters: prefer the host-materialized value, fall back to
+// the signed room.create payload (older hosts may omit derived fields).
+function roomCreatePayload(room) {
+    return room.envelope?.event.payload;
+}
+function roomTopic(room) {
+    return room.topic ?? roomCreatePayload(room)?.topic;
+}
+function roomAgenda(room) {
+    return room.agenda ?? roomCreatePayload(room)?.agenda;
+}
+function roomGuidance(room) {
+    return room.guidance ?? roomCreatePayload(room)?.guidance;
+}
+function roomVisibility(room) {
+    return room.visibility ?? roomCreatePayload(room)?.visibility;
+}
+function roomStartTime(room) {
+    return room.start_time ?? roomCreatePayload(room)?.start_time;
+}
+function roomEndTime(room) {
+    return room.end_time ?? roomCreatePayload(room)?.end_time;
+}
+function roomTags(room) {
+    if (room.tags && room.tags.length > 0)
+        return room.tags;
+    return roomCreatePayload(room)?.tags ?? [];
+}
+function roomLanguage(room) {
+    return room.language ?? roomCreatePayload(room)?.language;
+}
+function roomPolicy(room) {
+    return room.policy ?? roomCreatePayload(room)?.policy;
+}
+function roomResponseHead(room) {
+    return room.head ? [room.head.seq, room.head.hash] : [room.seq, room.hash];
+}
+function payloadWithReferences(payload, references) {
+    if (references.length === 0)
+        return payload;
+    const extra = isRecord(payload.extra) ? payload.extra : {};
+    extra.references = references;
+    payload.extra = extra;
+    return payload;
+}
+function messageDraftValue(input) {
+    return {
+        room_id: input.room_id,
+        content: input.content,
+        content_type: input.content_type ?? "text/plain",
+        mentions: input.mentions ?? [],
+        references: input.references ?? [],
+        extra: input.extra ?? {},
+    };
+}
+function eventDraftValue(input) {
+    return {
+        room_id: input.room_id,
+        type: input.type,
+        payload: input.payload,
+        mentions: input.mentions ?? [],
+        references: input.references ?? [],
+    };
+}
+function heldDraftOptions() {
+    return ["revise", "send_as_is", "stay_silent", "send_anyway"];
+}
+function profileToMemberProfile(profile) {
+    return {
+        name: profile.name,
+        description: profile.description,
+        avatar_url: profile.avatar_url,
+    };
+}
+function base64UrlEncode(bytes) {
+    return Buffer.from(bytes).toString("base64url");
+}
+function compareStrings(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function parseCursor(cursor) {
+    if (cursor === undefined)
+        return 0;
+    const parsed = Number.parseInt(cursor, 10);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function sortedAgentStatuses(statuses) {
+    return [...statuses.entries()]
+        .sort((a, b) => compareStrings(a[0], b[0]))
+        .map(([, status]) => status);
+}
+export class LocalConnector {
+    signer;
+    state;
+    nonces = new ClientNonceManager();
+    fetchImpl;
+    constructor(signer, options = {}) {
+        this.signer = signer;
+        this.state = options.state ?? new LocalConnectorState();
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    agentId() {
+        return this.signer.agentId();
+    }
+    addHost(host) {
+        this.state.hosts.set(normalizeHost(host.host), host);
+    }
+    observeRoom(host, room) {
+        const normalized = normalizeHost(host);
+        this.ensureHost(normalized);
+        const key = { host: normalized, roomId: room.id };
+        const keyStr = roomKeyString(key);
+        let entry = this.state.rooms.get(keyStr);
+        if (!entry) {
+            entry = newLocalRoomState(normalized, room);
+            this.state.rooms.set(keyStr, entry);
+        }
+        entry.host = normalized;
+        entry.room = room;
+        materializeCreator(entry);
+    }
+    acceptRoomResponse(host, room) {
+        const normalized = normalizeHost(host);
+        const key = { host: normalized, roomId: room.id };
+        this.observeRoom(normalized, room);
+        const entry = this.state.rooms.get(roomKeyString(key));
+        if (entry) {
+            const [headSeq, headHash] = roomResponseHead(entry.room);
+            entry.headSeq = headSeq;
+            entry.headHash = headHash;
+            entry.syncedSeq = entry.room.seq;
+            entry.syncedHash = entry.room.hash;
+        }
+    }
+    /** Applies a verified record to the room named by its `room_id` alone. Throws
+     * an ambiguity error when the room ID is open on more than one host. */
+    applyRecord(record) {
+        const key = this.resolveRoomKey(undefined, record.room_id);
+        this.applyRecordTo(key, record);
+    }
+    /** Applies a verified record to the room on the given host. */
+    applyHostRecord(host, record) {
+        const key = { host: normalizeHost(host), roomId: record.room_id };
+        this.applyRecordTo(key, record);
+    }
+    applyRecordTo(key, record) {
+        validateDiscourseEnvelope(record.envelope);
+        validateRoomPath(record.envelope, record.room_id);
+        verifyServerRecord(record);
+        const activeAgent = this.agentId();
+        const room = this.state.rooms.get(roomKeyString(key));
+        if (!room) {
+            throw invalidPayload(`room is not open locally: ${key.roomId}`);
+        }
+        if (isDuplicateRecord(room, record))
+            return;
+        validateNextRecord(room, record);
+        validateRecordBasePrecondition(room, record);
+        const item = timelineItemFromRecord(record);
+        const newInbox = [];
+        applyRecordProjection(room, record, item, activeAgent, newInbox);
+        let clearedStatus;
+        if (record.envelope.event.type === eventType.ROOM_MEMBER_REMOVE) {
+            const payload = record.envelope.event.payload;
+            clearedStatus = payload?.member;
+        }
+        if (recordAdvancesRoomHead(room, record)) {
+            room.headSeq = record.seq;
+            room.headHash = record.hash;
+        }
+        room.syncedSeq = record.seq;
+        room.syncedHash = record.hash;
+        room.records.push(record);
+        room.timeline.push(item);
+        // Removal ends membership; the host clears the member's transient status,
+        // so drop the local cache entry too.
+        if (clearedStatus !== undefined) {
+            this.state.agentStatuses.get(roomKeyString(key))?.delete(clearedStatus);
+        }
+        for (const inboxItem of newInbox)
+            this.insertInbox(inboxItem);
+    }
+    resolveRoomKey(host, roomId) {
+        if (host !== undefined)
+            return { host: normalizeHost(host), roomId };
+        const hosts = [...this.state.rooms.values()]
+            .filter((room) => room.room.id === roomId)
+            .map((room) => room.host);
+        if (hosts.length === 1)
+            return { host: hosts[0], roomId };
+        if (hosts.length > 1) {
+            throw invalidPayload(`room id ${roomId} matches rooms on more than one host; pass host`);
+        }
+        throw invalidPayload(`room is not open locally: ${roomId}`);
+    }
+    async callTool(name, input) {
+        switch (name) {
+            case TOOL_IDENTITY_CURRENT:
+                return this.identityCurrent();
+            case TOOL_HOSTS_LIST:
+                return this.hostsList();
+            case TOOL_ROOMS_SEARCH:
+                return this.roomsSearch(input);
+            case TOOL_ROOMS_LIST:
+                return this.roomsList(input);
+            case TOOL_ROOM_OPEN:
+                return this.roomOpen(input);
+            case TOOL_ROOM_STATE:
+                return this.roomStateTool(input);
+            case TOOL_ROOM_MEMBERS_LIST:
+                return this.roomMembersList(input);
+            case TOOL_ROOM_MEMBER_GET:
+                return this.roomMemberGet(input);
+            case TOOL_AGENT_STATUS_LIST:
+                return this.agentStatusList(input);
+            case TOOL_AGENT_STATUS_GET:
+                return this.agentStatusGet(input);
+            case TOOL_AGENT_STATUS_SET:
+                return this.agentStatusSet(input);
+            case TOOL_AGENT_STATUS_CLEAR:
+                return this.agentStatusClear(input);
+            case TOOL_ROOM_TIMELINE:
+                return this.roomTimeline(input);
+            case TOOL_ROOM_UNREAD:
+                return this.roomUnread(input);
+            case TOOL_ROOM_MARK_READ:
+                return this.roomMarkRead(input);
+            case TOOL_INBOX_NEXT:
+                return this.inboxNext(input);
+            case TOOL_INBOX_ACK:
+                return this.inboxAck(input);
+            case TOOL_DRAFTS_LIST:
+                return this.draftsList(input);
+            case TOOL_DRAFT_GET:
+                return this.draftGet(input);
+            case TOOL_DRAFT_COMMIT:
+                return this.draftCommit(input);
+            case TOOL_DRAFT_DROP:
+                return this.draftDrop(input);
+            case TOOL_PROFILE_UPDATE:
+                return this.profileUpdate(input);
+            case TOOL_ROOM_CREATE:
+                return this.roomCreate(input);
+            case TOOL_ROOM_JOIN:
+                return this.roomJoin(input);
+            case TOOL_ROOM_JOIN_REQUEST:
+                return this.roomJoinRequest(input);
+            case TOOL_ROOM_JOIN_WHEN_APPROVED:
+                return this.roomJoinWhenApproved(input);
+            case TOOL_ROOM_LEAVE:
+                return this.roomLeave(input);
+            case TOOL_ROOM_SEND_MESSAGE:
+                return this.roomSendMessage(input);
+            case TOOL_ROOM_SUBMIT_EVENT:
+                return this.roomSubmitEvent(input);
+            case TOOL_JOIN_REQUESTS_LIST:
+                return this.joinRequestsList(input);
+            case TOOL_JOIN_REQUEST_REVIEW:
+                return this.joinRequestReview(input);
+            default:
+                throw invalidPayload(`unknown local connector tool: ${name}`);
+        }
+    }
+    identityCurrent() {
+        const agentId = this.agentId();
+        return {
+            agent_id: agentId,
+            public_key: base64UrlEncode(publicKeyBytes(agentId)),
+            profiles: [...this.state.profiles.keys()].sort(compareStrings),
+            hosts: this.sortedHosts(),
+        };
+    }
+    hostsList() {
+        return { hosts: this.sortedHosts() };
+    }
+    async roomsSearch(input) {
+        const host = normalizeHost(input.host);
+        this.requireAllowedHost(host);
+        const rooms = await this.discourse(host).publicRooms({
+            status: input.status,
+            tag: input.tag,
+            keyword: input.keyword,
+            creator: input.creator,
+            startsAfter: input.starts_after,
+            endsBefore: input.ends_before,
+            language: input.language,
+            limit: input.limit,
+            cursor: input.cursor,
+        });
+        for (const room of rooms)
+            this.observeRoom(host, room);
+        const summaries = rooms.map((room) => this.summaryForResponse(host, room));
+        return { rooms: summaries };
+    }
+    roomsList(input) {
+        const offset = parseCursor(input.cursor);
+        const limit = input.limit ?? 50;
+        const agentId = this.agentId();
+        const rooms = [...this.state.rooms.values()]
+            .sort((a, b) => compareStrings(a.host, b.host) ||
+            compareStrings(a.room.id, b.room.id))
+            .filter((room) => input.status !== undefined ? room.room.status === input.status : true)
+            .filter((room) => membershipFilter(room, agentId, input.membership))
+            .slice(offset, offset + limit)
+            .map((room) => this.summaryForRoom(room));
+        return { rooms };
+    }
+    async roomOpen(input) {
+        const host = normalizeHost(input.host);
+        this.requireAllowedHost(host);
+        const key = { host, roomId: input.room_id };
+        const previousSeq = this.state.rooms.get(roomKeyString(key))?.syncedSeq ?? 0;
+        if (input.refresh || previousSeq === 0) {
+            const client = this.discourse(host);
+            const room = await client.room(input.room_id);
+            this.observeRoom(host, room);
+            const jwt = this.requestJwt(host);
+            const records = await client.events(input.room_id, {
+                afterSeq: previousSeq > 0 ? previousSeq : undefined,
+                jwt,
+            });
+            for (const record of records)
+                this.applyHostRecord(host, record);
+        }
+        const opened = this.state.rooms.get(roomKeyString(key));
+        if (opened)
+            opened.subscribed = input.subscribe ?? false;
+        const room = this.localRoom(key);
+        return {
+            room: this.roomStateView(room),
+            sync: this.syncState(key),
+            active_turn: room.activeTurn,
+        };
+    }
+    async roomStateTool(input) {
+        void input.include_types;
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        if (input.refresh) {
+            const host = this.localRoom(key).host;
+            return this.roomOpen({ host, room_id: input.room_id, refresh: true });
+        }
+        const room = this.localRoom(key);
+        return { room: this.roomStateView(room), sync: this.syncState(key) };
+    }
+    roomMembersList(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const room = this.localRoom(key);
+        const offset = parseCursor(input.cursor);
+        const limit = input.limit ?? 100;
+        const members = [...room.members.values()]
+            .sort((a, b) => compareStrings(a.agent_id, b.agent_id))
+            .filter((member) => input.status !== undefined ? member.status === input.status : true)
+            .filter((member) => input.role !== undefined ? member.role === input.role : true)
+            .slice(offset, offset + limit)
+            .map((member) => ({ ...member }));
+        if (input.include_profiles) {
+            for (const member of members) {
+                if (member.profile === undefined) {
+                    const profile = this.state.profiles.get(member.agent_id);
+                    if (profile)
+                        member.profile = profileToMemberProfile(profile);
+                }
+            }
+        }
+        return { members, sync: this.syncState(key) };
+    }
+    roomMemberGet(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const room = this.localRoom(key);
+        const found = room.members.get(input.agent_id);
+        if (!found)
+            throw invalidPayload("room member not found");
+        const member = { ...found };
+        if (input.include_profile && member.profile === undefined) {
+            const profile = this.state.profiles.get(member.agent_id);
+            if (profile)
+                member.profile = profileToMemberProfile(profile);
+        }
+        const recent = input.include_recent_activity
+            ? room.timeline
+                .filter((item) => item.actor === input.agent_id)
+                .slice(-10)
+                .reverse()
+            : [];
+        return { member, recent, sync: this.syncState(key) };
+    }
+    async agentStatusList(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const keyStr = roomKeyString(key);
+        if (!input.refresh) {
+            const cached = this.state.agentStatuses.get(keyStr);
+            if (cached) {
+                return {
+                    statuses: sortedAgentStatuses(cached),
+                    sync: this.syncState(key),
+                };
+            }
+        }
+        const host = this.allowedRoomHost(key);
+        const jwt = this.requestJwt(host);
+        const response = await this.discourse(host).agentStatuses(input.room_id, jwt);
+        const statuses = new Map();
+        for (const status of response.statuses) {
+            statuses.set(status.agent_id, status);
+        }
+        this.state.agentStatuses.set(keyStr, statuses);
+        return { statuses: sortedAgentStatuses(statuses), sync: this.syncState(key) };
+    }
+    async agentStatusGet(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const keyStr = roomKeyString(key);
+        if (!input.refresh) {
+            const cached = this.state.agentStatuses.get(keyStr)?.get(input.agent_id);
+            if (cached)
+                return { status: cached, sync: this.syncState(key) };
+        }
+        const host = this.allowedRoomHost(key);
+        const jwt = this.requestJwt(host);
+        const response = await this.discourse(host).agentStatus(input.room_id, input.agent_id, jwt);
+        let statuses = this.state.agentStatuses.get(keyStr);
+        if (!statuses) {
+            statuses = new Map();
+            this.state.agentStatuses.set(keyStr, statuses);
+        }
+        statuses.set(response.status.agent_id, response.status);
+        return { status: response.status, sync: this.syncState(key) };
+    }
+    async agentStatusSet(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const keyStr = roomKeyString(key);
+        const host = this.allowedRoomHost(key);
+        const jwt = this.requestJwt(host);
+        const request = {
+            state: input.state,
+            summary: input.summary,
+            seen_seq: input.seen_seq,
+            seen_hash: input.seen_hash,
+            claim_id: input.claim_id,
+            activity: input.activity,
+            expires_at: input.expires_at,
+            extra: input.extra,
+        };
+        const status = await this.discourse(host).setAgentStatus(input.room_id, jwt, request);
+        let statuses = this.state.agentStatuses.get(keyStr);
+        if (!statuses) {
+            statuses = new Map();
+            this.state.agentStatuses.set(keyStr, statuses);
+        }
+        statuses.set(status.agent_id, status);
+        return { status, sync: this.syncState(key) };
+    }
+    async agentStatusClear(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const host = this.allowedRoomHost(key);
+        const jwt = this.requestJwt(host);
+        const request = {
+            state: "away",
+            expires_at: unixTimeMillis() - 1,
+        };
+        await this.discourse(host).setAgentStatus(input.room_id, jwt, request);
+        this.state.agentStatuses.get(roomKeyString(key))?.delete(this.agentId());
+        return { cleared: true, room_id: input.room_id };
+    }
+    roomTimeline(input) {
+        void input.refresh;
+        void input.include_records;
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const room = this.localRoom(key);
+        const items = room.timeline
+            .filter((item) => input.after_seq !== undefined ? item.seq > input.after_seq : true)
+            .filter((item) => input.before_seq !== undefined ? item.seq < input.before_seq : true)
+            .filter((item) => input.types !== undefined ? input.types.includes(item.type) : true)
+            .filter((item) => input.actors !== undefined ? input.actors.includes(item.actor) : true)
+            .filter((item) => !input.unread_only || item.seq > room.readSeq)
+            .slice(0, input.limit ?? 50);
+        const nextAfterSeq = items.length > 0 ? items[items.length - 1].seq : undefined;
+        return {
+            items,
+            sync: this.syncState(key),
+            next_after_seq: nextAfterSeq,
+        };
+    }
+    roomUnread(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const room = this.localRoom(key);
+        let items = room.timeline
+            .filter((item) => item.seq > room.readSeq)
+            .slice(0, input.limit ?? 50);
+        const throughSeq = items.length > 0 ? items[items.length - 1].seq : undefined;
+        if (input.mark_read) {
+            if (throughSeq !== undefined)
+                room.readSeq = throughSeq;
+            items =
+                throughSeq !== undefined
+                    ? room.timeline.filter((item) => item.seq <= throughSeq)
+                    : [];
+        }
+        return {
+            items,
+            unread_count: unreadCount(room),
+            sync: this.syncState(key),
+        };
+    }
+    roomMarkRead(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const room = this.localRoom(key);
+        room.readSeq = Math.max(room.readSeq, input.through_seq);
+        return {
+            room_id: input.room_id,
+            read_seq: room.readSeq,
+            unread_count: unreadCount(room),
+        };
+    }
+    inboxNext(input) {
+        void input.wait_ms;
+        const now = unixTimeMillis();
+        const ids = [...this.state.inbox.entries()]
+            .sort((a, b) => compareStrings(a[0], b[0]))
+            .filter(([, entry]) => inboxEntryReady(entry, now))
+            .filter(([, entry]) => input.room_id !== undefined
+            ? entry.item.room_id === input.room_id
+            : true)
+            .filter(([, entry]) => input.kinds !== undefined
+            ? input.kinds.includes(entry.item.kind)
+            : true)
+            .map(([id]) => id)
+            .slice(0, input.limit ?? 10);
+        const items = [];
+        for (const id of ids) {
+            const entry = this.state.inbox.get(id);
+            if (entry) {
+                items.push(entry.item);
+                if (input.claim)
+                    entry.state = { kind: "claimed" };
+            }
+        }
+        return { items, pending_count: this.pendingInboxCount() };
+    }
+    inboxAck(input) {
+        const acknowledged = [];
+        for (const id of input.ids) {
+            const entry = this.state.inbox.get(id);
+            if (entry) {
+                entry.state =
+                    input.action === "defer"
+                        ? { kind: "deferred", until: input.defer_until ?? unixTimeMillis() }
+                        : { kind: "acknowledged" };
+                acknowledged.push(id);
+            }
+        }
+        return { acknowledged, pending_count: this.pendingInboxCount() };
+    }
+    draftsList(input) {
+        const offset = parseCursor(input.cursor);
+        const limit = input.limit ?? 50;
+        const host = input.host !== undefined ? normalizeHost(input.host) : undefined;
+        const drafts = [...this.state.drafts.values()]
+            .sort((a, b) => compareStrings(a.draft.id, b.draft.id))
+            .filter((entry) => input.room_id !== undefined
+            ? entry.draft.room_id === input.room_id
+            : true)
+            .filter((entry) => host !== undefined ? entry.draft.current_sync.host === host : true)
+            .slice(offset, offset + limit + 1)
+            .map((entry) => entry.draft);
+        let nextCursor;
+        if (drafts.length > limit) {
+            drafts.pop();
+            nextCursor = String(offset + limit);
+        }
+        return { drafts, next_cursor: nextCursor };
+    }
+    draftGet(input) {
+        const entry = this.state.drafts.get(input.draft_id);
+        if (!entry)
+            throw invalidPayload("draft not found");
+        const key = {
+            host: entry.draft.current_sync.host,
+            roomId: entry.draft.room_id,
+        };
+        return {
+            draft: entry.draft,
+            changes: this.roomChangesSince(key, entry.draft.base_seq),
+            sync: this.syncState(key),
+        };
+    }
+    async draftCommit(input) {
+        const entry = this.state.drafts.get(input.draft_id);
+        if (!entry)
+            throw invalidPayload("draft not found");
+        if (input.action === "stay_silent") {
+            this.state.drafts.delete(input.draft_id);
+            return { status: "dropped", draft_id: input.draft_id };
+        }
+        let result;
+        if (entry.request.kind === "message") {
+            const request = { ...entry.request.input };
+            if (input.action === "send_anyway") {
+                request.base_seq = undefined;
+                request.base_hash = undefined;
+                request.on_head_mismatch = "send_anyway";
+                result = await this.submitMessageUnchecked(request);
+            }
+            else {
+                if (input.action === "revise") {
+                    if (input.content !== undefined)
+                        request.content = input.content;
+                    if (input.content_type !== undefined)
+                        request.content_type = input.content_type;
+                    if (input.mentions !== undefined)
+                        request.mentions = input.mentions;
+                    if (input.references !== undefined)
+                        request.references = input.references;
+                    if (input.extra !== undefined)
+                        request.extra = input.extra;
+                }
+                request.base_seq = input.base_seq;
+                request.base_hash = input.base_hash;
+                request.on_head_mismatch = input.on_head_mismatch;
+                result = await this.roomSendMessage(request);
+            }
+        }
+        else {
+            const request = { ...entry.request.input };
+            if (input.action === "send_anyway") {
+                request.base_seq = undefined;
+                request.base_hash = undefined;
+                request.on_head_mismatch = "send_anyway";
+                result = await this.submitEventUnchecked(request);
+            }
+            else {
+                if (input.action === "revise") {
+                    if (input.type !== undefined)
+                        request.type = input.type;
+                    if (input.payload !== undefined)
+                        request.payload = input.payload;
+                    if (input.mentions !== undefined)
+                        request.mentions = input.mentions;
+                    if (input.references !== undefined)
+                        request.references = input.references;
+                }
+                request.base_seq = input.base_seq;
+                request.base_hash = input.base_hash;
+                request.on_head_mismatch = input.on_head_mismatch;
+                result = await this.roomSubmitEvent(request);
+            }
+        }
+        if (result.status === "sent" || result.status === "held") {
+            this.state.drafts.delete(input.draft_id);
+        }
+        return result;
+    }
+    draftDrop(input) {
+        this.state.drafts.delete(input.draft_id);
+        return {
+            status: "dropped",
+            draft_id: input.draft_id,
+            pending_count: this.state.drafts.size,
+        };
+    }
+    async profileUpdate(input) {
+        if (!isRecord(input.profile)) {
+            throw invalidPayload("profile must be an object");
+        }
+        const profile = { ...input.profile };
+        // payload.id is always the active Agent ID; reject an input that names a
+        // different agent instead of silently rewriting it.
+        const activeId = this.agentId();
+        if (profile.id === undefined) {
+            profile.id = activeId;
+        }
+        else if (profile.id !== activeId) {
+            throw invalidPayload("profile.id must be the active Agent ID");
+        }
+        const envelope = this.signProfileUpdate(profile);
+        const materialized = await this.profileClient(input.profile_service).submitProfileUpdate(envelope);
+        this.state.profiles.set(materialized.id, materialized);
+        return { profile: materialized, envelope };
+    }
+    async roomCreate(input) {
+        const host = normalizeHost(input.host);
+        this.requireAllowedHost(host);
+        const payload = {
+            topic: input.topic,
+            visibility: input.visibility,
+            start_time: input.start_time,
+            end_time: input.end_time,
+            agenda: input.agenda,
+            guidance: input.guidance,
+            tags: input.tags,
+            language: input.language,
+            policy: input.policy,
+            types: input.types,
+        };
+        const envelope = this.signRoomCreate(payload);
+        const room = await this.discourse(host).createRoom(envelope);
+        if (!room.envelope)
+            room.envelope = envelope;
+        this.acceptRoomResponse(host, room);
+        const key = { host, roomId: room.id };
+        return {
+            room: this.roomStateView(this.localRoom(key)),
+            envelope,
+            sync: this.syncState(key),
+        };
+    }
+    async roomJoin(input) {
+        const roomId = input.room_id;
+        let key;
+        if (input.host !== undefined) {
+            const host = normalizeHost(input.host);
+            this.requireAllowedHost(host);
+            key = { host, roomId };
+        }
+        else {
+            key = this.resolveRoomKey(undefined, roomId);
+            this.requireAllowedHost(key.host);
+        }
+        const host = key.host;
+        if (!this.state.rooms.has(roomKeyString(key))) {
+            const room = await this.discourse(host).room(roomId);
+            this.acceptRoomResponse(host, room);
+        }
+        if (input.request_id !== undefined) {
+            const status = await this.approvedJoinRequest(host, roomId, input.request_id);
+            const approvedRole = status.approved_role ?? status.request.role;
+            // The completion call signs room.join with the approved role; a differing
+            // input role is a mismatch error, never a silent substitution.
+            if (input.role !== approvedRole) {
+                throw invalidPayload(`join_request_role_mismatch: approved role is ${approvedRole}`);
+            }
+            const payload = {
+                request_id: input.request_id,
+                role: approvedRole,
+            };
+            return this.completeJoin(host, key, payload);
+        }
+        if (roomVisibility(this.localRoom(key).room) === "public") {
+            const payload = {
+                request_id: undefined,
+                role: input.role,
+                perspective: input.perspective,
+            };
+            return this.completeJoin(host, key, payload);
+        }
+        const jwt = this.requestJwt(host);
+        const request = {
+            role: input.role,
+            perspective: input.perspective,
+            reason: input.reason,
+            extra: input.extra,
+        };
+        const status = await this.discourse(host).requestJoin(roomId, jwt, request);
+        this.pushJoinRequest(key, status);
+        let sync;
+        try {
+            sync = this.syncState(key);
+        }
+        catch {
+            sync = undefined;
+        }
+        return { status: "approval_required", join_request: status, sync };
+    }
+    async roomJoinRequest(input) {
+        const host = normalizeHost(input.host);
+        this.requireAllowedHost(host);
+        const jwt = this.requestJwt(host);
+        const request = {
+            role: input.role,
+            perspective: input.perspective,
+            reason: input.reason,
+            extra: input.extra,
+        };
+        const status = await this.discourse(host).requestJoin(input.room_id, jwt, request);
+        this.pushJoinRequest({ host, roomId: input.room_id }, status);
+        return { join_request: status };
+    }
+    async roomJoinWhenApproved(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const host = this.allowedRoomHost(key);
+        const status = await this.approvedJoinRequest(host, input.room_id, input.request_id);
+        const role = status.approved_role ?? status.request.role;
+        const payload = {
+            request_id: input.request_id,
+            role,
+        };
+        const result = await this.completeJoin(host, key, payload);
+        return { record: result.record, member: result.member, sync: result.sync };
+    }
+    async roomLeave(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const host = this.allowedRoomHost(key);
+        const payload = {
+            reason: input.reason,
+            references: [],
+            extra: {},
+        };
+        const envelope = this.signRoomEvent(eventType.ROOM_LEAVE, key, undefined, undefined, [], payload);
+        const record = await this.discourse(host).leaveRoom(input.room_id, envelope);
+        this.applyHostRecord(host, record);
+        return { record, sync: this.syncState(key) };
+    }
+    async roomSendMessage(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const held = this.headMismatchMessageResult(key, input);
+        if (held)
+            return held;
+        return this.submitMessageUnchecked(input);
+    }
+    async submitMessageUnchecked(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const host = this.allowedRoomHost(key);
+        const payload = {
+            content_type: input.content_type ?? "text/plain",
+            content: input.content,
+        };
+        if (input.references && input.references.length > 0) {
+            payload.references = input.references;
+        }
+        if (input.extra && Object.keys(input.extra).length > 0) {
+            payload.extra = input.extra;
+        }
+        const envelope = this.signRoomEvent(eventType.MESSAGE_CREATE, key, input.base_seq, input.base_hash, input.mentions ?? [], payload);
+        const record = await this.discourse(host).submitEvent(input.room_id, envelope);
+        this.applyHostRecord(host, record);
+        const item = this.timelineItemByEvent(key, record.envelope.hash);
+        return {
+            status: "sent",
+            record: record,
+            item,
+            sync: this.syncState(key),
+        };
+    }
+    async roomSubmitEvent(input) {
+        // For signal-kind writes — including the membership events — the base is
+        // only an anchor: never hold the draft, ignore on_head_mismatch.
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const room = this.state.rooms.get(roomKeyString(key));
+        const advancesHead = room
+            ? eventTypeAdvancesRoomHead(room, input.type)
+            : true;
+        if (advancesHead) {
+            const held = this.headMismatchEventResult(key, input);
+            if (held)
+                return held;
+        }
+        return this.submitEventUnchecked(input);
+    }
+    async submitEventUnchecked(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const host = this.allowedRoomHost(key);
+        const payload = payloadWithReferences(input.payload, input.references ?? []);
+        const envelope = this.signRoomEvent(input.type, key, input.base_seq, input.base_hash, input.mentions ?? [], payload);
+        const record = await this.discourse(host).submitEvent(input.room_id, envelope);
+        this.applyHostRecord(host, record);
+        const item = this.timelineItemByEvent(key, record.envelope.hash);
+        return {
+            status: "sent",
+            record: record,
+            item,
+            sync: this.syncState(key),
+        };
+    }
+    async joinRequestsList(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const host = this.allowedRoomHost(key);
+        const jwt = this.requestJwt(host);
+        let requests = await this.discourse(host).joinRequests(input.room_id, jwt);
+        if (input.status !== undefined) {
+            requests = requests.filter((request) => request.status === input.status);
+        }
+        const offset = parseCursor(input.cursor);
+        if (offset > 0)
+            requests = requests.slice(offset);
+        if (input.limit !== undefined)
+            requests = requests.slice(0, input.limit);
+        this.state.joinRequests.set(roomKeyString(key), requests);
+        return { join_requests: requests };
+    }
+    async joinRequestReview(input) {
+        const key = this.resolveRoomKey(input.host, input.room_id);
+        const host = this.allowedRoomHost(key);
+        const jwt = this.requestJwt(host);
+        const status = await this.discourse(host).joinRequest(input.room_id, input.request_id, jwt);
+        const payload = {
+            request: status.request,
+            decision: input.decision,
+            role: input.role,
+            reason: input.reason,
+            extra: {},
+        };
+        const envelope = this.signRoomEvent(eventType.ROOM_JOIN_REVIEW, key, undefined, undefined, [], payload);
+        const record = await this.discourse(host).submitEvent(input.room_id, envelope);
+        this.applyHostRecord(host, record);
+        return { record, sync: this.syncState(key) };
+    }
+    // ── Join helpers shared by the join tools.
+    async approvedJoinRequest(host, roomId, requestId) {
+        const jwt = this.requestJwt(host);
+        const status = await this.discourse(host).joinRequest(roomId, requestId, jwt);
+        if (status.request.applicant !== this.agentId()) {
+            throw invalidPayload("join request belongs to another agent");
+        }
+        if (status.status !== "approved") {
+            throw invalidPayload("join request is not approved");
+        }
+        return status;
+    }
+    async completeJoin(host, key, payload) {
+        const envelope = this.signRoomEvent(eventType.ROOM_JOIN, key, undefined, undefined, [], payload);
+        const record = await this.discourse(host).joinRoom(key.roomId, envelope);
+        this.applyHostRecord(host, record);
+        const member = this.localRoom(key).members.get(this.agentId());
+        if (!member)
+            throw invalidPayload("joined member not materialized");
+        return {
+            status: "joined",
+            record: record,
+            member,
+            sync: this.syncState(key),
+        };
+    }
+    pushJoinRequest(key, status) {
+        const keyStr = roomKeyString(key);
+        const existing = this.state.joinRequests.get(keyStr);
+        if (existing)
+            existing.push(status);
+        else
+            this.state.joinRequests.set(keyStr, [status]);
+    }
+    // ── Signing.
+    signProfileUpdate(payload) {
+        const event = profileUpdateEvent(this.agentId(), unixTimeMillis(), this.nonces.nextNonce(), payload);
+        return this.signer.signEvent(event);
+    }
+    signRoomCreate(payload) {
+        const event = roomCreateEvent(this.agentId(), unixTimeMillis(), this.nonces.nextNonce(), payload);
+        const envelope = this.signer.signEvent(event);
+        validateDiscourseEnvelope(envelope);
+        return envelope;
+    }
+    signRoomEvent(type, key, baseSeq, baseHash, mentions, payload) {
+        const host = this.localRoom(key).host;
+        this.requireAllowedHost(host);
+        const [resolvedSeq, resolvedHash] = this.roomHeadForWrite(key, baseSeq, baseHash);
+        const event = withMentions(discourseEvent(type, this.agentId(), unixTimeMillis(), this.nonces.nextNonce(), key.roomId, resolvedSeq, resolvedHash, payload), mentions);
+        const envelope = this.signer.signEvent(event);
+        validateDiscourseEnvelope(envelope);
+        return envelope;
+    }
+    roomHeadForWrite(key, baseSeq, baseHash) {
+        if (baseSeq !== undefined && baseHash !== undefined) {
+            if (baseSeq > 0 && baseHash.trim() !== "")
+                return [baseSeq, baseHash];
+            throw invalidPayload("base_seq and base_hash must identify a valid room head");
+        }
+        if (baseSeq === undefined && baseHash === undefined) {
+            const sync = this.syncState(key);
+            if (sync.head_seq === 0 || sync.head_hash.trim() === "") {
+                throw invalidPayload("current room head is not known locally");
+            }
+            return [sync.head_seq, sync.head_hash];
+        }
+        throw invalidPayload("base_seq and base_hash must be provided together");
+    }
+    requestJwt(host) {
+        // The request JWT aud is always the origin of the host API.
+        const audience = serviceOrigin(host);
+        const claims = createRequestJwtClaims(this.agentId(), createRequestBinding(audience), unixTimeSecs(), DEFAULT_REQUEST_JWT_TTL_SECS);
+        return this.signer.signRequestJwt(claims);
+    }
+    // ── Head-mismatch handling and draft holding.
+    headMismatchMessageResult(key, input) {
+        const headMismatch = this.headMismatchWriteState(key, input.base_seq, input.base_hash);
+        if (!headMismatch)
+            return undefined;
+        switch (input.on_head_mismatch ?? "hold") {
+            case "send_anyway":
+                input.base_seq = undefined;
+                input.base_hash = undefined;
+                return undefined;
+            case "reject":
+                return this.rejectedHeadMismatchResult(headMismatch);
+            default:
+                return this.holdMessageDraft(input, headMismatch);
+        }
+    }
+    headMismatchEventResult(key, input) {
+        const headMismatch = this.headMismatchWriteState(key, input.base_seq, input.base_hash);
+        if (!headMismatch)
+            return undefined;
+        switch (input.on_head_mismatch ?? "hold") {
+            case "send_anyway":
+                input.base_seq = undefined;
+                input.base_hash = undefined;
+                return undefined;
+            case "reject":
+                return this.rejectedHeadMismatchResult(headMismatch);
+            default:
+                return this.holdEventDraft(input, headMismatch);
+        }
+    }
+    headMismatchWriteState(key, baseSeq, baseHash) {
+        if (baseSeq === undefined && baseHash === undefined)
+            return undefined;
+        const sync = this.syncState(key);
+        const seqMismatch = baseSeq !== undefined && baseSeq !== sync.head_seq;
+        const hashMismatch = baseHash !== undefined && sync.head_hash !== baseHash;
+        if (!seqMismatch && !hashMismatch)
+            return undefined;
+        return { sync, changes: this.roomChangesSince(key, baseSeq) };
+    }
+    rejectedHeadMismatchResult(headMismatch) {
+        return {
+            status: "rejected",
+            reason: "room_head_mismatch",
+            changes: headMismatch.changes,
+            sync: headMismatch.sync,
+        };
+    }
+    holdMessageDraft(input, headMismatch) {
+        input.host = headMismatch.sync.host;
+        const draftId = this.nextDraftId(input.room_id);
+        const draft = {
+            id: draftId,
+            room_id: input.room_id,
+            kind: "message",
+            created_at: unixTimeMillis(),
+            base_seq: input.base_seq,
+            base_hash: input.base_hash,
+            current_sync: headMismatch.sync,
+            draft: messageDraftValue(input),
+            reason: "room_head_mismatch",
+            options: heldDraftOptions(),
+        };
+        this.state.drafts.set(draftId, {
+            draft,
+            request: { kind: "message", input },
+        });
+        return {
+            status: "held",
+            reason: "room_head_mismatch",
+            draft,
+            changes: headMismatch.changes,
+            sync: headMismatch.sync,
+        };
+    }
+    holdEventDraft(input, headMismatch) {
+        input.host = headMismatch.sync.host;
+        const draftId = this.nextDraftId(input.room_id);
+        const draft = {
+            id: draftId,
+            room_id: input.room_id,
+            kind: "event",
+            created_at: unixTimeMillis(),
+            base_seq: input.base_seq,
+            base_hash: input.base_hash,
+            current_sync: headMismatch.sync,
+            draft: eventDraftValue(input),
+            reason: "room_head_mismatch",
+            options: heldDraftOptions(),
+        };
+        this.state.drafts.set(draftId, {
+            draft,
+            request: { kind: "event", input },
+        });
+        return {
+            status: "held",
+            reason: "room_head_mismatch",
+            draft,
+            changes: headMismatch.changes,
+            sync: headMismatch.sync,
+        };
+    }
+    roomChangesSince(key, baseSeq) {
+        const room = this.localRoom(key);
+        if (baseSeq !== undefined) {
+            return room.timeline.filter((item) => item.seq > baseSeq);
+        }
+        return room.timeline.slice(-20);
+    }
+    nextDraftId(roomId) {
+        const room = [...roomId]
+            .map((ch) => (/[A-Za-z0-9_-]/.test(ch) ? ch : "_"))
+            .join("");
+        return `draft_${room}_${this.state.drafts.size + 1}`;
+    }
+    // ── Views.
+    syncState(key) {
+        const room = this.localRoom(key);
+        const headHash = room.headHash ?? room.room.head?.hash ?? room.room.hash;
+        return {
+            host: room.host,
+            room_id: key.roomId,
+            head_seq: room.headSeq,
+            head_hash: headHash,
+            synced_seq: room.syncedSeq,
+            remote_seq: Math.max(room.room.seq, room.syncedSeq),
+            subscribed: room.subscribed,
+            unread_count: unreadCount(room),
+            pending_inbox_count: this.pendingInboxCount(key.roomId),
+        };
+    }
+    roomStateView(room) {
+        const selfMember = room.members.get(this.agentId());
+        return {
+            host: room.host,
+            room_id: room.room.id,
+            status: room.room.status,
+            visibility: roomVisibility(room.room),
+            topic: roomTopic(room.room),
+            agenda: roomAgenda(room.room),
+            guidance: roomGuidance(room.room),
+            creator: room.room.envelope?.event.actor,
+            created_at: room.room.envelope?.event.created_at,
+            start_time: roomStartTime(room.room),
+            end_time: roomEndTime(room.room),
+            tags: roomTags(room.room),
+            language: roomLanguage(room.room),
+            policy: roomPolicy(room.room),
+            types: room.room.types ?? [],
+            self_member: selfMember,
+            members_count: room.members.size,
+            active_turn: room.activeTurn,
+            unread_count: unreadCount(room),
+            pending_inbox_count: this.pendingInboxCount(room.room.id),
+        };
+    }
+    summaryForRoom(room) {
+        return roomSummaryFromResponse(room.host, room.room, {
+            role: room.members.get(this.agentId())?.role,
+            unreadCount: unreadCount(room),
+            pendingInboxCount: this.pendingInboxCount(room.room.id),
+        });
+    }
+    summaryForResponse(host, room) {
+        const existing = this.state.rooms.get(roomKeyString({ host, roomId: room.id }));
+        if (existing)
+            return this.summaryForRoom(existing);
+        return roomSummaryFromResponse(host, room);
+    }
+    timelineItemByEvent(key, eventId) {
+        const item = this.localRoom(key).timeline.find((entry) => entry.event_id === eventId);
+        if (!item)
+            throw invalidPayload("timeline item not materialized");
+        return item;
+    }
+    // ── Internal helpers.
+    localRoom(key) {
+        const room = this.state.rooms.get(roomKeyString(key));
+        if (!room)
+            throw invalidPayload(`room is not open locally: ${key.roomId}`);
+        return room;
+    }
+    requireAllowedHost(host) {
+        const record = this.state.hosts.get(host);
+        if (!record || !record.allowed)
+            throw permissionDenied();
+    }
+    allowedRoomHost(key) {
+        const host = this.localRoom(key).host;
+        this.requireAllowedHost(host);
+        return host;
+    }
+    ensureHost(host) {
+        if (!this.state.hosts.has(host)) {
+            this.state.hosts.set(host, { host, allowed: false, features: [] });
+        }
+    }
+    insertInbox(item) {
+        if (!this.state.inbox.has(item.id)) {
+            this.state.inbox.set(item.id, { item, state: { kind: "pending" } });
+        }
+    }
+    pendingInboxCount(roomId) {
+        const now = unixTimeMillis();
+        let count = 0;
+        for (const entry of this.state.inbox.values()) {
+            if (!inboxEntryReady(entry, now))
+                continue;
+            if (roomId !== undefined && entry.item.room_id !== roomId)
+                continue;
+            count += 1;
+        }
+        return count;
+    }
+    sortedHosts() {
+        return [...this.state.hosts.entries()]
+            .sort((a, b) => compareStrings(a[0], b[0]))
+            .map(([, host]) => host);
+    }
+    discourse(host) {
+        return new DiscourseClient(host, this.fetchImpl);
+    }
+    profileClient(url) {
+        return new ProfileClient(url, this.fetchImpl);
+    }
+}
+//# sourceMappingURL=engine.js.map