@zooid/transport-matrix 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { TransportContextProvider, HistoryOptions, HistoryPage, ThreadOverviewPage, Member, ChannelInfo, RoomBinding, AcpRegistry, ApprovalCorrelator } from '@zooid/core';
+import { TransportContextProvider, RoomBinding, HistoryOptions, HistoryPage, ThreadOverviewPage, Member, RoomInfo, SendMessageInput as SendMessageInput$1, SendMessageResult, AcpRegistry, ApprovalCorrelator, PendingInputRegistry, TaskActions, InvocationRecord, ThreadCompletion, ThreadStartContent } from '@zooid/core';
 import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
 
@@ -16,12 +16,14 @@ interface SendMessageInput {
         [k: string]: unknown;
     };
     threadRoot?: string;
+    txnId?: string;
 }
 interface SendCustomEventInput {
     roomId: string;
     asUserId: string;
     eventType: string;
     content: Record<string, unknown>;
+    txnId?: string;
 }
 interface SetTypingInput {
     roomId: string;
@@ -177,10 +179,30 @@ declare class MatrixClient {
 
 interface MatrixContextProviderOpts {
     client: MatrixClient;
-    /** AS sender_localpart user (read access). */
+    /**
+     * The **agent's own** Matrix user (`@{workstation}.{name}:server`), which
+     * every read is impersonated as via `?user_id=`. Not the AS bot: that would
+     * read every room on the homeserver and make this class the only thing
+     * standing between an agent and someone else's conversation.
+     *
+     * This is load-bearing. It is what makes the homeserver — not our own
+     * bookkeeping — the authorization boundary for context reads, so a room or
+     * thread the agent is not in fails at Matrix with 403/404. Anything that
+     * widens who can name a room (a CLI, a new tool parameter) is safe only
+     * while this holds.
+     */
     asUserId: string;
     /** Map of Matrix user IDs → agent names, for is_agent / agent_name flags. */
     agentBots: Map<string, string>;
+    /**
+     * This agent's own room bindings — the live array `BotPool.bootstrap`
+     * rewrites `.alias` on in place, so reads through this field after
+     * bootstrap see canonical room IDs. Backs `getRooms()` and the
+     * `sendMessage()` authorization check. Absent/empty = no rooms known
+     * (context providers built before this field existed, or in tests that
+     * don't exercise either method).
+     */
+    rooms?: RoomBinding[];
 }
 declare class MatrixContextProvider implements TransportContextProvider {
     private readonly opts;
@@ -190,7 +212,9 @@ declare class MatrixContextProvider implements TransportContextProvider {
     getThreadHistory(channelId: string, threadId: string, hopts: HistoryOptions): Promise<HistoryPage>;
     private toMessage;
     getChannelMembers(channelId: string): Promise<Member[]>;
-    getChannelInfo(channelId: string): Promise<ChannelInfo>;
+    getRoomInfo(channelId: string): Promise<RoomInfo>;
+    getRooms(): Promise<RoomInfo[]>;
+    sendMessage(input: SendMessageInput$1): Promise<SendMessageResult>;
 }
 
 interface MatrixTransportConfig {
@@ -279,6 +303,10 @@ interface ThreadState {
      */
     handoffs: Record<string, string[]>;
 }
+interface TaskThreadContext {
+    assignee: string;
+    isRoot: boolean;
+}
 interface MaybeEvent {
     type?: string;
     room_id?: string;
@@ -292,7 +320,7 @@ interface MaybeEvent {
     };
 }
 type RouteMatch = AgentBinding;
-declare function route(event: MaybeEvent, agents: AgentBinding[], threadStates?: Map<string, ThreadState>): RouteMatch[];
+declare function route(event: MaybeEvent, agents: AgentBinding[], threadStates?: Map<string, ThreadState>, task?: TaskThreadContext): RouteMatch[];
 
 interface BootstrapOpts {
     /** Invited to any newly-created room; absent = no invite. */
@@ -367,6 +395,69 @@ declare class SyncLoop {
     stop(): void;
 }
 
+declare const MAX_OPEN_TASKS_PER_ROOM = 5;
+type TaskPhase = 'reserved' | 'uncertain' | 'open' | 'closed';
+interface TaskRecord {
+    taskId: string;
+    attemptId: string;
+    roomId: string;
+    assignee: string;
+    notify: 'caller' | 'none';
+    parent: {
+        agent: string;
+        threadRoot: string;
+        sessionKey: string;
+        generation: number;
+    };
+    phase: TaskPhase;
+    threadRoot?: string;
+    summary?: string;
+    runId?: string;
+    closedAt?: string;
+}
+interface PersistedTask extends Required<Pick<TaskRecord, 'taskId' | 'attemptId' | 'roomId' | 'assignee' | 'notify' | 'parent' | 'phase'>> {
+    threadRoot?: string;
+    summary?: string;
+    runId: string;
+    closedAt?: string;
+}
+interface TaskJournal {
+    load(): PersistedTask[];
+    save(tasks: PersistedTask[]): void;
+}
+declare class TaskRegistry {
+    private readonly opts;
+    private readonly tasks;
+    private readonly byRoot;
+    private readonly generations;
+    private readonly runIdValue;
+    constructor(opts?: {
+        maxOpenPerRoom?: number;
+        newId?: () => string;
+        journal?: TaskJournal;
+        runId?: string;
+        maxClosedRecords?: number;
+    });
+    private get max();
+    private get runId();
+    private save;
+    openCount(roomId: string): number;
+    reserve(input: Omit<TaskRecord, 'taskId' | 'attemptId' | 'phase' | 'threadRoot' | 'summary'>): TaskRecord | undefined;
+    activate(taskId: string, threadRoot: string): void;
+    abandon(taskId: string): void;
+    markUncertain(taskId: string): void;
+    adopt(attemptId: string, threadRoot: string): TaskRecord | undefined;
+    taskForRoot(threadRoot: string): TaskRecord | undefined;
+    openTaskFor(agent: string, root: string): TaskRecord | undefined;
+    recordSummary(id: string, summary: string): "recorded" | "already_recorded";
+    clearSummary(id: string): void;
+    close(id: string): boolean;
+    /** Reconcile records from a prior daemon run and retain closed roots for trust checks. */
+    restore(): TaskRecord[];
+    generationOf(agent: string, session: string): number;
+    bumpGeneration(agent: string, session: string): void;
+}
+
 interface MediaClientLike {
     download(input: {
         mxcUri: string;
@@ -417,9 +508,16 @@ interface CreateMatrixTransportOptions {
     loadSince?: (agentUserId: string) => string | null;
     /** Pull mode: persist the `since` cursor after each sync poll. */
     saveSince?: (agentUserId: string, since: string) => void;
+    /** Durable lifecycle state; supplied by the daemon when it has a data directory. */
+    taskJournal?: TaskJournal;
+    taskRunId?: string;
+    pendingInput?: PendingInputRegistry;
+    /** Deferred-return fallback window. Defaults to `RETURN_GRACE_MS`. */
+    returnGraceMs?: number;
 }
 declare function createMatrixTransport(opts: CreateMatrixTransportOptions): {
     app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+    taskActions: TaskActions;
     syncLoops: SyncLoop[] | undefined;
     bootstrap: (bootstrapOpts?: {
         spaceRoomId?: string;
@@ -565,4 +663,65 @@ declare class PendingMediaStore {
     drain(roomId: string, threadKey: string | undefined, sender: string): PendingMediaItem[];
 }
 
-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 };
+declare class InvocationRegistry {
+    private readonly opts;
+    private readonly records;
+    private readonly byCallee;
+    private readonly byEvent;
+    constructor(opts?: {
+        newId?: () => string;
+    });
+    open(input: Omit<InvocationRecord, 'invocationId' | 'state'>): InvocationRecord;
+    attachCallEvent(id: string, eventId: string, sessionKey: string): void;
+    get(id: string): InvocationRecord | undefined;
+    byCallEvent(eventId: string): InvocationRecord | undefined;
+    forCalleeSession(session: string): InvocationRecord | undefined;
+    outstandingFor(session: string): InvocationRecord[];
+    outstandingForTask(taskId: string): InvocationRecord[];
+    resolve(id: string): InvocationRecord | undefined;
+    cancelForTask(taskId: string): InvocationRecord[];
+    ancestorAgents(session: string): string[];
+    isOutstandingAncestor(session: string, agent: string): boolean;
+}
+
+/** ACP's stable prompt termination values (kept local to avoid an SDK runtime dep). */
+type StopReason = 'end_turn' | 'max_tokens' | 'max_turn_requests' | 'refusal' | 'cancelled';
+interface CompletionInputs {
+    agent: string;
+    threadId: string;
+    stopReason?: StopReason;
+    error?: unknown;
+    summary?: string;
+    prose?: string;
+    outstanding: number;
+    awaitingHuman: number;
+}
+type CompletionDecision = {
+    decision: 'stay_open';
+    reason: 'outstanding_handoff' | 'awaiting_human';
+} | {
+    decision: 'finish';
+    completion: ThreadCompletion;
+};
+declare function evaluateCompletion(input: CompletionInputs): CompletionDecision;
+
+type Admission = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+declare function checkDelegable(agentName: string, roomId: string, bindings: AgentBinding[]): Admission;
+declare function buildAssignmentContent(input: {
+    assigneeUserId: string;
+    prompt: string;
+    start: ThreadStartContent;
+}): {
+    msgtype: string;
+    body: string;
+    [key: string]: unknown;
+};
+declare function renderCompletionPrompt(c: ThreadCompletion): string;
+declare function renderInvocationReturn(c: ThreadCompletion): string;
+
+export { AGENT_KEY_RE, type AgentBinding, BotPool, type CompletionDecision, type CompletionInputs, type CreateMatrixTransportOptions, type EnsureDefaultChannelOpts, type EnsureSpaceOpts, INLINE_IMAGE_MIMES, InvocationRegistry, MAX_DOWNLOAD_BYTES, MAX_INLINE_IMAGE_BYTES, MAX_MEDIA_PER_TURN, MAX_OPEN_TASKS_PER_ROOM, MEDIA_MSGTYPES, MatrixClient, type MatrixClientOptions, MatrixContextProvider, type MatrixContextProviderOpts, type MatrixTransportConfig, type MaybeMessage, MediaClient, type MediaClientLike, type MediaClientOptions, type PendingMediaItem, PendingMediaStore, type PersistedTask, type PublishOpts, type PublisherHandle, type RouteMatch, SLUG_RE, type SendCustomEventInput, type SendMessageInput, type StartOpts as StartWorkforcePublisherOpts, type StopReason, type SyncClient, SyncLoop, type SyncLoopOptions, type SyncResponse, type TaskJournal, type TaskPhase, type TaskRecord, TaskRegistry, type WorkforceRoster, type WriteAttachmentInput, agentMxid, buildAssignmentContent, buildWorkforceRoster, checkDelegable, createMatrixTransport, ensureDefaultChannel, ensureWorkforceSpace, evaluateCompletion, extractMentions, isMediaMsgtype, isValidAgentKey, isValidWorkstation, parseMxcUri, publishWorkforce, renderCompletionPrompt, renderInvocationReturn, renderRegistration, route, serverNameFromMxid, splitAgentLocalpart, startWorkforcePublisher, workstationUserNamespace, writeAttachment };