@zooid/transport-matrix 0.7.0 → 0.7.2

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { TransportContextProvider, HistoryOptions, HistoryPage, ThreadOverviewPage, Member, ChannelInfo, AcpRegistry, ApprovalCorrelator } from '@zooid/core';
+import { TransportContextProvider, HistoryOptions, HistoryPage, ThreadOverviewPage, Member, ChannelInfo, RoomBinding, AcpRegistry, ApprovalCorrelator } from '@zooid/core';
 import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
 
@@ -53,6 +53,20 @@ declare class MatrixClient {
         /** Optional `m.room.name`. When set, sent in the createRoom body so the
          *  room has a display name from the moment it exists. */
         name?: string;
+        /** When set, the room is created with a `restricted` join rule whose allow
+         *  condition references this space room ID — i.e. joinable by space members
+         *  only, rather than the whole homeserver. */
+        restrictedToSpaceId?: string;
+        /** Explicit room version. Restricted join rules require v8+; omit to use the
+         *  homeserver default (modern Tuwunel defaults to v10/v11). */
+        roomVersion?: string;
+        /**
+         * Seeds `m.room.power_levels.users` at creation via
+         * `power_level_content_override.users`. The caller owns the full map —
+         * typically the AS bot at 100, plus operator and any agents with
+         * declared PLs. Empty/absent → no override (the preset's defaults apply).
+         */
+        userPowerLevels?: Record<string, number>;
     }): Promise<string>;
     createRoomRaw(opts: {
         asUserId: string;
@@ -67,6 +81,17 @@ declare class MatrixClient {
     }): Promise<{
         event_id: string;
     }>;
+    /**
+     * Invite a user to a room. Sent as the inviter (`asUserId`) — that user
+     * needs invite power in the room. Tolerates the "already in room /
+     * already invited" responses idempotently so bootstrap can run on a
+     * fresh AND a populated homeserver without branching.
+     */
+    invite(opts: {
+        roomId: string;
+        asUserId: string;
+        targetUserId: string;
+    }): Promise<void>;
     joinRoom(roomIdOrAlias: string, asUserId: string): Promise<void>;
     sendMessage(input: SendMessageInput): Promise<{
         event_id: string;
@@ -188,7 +213,13 @@ interface AgentBinding {
     userId: string;
     /** Optional human-readable display name. Falls back to the user_id localpart. */
     displayName?: string;
-    rooms: string[];
+    /**
+     * Rooms this agent is bound to. Each entry's `alias` starts out as the
+     * configured `#alias` (or `!id`) and is rewritten to the canonical room
+     * ID by `BotPool.bootstrap`. Optional `powerLevel` is seeded into the
+     * room's `m.room.power_levels.users` at room creation only.
+     */
+    rooms: RoomBinding[];
     trigger: 'mention' | 'any';
 }
 interface ThreadState {
@@ -219,11 +250,17 @@ interface BootstrapOpts {
     spaceRoomId?: string;
     /** AS bot user ID. Required when spaceRoomId is set; sender of the m.space.child write. */
     asUserId?: string;
+    /**
+     * Operator MXIDs seeded at PL 100 in every agent room this pool creates.
+     * Applied via `power_level_content_override.users` at room creation only —
+     * never reconciled. Empty/absent = no operator entries.
+     */
+    adminUserIds?: string[];
 }
 declare class BotPool {
     private readonly client;
     private readonly agents;
-    constructor(client: Pick<MatrixClient, 'registerBot' | 'joinRoom' | 'resolveAlias' | 'createRoom' | 'sendStateEvent' | 'setDisplayName'>, agents: AgentBinding[]);
+    constructor(client: Pick<MatrixClient, 'registerBot' | 'invite' | 'joinRoom' | 'resolveAlias' | 'createRoom' | 'sendStateEvent' | 'setDisplayName'>, agents: AgentBinding[]);
     bootstrap(opts?: BootstrapOpts): Promise<void>;
     findByUserId(userId: string): AgentBinding | undefined;
     findByName(name: string): AgentBinding | undefined;
@@ -237,12 +274,19 @@ interface CreateMatrixTransportOptions {
     hsToken: string;
     /** Admin Matrix user ID. When set, BotPool.bootstrap invites this user into rooms it creates. */
     adminUserId?: string;
+    /** Post-turn drain: keep collecting trailing `agent_message_chunk`s until the
+     *  buffer is quiet for this long before flushing. Defaults to `DRAIN_QUIET_MS`.
+     *  Set to 0 to disable the drain (e.g. in tests). */
+    drainQuietMs?: number;
+    /** Hard cap on the post-turn drain. Defaults to `DRAIN_MAX_MS`. */
+    drainMaxMs?: number;
 }
 declare function createMatrixTransport(opts: CreateMatrixTransportOptions): {
     app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
     bootstrap: (bootstrapOpts?: {
         spaceRoomId?: string;
         asUserId?: string;
+        adminUserIds?: string[];
     }) => Promise<void>;
     pool: BotPool;
 };
@@ -253,8 +297,38 @@ interface EnsureSpaceOpts {
     serverName: string;
     spaceLocalpart: string;
     preset: 'public_chat' | 'private_chat';
+    /**
+     * Operator MXIDs to seed at PL 100 in the space's `m.room.power_levels`
+     * at creation. The AS bot is always included. Empty/absent → no override
+     * (the preset's PL defaults apply). Only consulted on first creation —
+     * if the alias already resolves we return the existing room untouched.
+     */
+    admins?: string[];
 }
 declare function ensureWorkforceSpace(opts: EnsureSpaceOpts): Promise<string>;
+interface EnsureDefaultChannelOpts {
+    client: MatrixClient;
+    asUserId: string;
+    serverName: string;
+    spaceId: string;
+    /** Localpart of the default channel; defaults to `general`. */
+    channelLocalpart?: string;
+    /**
+     * Operator MXIDs to seed at PL 100 in the channel's `m.room.power_levels`
+     * at creation. The AS bot is always included. Empty/absent → no override
+     * (the preset's PL defaults apply). Only consulted on first creation —
+     * if the alias already resolves we return the existing room untouched.
+     */
+    admins?: string[];
+}
+/**
+ * Ensure a space has a default channel (`#general` by default), restricted to
+ * the space's members and attached as an `m.space.child`. Idempotent: returns
+ * the existing room if the alias already resolves. Has no agent — it's the
+ * human landing room, so it is created here at provisioning time rather than
+ * via the agent-room path.
+ */
+declare function ensureDefaultChannel(opts: EnsureDefaultChannelOpts): Promise<string>;
 declare function serverNameFromMxid(mxid: string): string;
 
 interface WorkforceRoster {
@@ -285,4 +359,4 @@ interface StartOpts {
 }
 declare function startWorkforcePublisher(opts: StartOpts): Promise<PublisherHandle>;
 
-export { type AgentBinding, BotPool, type CreateMatrixTransportOptions, type EnsureSpaceOpts, MatrixClient, type MatrixClientOptions, MatrixContextProvider, type MatrixContextProviderOpts, type MatrixTransportConfig, type MaybeMessage, type PublishOpts, type PublisherHandle, type RouteMatch, type SendCustomEventInput, type SendMessageInput, type StartOpts as StartWorkforcePublisherOpts, type WorkforceRoster, buildWorkforceRoster, createMatrixTransport, ensureWorkforceSpace, extractMentions, publishWorkforce, renderRegistration, route, serverNameFromMxid, startWorkforcePublisher };
+export { type AgentBinding, BotPool, type CreateMatrixTransportOptions, type EnsureDefaultChannelOpts, type EnsureSpaceOpts, MatrixClient, type MatrixClientOptions, MatrixContextProvider, type MatrixContextProviderOpts, type MatrixTransportConfig, type MaybeMessage, type PublishOpts, type PublisherHandle, type RouteMatch, type SendCustomEventInput, type SendMessageInput, type StartOpts as StartWorkforcePublisherOpts, type WorkforceRoster, buildWorkforceRoster, createMatrixTransport, ensureDefaultChannel, ensureWorkforceSpace, extractMentions, publishWorkforce, renderRegistration, route, serverNameFromMxid, startWorkforcePublisher };

package/dist/index.js

@@ -39,6 +39,22 @@ var MatrixClient = class {
       preset: opts.preset ?? "public_chat"
     };
     if (opts.name !== void 0) body.name = opts.name;
+    if (opts.roomVersion !== void 0) body.room_version = opts.roomVersion;
+    if (opts.restrictedToSpaceId !== void 0) {
+      body.initial_state = [
+        {
+          type: "m.room.join_rules",
+          state_key: "",
+          content: {
+            join_rule: "restricted",
+            allow: [{ type: "m.room_membership", room_id: opts.restrictedToSpaceId }]
+          }
+        }
+      ];
+    }
+    if (opts.userPowerLevels && Object.keys(opts.userPowerLevels).length > 0) {
+      body.power_level_content_override = { users: opts.userPowerLevels };
+    }
     const r = await this.fetch(
       `${this.homeserver}/_matrix/client/v3/createRoom?user_id=${encodeURIComponent(opts.senderUserId)}`,
       {
@@ -84,6 +100,30 @@ var MatrixClient = class {
     if (!r.ok) throw new Error(`sendStateEvent ${opts.eventType} failed: ${r.status}`);
     return await r.json();
   }
+  /**
+   * Invite a user to a room. Sent as the inviter (`asUserId`) — that user
+   * needs invite power in the room. Tolerates the "already in room /
+   * already invited" responses idempotently so bootstrap can run on a
+   * fresh AND a populated homeserver without branching.
+   */
+  async invite(opts) {
+    const url = `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(opts.roomId)}/invite?user_id=${encodeURIComponent(opts.asUserId)}`;
+    const r = await this.fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.asToken}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({ user_id: opts.targetUserId })
+    });
+    if (r.ok) return;
+    if (r.status === 403) {
+      const body = await r.text();
+      if (/already (in the room|invited|a member|joined)/i.test(body)) return;
+      throw new Error(`invite(${opts.targetUserId}) failed: 403 ${body}`);
+    }
+    throw new Error(`invite(${opts.targetUserId}) failed: ${r.status}`);
+  }
   async joinRoom(roomIdOrAlias, asUserId) {
     const url = `${this.homeserver}/_matrix/client/v3/join/${encodeURIComponent(roomIdOrAlias)}?user_id=${encodeURIComponent(asUserId)}`;
     const r = await this.fetch(url, {
@@ -412,7 +452,7 @@ function route(event, agents, threadStates) {
   const threadState = threadRoot ? threadStates?.get(threadRoot) : void 0;
   for (const a of agents) {
     if (event.sender === a.userId) continue;
-    if (!a.rooms.includes(event.room_id ?? "")) continue;
+    if (!a.rooms.some((r) => r.alias === event.room_id)) continue;
     if (a.trigger === "any") {
       matches.push(a);
       continue;
@@ -439,15 +479,50 @@ async function ensureWorkforceSpace(opts) {
   const existing = await opts.client.resolveAlias(alias);
   if (existing) return existing;
   const display = opts.spaceLocalpart.charAt(0).toUpperCase() + opts.spaceLocalpart.slice(1);
-  return opts.client.createRoomRaw({
+  const body = {
+    room_alias_name: opts.spaceLocalpart,
+    name: display,
+    preset: opts.preset,
+    creation_content: { type: "m.space" },
+    // A workspace is joined by invitation, not self-service. Pin the space's
+    // join rule to invite regardless of preset so it can't be walked into
+    // (which would otherwise satisfy every restricted child room's allow).
+    initial_state: [{ type: "m.room.join_rules", state_key: "", content: { join_rule: "invite" } }]
+  };
+  if (opts.admins && opts.admins.length > 0) {
+    body.invite = opts.admins;
+    const users = { [opts.asUserId]: 100 };
+    for (const a of opts.admins) users[a] = 100;
+    body.power_level_content_override = { users };
+  }
+  return opts.client.createRoomRaw({ asUserId: opts.asUserId, body });
+}
+async function ensureDefaultChannel(opts) {
+  const localpart2 = opts.channelLocalpart ?? "general";
+  const alias = `#${localpart2}:${opts.serverName}`;
+  const existing = await opts.client.resolveAlias(alias);
+  if (existing) return existing;
+  let userPowerLevels;
+  if (opts.admins && opts.admins.length > 0) {
+    userPowerLevels = { [opts.asUserId]: 100 };
+    for (const a of opts.admins) userPowerLevels[a] = 100;
+  }
+  const roomId = await opts.client.createRoom({
+    roomAliasName: localpart2,
+    invite: [],
+    senderUserId: opts.asUserId,
+    name: localpart2.charAt(0).toUpperCase() + localpart2.slice(1),
+    restrictedToSpaceId: opts.spaceId,
+    ...userPowerLevels ? { userPowerLevels } : {}
+  });
+  await opts.client.sendStateEvent({
+    roomId: opts.spaceId,
     asUserId: opts.asUserId,
-    body: {
-      room_alias_name: opts.spaceLocalpart,
-      name: display,
-      preset: opts.preset,
-      creation_content: { type: "m.space" }
-    }
+    eventType: "m.space.child",
+    stateKey: roomId,
+    content: { via: [opts.serverName] }
   });
+  return roomId;
 }
 function serverNameFromMxid(mxid) {
   const colon = mxid.indexOf(":");
@@ -478,8 +553,23 @@ var BotPool = class {
       } catch (err) {
         console.warn(`[matrix] setDisplayName(${a.userId}) failed: ${err.message}`);
       }
+      if (opts.spaceRoomId && opts.asUserId) {
+        try {
+          await this.client.invite({
+            roomId: opts.spaceRoomId,
+            asUserId: opts.asUserId,
+            targetUserId: a.userId
+          });
+          await this.client.joinRoom(opts.spaceRoomId, a.userId);
+        } catch (err) {
+          console.warn(
+            `[matrix] space membership for ${a.userId} failed: ${err.message}`
+          );
+        }
+      }
       for (let i = 0; i < a.rooms.length; i++) {
-        const room = a.rooms[i];
+        const binding = a.rooms[i];
+        const room = binding.alias;
         try {
           let resolved = room;
           if (room.startsWith("#")) {
@@ -494,17 +584,25 @@ var BotPool = class {
                 const colon = room.indexOf(":");
                 const aliasLocalpart = colon > 1 ? room.slice(1, colon) : room.slice(1);
                 const sender = opts.adminUserId ?? a.userId;
+                const userPowerLevels = buildUserPowerLevels(
+                  opts.asUserId,
+                  opts.adminUserIds,
+                  this.agents,
+                  room
+                );
                 resolved = await this.client.createRoom({
                   roomAliasName: aliasLocalpart,
                   invite: opts.adminUserId ? [opts.adminUserId] : [],
                   senderUserId: sender,
-                  name: aliasLocalpart
+                  name: aliasLocalpart,
+                  ...opts.spaceRoomId ? { restrictedToSpaceId: opts.spaceRoomId } : {},
+                  ...userPowerLevels ? { userPowerLevels } : {}
                 });
               }
               aliasToId.set(room, resolved);
             }
           }
-          a.rooms[i] = resolved;
+          binding.alias = resolved;
           await this.client.joinRoom(resolved, a.userId);
           if (opts.spaceRoomId && opts.asUserId && !attachedToSpace.has(resolved)) {
             attachedToSpace.add(resolved);
@@ -543,6 +641,18 @@ function localpart(userId) {
   if (!m) throw new Error(`bad user id: ${userId}`);
   return m[1];
 }
+function buildUserPowerLevels(asUserId, admins, agents, roomAlias) {
+  const users = {};
+  if (asUserId) users[asUserId] = 100;
+  if (admins) for (const a of admins) users[a] = 100;
+  for (const a of agents) {
+    for (const r of a.rooms) {
+      if (r.alias !== roomAlias) continue;
+      if (r.powerLevel !== void 0) users[a.userId] = r.powerLevel;
+    }
+  }
+  return Object.keys(users).length > 0 ? users : void 0;
+}
 
 // src/transport.ts
 import { Hono } from "hono";
@@ -596,6 +706,33 @@ function toPlanBody(evt) {
     entries: evt.entries
   };
 }
+var RECOVERY_URLS = {
+  auth_missing: "https://zooid.dev/docs/guides/run-in-container#authentication-that-carries-over",
+  auth_invalid: "https://zooid.dev/docs/guides/run-in-container#authentication-that-carries-over",
+  mount_failed: "https://zooid.dev/docs/guides/run-in-container#what-you-get-for-free",
+  image_pull_failed: "https://zooid.dev/docs/guides/run-in-container#skipping-the-image-prepull"
+};
+function toErrorBody(evt, threadRoot) {
+  const msg = evt.message.slice(0, 250);
+  const out = {
+    msgtype: "m.notice",
+    body: `\u26A0 [${evt.code}] ${msg}`,
+    code: evt.code,
+    message: msg,
+    transient: evt.transient,
+    "m.relates_to": { rel_type: "m.thread", event_id: threadRoot }
+  };
+  if (evt.sessionId) out.session_id = evt.sessionId;
+  if (evt.turnId) out.turn_id = evt.turnId;
+  if (evt.detail) out.detail = evt.detail.slice(0, 2e3);
+  if (evt.acp_error) out.acp_error = evt.acp_error;
+  const recovery = RECOVERY_URLS[evt.code];
+  if (recovery) out.recovery = recovery;
+  return out;
+}
+
+// src/transport.ts
+import { classify } from "@zooid/acp-client";
 
 // src/markdown-to-matrix-html.ts
 import { marked } from "marked";
@@ -669,12 +806,17 @@ function toMatrixHtml(markdown) {
 // src/transport.ts
 var STARTUP_GRACE_MS = 5e3;
 var SEEN_EVENT_CAP = 5e3;
+var DRAIN_QUIET_MS = 300;
+var DRAIN_MAX_MS = 3e3;
+var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 function inboundThreadRoot2(evt) {
   const r = evt.content?.["m.relates_to"];
   return r?.rel_type === "m.thread" && r.event_id ? r.event_id : void 0;
 }
 function createMatrixTransport(opts) {
   const { agents, approvals, client, bindings, hsToken, adminUserId } = opts;
+  const drainQuietMs = opts.drainQuietMs ?? DRAIN_QUIET_MS;
+  const drainMaxMs = opts.drainMaxMs ?? DRAIN_MAX_MS;
   const pool = new BotPool(client, bindings);
   const sessions = /* @__PURE__ */ new Map();
   const buffers = /* @__PURE__ */ new Map();
@@ -691,7 +833,9 @@ function createMatrixTransport(opts) {
     if (event.type === "agent_message_chunk") {
       const block = event.content;
       if (block.type === "text" && typeof block.text === "string") {
-        buffers.set(event.sessionId, (buffers.get(event.sessionId) ?? "") + block.text);
+        const current = buffers.get(event.sessionId) ?? "";
+        const prefix = block.text === "" && current.length > 0 ? "\n\n" : "";
+        buffers.set(event.sessionId, current + prefix + block.text);
       } else {
         console.warn(`[matrix:${name}] dropped chunk block type=${block.type}`, block);
       }
@@ -879,6 +1023,29 @@ function createMatrixTransport(opts) {
           if (st.participants.at(-1) !== a.name) st.participants.push(a.name);
         }).catch((err) => {
           console.error(`[matrix] runTurn failed for ${a.name}:`, err);
+          const c2 = classify(err);
+          const threadRoot = inboundThreadRoot2(evt) ?? evt.event_id;
+          if (!threadRoot || !evt.room_id) return;
+          const body2 = toErrorBody(
+            {
+              kind: "error",
+              agentId: a.name,
+              sessionId: null,
+              turnId: null,
+              code: c2.code,
+              message: err instanceof Error ? err.message : String(err),
+              detail: err instanceof Error && err.stack ? err.stack.slice(0, 2e3) : void 0,
+              transient: c2.transient,
+              acp_error: c2.acp_error
+            },
+            threadRoot
+          );
+          void client.sendCustomEvent({
+            roomId: evt.room_id,
+            asUserId: a.userId,
+            eventType: "eco.zoon.error",
+            content: body2
+          }).catch((e) => console.warn(`[matrix:${a.name}] eco.zoon.error send failed:`, e));
         });
       }
     }
@@ -931,6 +1098,14 @@ function createMatrixTransport(opts) {
         channelId: evt.room_id,
         content: [{ type: "text", text: promptText }]
       });
+      const drainStart = Date.now();
+      let drained = buffers.get(sessionId) ?? "";
+      while (drainQuietMs > 0 && Date.now() - drainStart < drainMaxMs) {
+        await delay(drainQuietMs);
+        const next = buffers.get(sessionId) ?? "";
+        if (next === drained) break;
+        drained = next;
+      }
       const text = buffers.get(sessionId) ?? "";
       if (text.length > 0) {
         const html = toMatrixHtml(text);
@@ -982,7 +1157,7 @@ function createMatrixTransport(opts) {
 }
 async function rebuildThreadState(client, roomId, rootEventId, bindings) {
   const state = { participants: [], rootMentions: [] };
-  const asUser = (bindings.find((b) => b.rooms.includes(roomId)) ?? bindings[0])?.userId;
+  const asUser = (bindings.find((b) => b.rooms.some((r) => r.alias === roomId)) ?? bindings[0])?.userId;
   if (!asUser) return state;
   const root = await client.fetchEvent(roomId, rootEventId, asUser);
   if (root) {
@@ -1037,7 +1212,11 @@ function truncate(s, n) {
 function buildWorkforceRoster(agents) {
   return {
     version: 1,
-    agents: agents.map((a) => ({ user_id: a.userId, name: a.name, rooms: a.rooms }))
+    agents: agents.map((a) => ({
+      user_id: a.userId,
+      name: a.name,
+      rooms: a.rooms.map((r) => r.alias)
+    }))
   };
 }
 async function publishWorkforce(opts) {
@@ -1065,6 +1244,7 @@ export {
   MatrixContextProvider,
   buildWorkforceRoster,
   createMatrixTransport,
+  ensureDefaultChannel,
   ensureWorkforceSpace,
   extractMentions,
   publishWorkforce,