@zooid/transport-matrix 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zooid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,288 @@
+import { TransportContextProvider, HistoryOptions, HistoryPage, ThreadOverviewPage, Member, ChannelInfo, AcpRegistry, ApprovalCorrelator } from '@zooid/core';
+import * as hono_types from 'hono/types';
+import { Hono } from 'hono';
+
+interface MatrixClientOptions {
+    homeserver: string;
+    asToken: string;
+    fetch?: typeof globalThis.fetch;
+}
+interface SendMessageInput {
+    roomId: string;
+    asUserId: string;
+    content: {
+        msgtype: string;
+        body: string;
+        [k: string]: unknown;
+    };
+    threadRoot?: string;
+}
+interface SendCustomEventInput {
+    roomId: string;
+    asUserId: string;
+    eventType: string;
+    content: Record<string, unknown>;
+}
+interface SetTypingInput {
+    roomId: string;
+    asUserId: string;
+    typing: boolean;
+    /** ms — homeserver expects re-PUTs before this expires. Ignored when typing=false. */
+    timeoutMs?: number;
+}
+interface SetPresenceInput {
+    asUserId: string;
+    presence: 'online' | 'unavailable' | 'offline';
+    statusMsg?: string;
+}
+declare class MatrixClient {
+    private readonly homeserver;
+    private readonly asToken;
+    private readonly fetch;
+    constructor(opts: MatrixClientOptions);
+    registerBot(localpart: string): Promise<{
+        user_id: string;
+        device_id: string;
+    } | undefined>;
+    resolveAlias(alias: string): Promise<string | null>;
+    createRoom(opts: {
+        roomAliasName: string;
+        invite: string[];
+        senderUserId: string;
+        preset?: 'public_chat' | 'private_chat' | 'trusted_private_chat';
+        /** 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;
+    }): Promise<string>;
+    createRoomRaw(opts: {
+        asUserId: string;
+        body: Record<string, unknown>;
+    }): Promise<string>;
+    sendStateEvent(opts: {
+        roomId: string;
+        asUserId: string;
+        eventType: string;
+        stateKey?: string;
+        content: Record<string, unknown>;
+    }): Promise<{
+        event_id: string;
+    }>;
+    joinRoom(roomIdOrAlias: string, asUserId: string): Promise<void>;
+    sendMessage(input: SendMessageInput): Promise<{
+        event_id: string;
+    }>;
+    sendCustomEvent(input: SendCustomEventInput): Promise<{
+        event_id: string;
+    }>;
+    setTyping(input: SetTypingInput): Promise<void>;
+    setDisplayName(asUserId: string, displayName: string): Promise<void>;
+    setPresence(input: SetPresenceInput): Promise<void>;
+    /**
+     * Fetch a single event from a room. Used to recover thread-root context
+     * after a daemon restart wipes the in-memory threadStates cache.
+     */
+    fetchEvent(roomId: string, eventId: string, asUserId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Fetch replies to a thread root via the relations endpoint, oldest-first.
+     * Pass `limit` and `from` for pagination; `next_batch` echoes back when
+     * there are more replies. Returns `{ chunk: [] }` when the root is unknown.
+     */
+    fetchThreadRelations(opts: {
+        roomId: string;
+        rootEventId: string;
+        asUserId: string;
+        limit?: number;
+        from?: string;
+    }): Promise<{
+        chunk: Array<Record<string, unknown>>;
+        next_batch?: string;
+    }>;
+    /**
+     * Paginate the room timeline. Returns events newest-first (dir=b) per Matrix
+     * spec. The caller is responsible for reversing if it wants oldest-first.
+     */
+    fetchRoomMessages(opts: {
+        roomId: string;
+        asUserId: string;
+        limit?: number;
+        /** Opaque pagination token returned in `end` from a previous call. */
+        from?: string;
+        /**
+         * Server-side RoomEventFilter. Common keys: `types` (whitelist event types),
+         * `not_types`, `not_rel_types` (e.g. `['m.thread']` to exclude thread
+         * replies). Encoded as JSON into the `filter` query param.
+         */
+        filter?: {
+            types?: string[];
+            not_types?: string[];
+            rel_types?: string[];
+            not_rel_types?: string[];
+        };
+    }): Promise<{
+        chunk: Array<Record<string, unknown>>;
+        end?: string;
+    }>;
+    getJoinedMembers(roomId: string, asUserId: string): Promise<{
+        joined: Record<string, {
+            display_name?: string;
+        }>;
+    }>;
+    fetchRoomName(roomId: string, asUserId: string): Promise<string | null>;
+    private sendEvent;
+}
+
+interface MatrixContextProviderOpts {
+    client: MatrixClient;
+    /** AS sender_localpart user (read access). */
+    asUserId: string;
+    /** Map of Matrix user IDs → agent names, for is_agent / agent_name flags. */
+    agentBots: Map<string, string>;
+}
+declare class MatrixContextProvider implements TransportContextProvider {
+    private readonly opts;
+    constructor(opts: MatrixContextProviderOpts);
+    getRoomHistory(channelId: string, hopts: HistoryOptions): Promise<HistoryPage>;
+    getRecentThreads(channelId: string, hopts: HistoryOptions): Promise<ThreadOverviewPage>;
+    getThreadHistory(channelId: string, threadId: string, hopts: HistoryOptions): Promise<HistoryPage>;
+    private toMessage;
+    getChannelMembers(channelId: string): Promise<Member[]>;
+    getChannelInfo(channelId: string): Promise<ChannelInfo>;
+}
+
+interface MatrixTransportConfig {
+    id: string;
+    url: string;
+    homeserver: string;
+    asToken: string;
+    hsToken: string;
+    senderLocalpart: string;
+    /** Regex covering all bot users, e.g. `@.*:example.com` */
+    userNamespace: string;
+    /**
+     * Optional regex covering aliases the AS may claim, e.g. `#.*:example.com`.
+     * Required when the AS calls `createRoom` with a `room_alias_name`.
+     */
+    aliasNamespace?: string;
+    /**
+     * Whether the AS exclusively owns the user_namespace. Default true.
+     * Set false when humans share the namespace (e.g., `zooid dev` registers
+     * a predefined admin under the same `@.*:localhost` regex).
+     */
+    exclusive?: boolean;
+}
+declare function renderRegistration(c: MatrixTransportConfig): string;
+
+interface MaybeMessage {
+    content?: {
+        'm.mentions'?: {
+            user_ids?: string[];
+        };
+        body?: string;
+        formatted_body?: string;
+    };
+}
+declare function extractMentions(event: MaybeMessage): string[];
+
+interface AgentBinding {
+    name: string;
+    userId: string;
+    /** Optional human-readable display name. Falls back to the user_id localpart. */
+    displayName?: string;
+    rooms: string[];
+    trigger: 'mention' | 'any';
+}
+interface ThreadState {
+    /** Agent names that have posted in this thread, in order. */
+    participants: string[];
+    /** Agent names @mentioned in the thread root event (or subsequently). */
+    rootMentions: string[];
+}
+interface MaybeEvent {
+    type?: string;
+    room_id?: string;
+    sender?: string;
+    content?: {
+        msgtype?: string;
+        'm.relates_to'?: {
+            rel_type?: string;
+            event_id?: string;
+        };
+    };
+}
+type RouteMatch = AgentBinding;
+declare function route(event: MaybeEvent, agents: AgentBinding[], threadStates?: Map<string, ThreadState>): RouteMatch[];
+
+interface BootstrapOpts {
+    /** Invited to any newly-created room; absent = no invite. */
+    adminUserId?: string;
+    /** Workforce space room ID. When set, every resolved agent room is attached as m.space.child. */
+    spaceRoomId?: string;
+    /** AS bot user ID. Required when spaceRoomId is set; sender of the m.space.child write. */
+    asUserId?: string;
+}
+declare class BotPool {
+    private readonly client;
+    private readonly agents;
+    constructor(client: Pick<MatrixClient, 'registerBot' | 'joinRoom' | 'resolveAlias' | 'createRoom' | 'sendStateEvent' | 'setDisplayName'>, agents: AgentBinding[]);
+    bootstrap(opts?: BootstrapOpts): Promise<void>;
+    findByUserId(userId: string): AgentBinding | undefined;
+    findByName(name: string): AgentBinding | undefined;
+}
+
+interface CreateMatrixTransportOptions {
+    agents: AcpRegistry;
+    approvals: ApprovalCorrelator;
+    client: MatrixClient;
+    bindings: AgentBinding[];
+    hsToken: string;
+    /** Admin Matrix user ID. When set, BotPool.bootstrap invites this user into rooms it creates. */
+    adminUserId?: string;
+}
+declare function createMatrixTransport(opts: CreateMatrixTransportOptions): {
+    app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+    bootstrap: (bootstrapOpts?: {
+        spaceRoomId?: string;
+        asUserId?: string;
+    }) => Promise<void>;
+    pool: BotPool;
+};
+
+interface EnsureSpaceOpts {
+    client: MatrixClient;
+    asUserId: string;
+    serverName: string;
+    spaceLocalpart: string;
+    preset: 'public_chat' | 'private_chat';
+}
+declare function ensureWorkforceSpace(opts: EnsureSpaceOpts): Promise<string>;
+declare function serverNameFromMxid(mxid: string): string;
+
+interface WorkforceRoster {
+    version: 1;
+    agents: {
+        user_id: string;
+        name: string;
+        rooms: string[];
+    }[];
+}
+declare function buildWorkforceRoster(agents: AgentBinding[]): WorkforceRoster;
+interface PublishOpts {
+    client: MatrixClient;
+    spaceRoomId: string;
+    asUserId: string;
+    agents: AgentBinding[];
+}
+declare function publishWorkforce(opts: PublishOpts): Promise<void>;
+interface PublisherHandle {
+    reload(): Promise<void>;
+    stop(): Promise<void>;
+}
+interface StartOpts {
+    client: MatrixClient;
+    spaceRoomId: string;
+    asUserId: string;
+    getAgents: () => AgentBinding[];
+}
+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 };