feat(appservice): room provisioning via bridge API (M4c, agent-comms#9)

POST /bridge/v1/provision/rooms (inside the authed bridge block): creates
rooms AS the appservice sender (PL 100 override), optional alias/topic/
invite/space. Space-link failures surface partial success (room_id +
space_linked:false + space_error) instead of orphaning the room behind an
exception (review blocker); invite list capped at 50 (review blocker:
amplification via stolen bridge token); alias length capped. 13+14 vitest.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

packages/appservice/src/bridge.dto.ts

@@ -50,3 +50,34 @@ export function validateBridgeTyping(input: unknown): asserts input is BridgeTyp
   assertAgentSlug(o.agent);
   if (typeof o.typing !== 'boolean') throw new Error('typing must be a boolean');
 }
+
+export interface ProvisionRoomDto {
+  name: string;
+  alias?: string;
+  topic?: string;
+  invite?: string[];
+  space_id?: string;
+}
+
+export function validateProvisionRoom(input: unknown): asserts input is ProvisionRoomDto {
+  const o = input as Partial<ProvisionRoomDto> | null | undefined;
+  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
+  if (typeof o.name !== 'string' || o.name.length === 0) throw new Error('name is required');
+  if (o.alias !== undefined && (!/^[a-z0-9_.-]+$/.test(o.alias) || o.alias.length > 200)) {
+    throw new Error('alias must match [a-z0-9_.-]+ (max 200 chars)');
+  }
+  if (o.invite !== undefined) {
+    if (
+      !Array.isArray(o.invite) ||
+      o.invite.some((u) => typeof u !== 'string' || !u.startsWith('@'))
+    ) {
+      throw new Error('invite must be a list of Matrix user ids');
+    }
+    if (o.invite.length > 50) {
+      throw new Error('invite list exceeds maximum of 50');
+    }
+  }
+  if (o.space_id !== undefined && (typeof o.space_id !== 'string' || !o.space_id.startsWith('!'))) {
+    throw new Error('space_id must be a Matrix room id');
+  }
+}

packages/appservice/src/index.ts

@@ -4,8 +4,12 @@ export { TransactionHandler } from './transactions.js';
 export type { TransactionHandlerOptions } from './transactions.js';
 export { buildRegistration, registrationToYaml } from './registration.js';
 export type { RegistrationOptions } from './registration.js';
-export { validateBridgeMessage, validateBridgeTyping } from './bridge.dto.js';
-export type { BridgeMessageDto, BridgeTypingDto } from './bridge.dto.js';
+export {
+  validateBridgeMessage,
+  validateBridgeTyping,
+  validateProvisionRoom,
+} from './bridge.dto.js';
+export type { BridgeMessageDto, BridgeTypingDto, ProvisionRoomDto } from './bridge.dto.js';
 export type {
   AppserviceConfig,
   EventHandler,

packages/appservice/src/intent.ts

@@ -172,6 +172,58 @@ export class AppserviceIntent {
     });
   }
 
+  /** Create a room as the AS sender: agents get PL 50 by namespace via the
+   * sender (PL 100); humans invited at default PL. Optionally link into a
+   * space (m.space.child + m.space.parent). Returns the room id. */
+  async createRoom(options: {
+    name: string;
+    alias?: string;
+    topic?: string;
+    invite?: string[];
+    spaceId?: string;
+  }): Promise<{ roomId: string; spaceLinked: boolean; spaceError?: string }> {
+    const body: Record<string, unknown> = {
+      name: options.name,
+      preset: 'private_chat',
+      invite: options.invite ?? [],
+      power_level_content_override: {
+        users: { [this.senderUserId]: 100 },
+        // state_default 50 stays; the AS sender can grant agents as needed.
+      },
+    };
+    if (options.alias) body.room_alias_name = options.alias;
+    if (options.topic) body.topic = options.topic;
+    const res = await this.request('POST', '/_matrix/client/v3/createRoom', {
+      userId: this.senderUserId,
+      body,
+    });
+    const roomId = res.room_id;
+    if (typeof roomId !== 'string') throw new Error('createRoom returned no room_id');
+    if (!options.spaceId) {
+      return { roomId, spaceLinked: false };
+    }
+    // Space-link failures must NOT throw: the room already exists, and an
+    // exception would hide the room_id (orphaned room, no recovery path).
+    const encodedSpaceId = encodeURIComponent(options.spaceId);
+    const encodedRoomId = encodeURIComponent(roomId);
+    try {
+      await this.request(
+        'PUT',
+        `/_matrix/client/v3/rooms/${encodedSpaceId}/state/m.space.child/${encodedRoomId}`,
+        { userId: this.senderUserId, body: { via: [this.cfg.domain], suggested: true } },
+      );
+      await this.request(
+        'PUT',
+        `/_matrix/client/v3/rooms/${encodedRoomId}/state/m.space.parent/${encodedSpaceId}`,
+        { userId: this.senderUserId, body: { via: [this.cfg.domain], canonical: true } },
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { roomId, spaceLinked: false, spaceError: message };
+    }
+    return { roomId, spaceLinked: true };
+  }
+
   /** Set display name for an agent's virtual user. */
   async setDisplayName(agent: string, displayName: string): Promise<void> {
     const userId = await this.ensureRegistered(agent);