@zooid/transport-matrix 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -155,6 +155,22 @@ declare class MatrixClient {
             display_name?: string;
         }>;
     }>;
+    sync(opts: {
+        asUserId: string;
+        since?: string | null;
+        timeoutMs?: number;
+    }): Promise<{
+        next_batch: string;
+        rooms: {
+            join: Record<string, {
+                timeline: {
+                    events: Record<string, unknown>[];
+                    prev_batch?: string;
+                    limited?: boolean;
+                };
+            }>;
+        };
+    }>;
     fetchRoomName(roomId: string, asUserId: string): Promise<string | null>;
     private sendEvent;
 }
@@ -200,6 +216,17 @@ interface MatrixTransportConfig {
 }
 declare function renderRegistration(c: MatrixTransportConfig): string;
 
+declare const SLUG_RE: RegExp;
+declare const AGENT_KEY_RE: RegExp;
+declare const isValidWorkstation: (s: string) => boolean;
+declare const isValidAgentKey: (s: string) => boolean;
+declare function agentMxid(workstation: string, agent: string, serverName: string): string;
+declare function splitAgentLocalpart(localpart: string): {
+    workstation: string;
+    agent: string;
+};
+declare function workstationUserNamespace(workstation: string, serverName: string): string;
+
 interface MaybeMessage {
     content?: {
         'm.mentions'?: {
@@ -236,6 +263,14 @@ interface ThreadState {
     participants: string[];
     /** Agent names @mentioned in the thread root event (or subsequently). */
     rootMentions: string[];
+    /**
+     * Agent-to-agent call edges: sub-agent name → the agent that @mentioned
+     * (called) it in this thread. A sub's bare reply bubbles up to its caller;
+     * a caller never implicitly re-triggers its callee. Makes agent↔agent
+     * acknowledgement loops structurally impossible. See [[ZOD039]] §
+     * Implicit triggers → Directional continuation.
+     */
+    callers: Record<string, string>;
 }
 interface MaybeEvent {
     type?: string;
@@ -287,6 +322,44 @@ declare function writeAttachment(input: WriteAttachmentInput): {
     agentPath: string;
 };
 
+interface SyncResponse {
+    next_batch: string;
+    rooms?: {
+        join?: Record<string, {
+            timeline?: {
+                events?: Record<string, unknown>[];
+                prev_batch?: string;
+                limited?: boolean;
+            };
+        }>;
+    };
+}
+interface SyncClient {
+    sync(opts: {
+        asUserId: string;
+        since: string | null;
+        timeoutMs: number;
+    }): Promise<SyncResponse>;
+}
+interface SyncLoopOptions {
+    client: SyncClient;
+    asUserId: string;
+    loadSince: () => string | null;
+    saveSince: (since: string) => void;
+    onEvent: (evt: Record<string, unknown>) => void | Promise<void>;
+    timeoutMs?: number;
+    /** Backoff after a failed tick before retrying. Default 5000ms. */
+    retryDelayMs?: number;
+}
+declare class SyncLoop {
+    private readonly opts;
+    private running;
+    constructor(opts: SyncLoopOptions);
+    tick(): Promise<void>;
+    run(): Promise<void>;
+    stop(): void;
+}
+
 interface MediaClientLike {
     download(input: {
         mxcUri: string;
@@ -327,9 +400,20 @@ interface CreateMatrixTransportOptions {
      *  bindings this forms the set of "our bot users" whose ad-hoc invites are
      *  declined. */
     botUserId?: string;
+    /**
+     * Transport ingestion mode.
+     * - `'appservice'` (default): Tuwunel pushes events to the HTTP transaction endpoint.
+     * - `'client'`: daemon polls via impersonated `/sync` per agent (pull mode).
+     */
+    mode?: 'appservice' | 'client';
+    /** Pull mode: load the persisted `since` cursor for an agent user ID. */
+    loadSince?: (agentUserId: string) => string | null;
+    /** Pull mode: persist the `since` cursor after each sync poll. */
+    saveSince?: (agentUserId: string, since: string) => void;
 }
 declare function createMatrixTransport(opts: CreateMatrixTransportOptions): {
     app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+    syncLoops: SyncLoop[] | undefined;
     bootstrap: (bootstrapOpts?: {
         spaceRoomId?: string;
         asUserId?: string;
@@ -474,4 +558,4 @@ declare class PendingMediaStore {
     drain(roomId: string, threadKey: string | undefined, sender: string): PendingMediaItem[];
 }
 
-export { type AgentBinding, BotPool, type CreateMatrixTransportOptions, type EnsureDefaultChannelOpts, type EnsureSpaceOpts, INLINE_IMAGE_MIMES, MAX_DOWNLOAD_BYTES, MAX_INLINE_IMAGE_BYTES, MAX_MEDIA_PER_TURN, MEDIA_MSGTYPES, MatrixClient, type MatrixClientOptions, MatrixContextProvider, type MatrixContextProviderOpts, type MatrixTransportConfig, type MaybeMessage, MediaClient, type MediaClientLike, type MediaClientOptions, type PendingMediaItem, PendingMediaStore, type PublishOpts, type PublisherHandle, type RouteMatch, type SendCustomEventInput, type SendMessageInput, type StartOpts as StartWorkforcePublisherOpts, type WorkforceRoster, type WriteAttachmentInput, buildWorkforceRoster, createMatrixTransport, ensureDefaultChannel, ensureWorkforceSpace, extractMentions, isMediaMsgtype, parseMxcUri, publishWorkforce, renderRegistration, route, serverNameFromMxid, startWorkforcePublisher, writeAttachment };
+export { AGENT_KEY_RE, type AgentBinding, BotPool, type CreateMatrixTransportOptions, type EnsureDefaultChannelOpts, type EnsureSpaceOpts, INLINE_IMAGE_MIMES, MAX_DOWNLOAD_BYTES, MAX_INLINE_IMAGE_BYTES, MAX_MEDIA_PER_TURN, MEDIA_MSGTYPES, MatrixClient, type MatrixClientOptions, MatrixContextProvider, type MatrixContextProviderOpts, type MatrixTransportConfig, type MaybeMessage, MediaClient, type MediaClientLike, type MediaClientOptions, type PendingMediaItem, PendingMediaStore, type PublishOpts, type PublisherHandle, type RouteMatch, SLUG_RE, type SendCustomEventInput, type SendMessageInput, type StartOpts as StartWorkforcePublisherOpts, type SyncClient, SyncLoop, type SyncLoopOptions, type SyncResponse, type WorkforceRoster, type WriteAttachmentInput, agentMxid, buildWorkforceRoster, createMatrixTransport, ensureDefaultChannel, ensureWorkforceSpace, extractMentions, isMediaMsgtype, isValidAgentKey, isValidWorkstation, parseMxcUri, publishWorkforce, renderRegistration, route, serverNameFromMxid, splitAgentLocalpart, startWorkforcePublisher, workstationUserNamespace, writeAttachment };