@finalai/agents 0.8.0

package/dist/modules/agent-client/conversations.d.mts

@@ -0,0 +1,385 @@
+import { type ProcessInspectionRequestIface, type ProcessInspectionResultIface } from '@finalai/agent-protocol';
+import { AgentSessionState, type AgentRealtimeEvent, type AgentTurnPolicy, type AttachmentDownloadIface, type AttachmentUploadIface, type ContentInput, type ConversationIface, type ConversationKind, type ConversationLinkIface, type ConversationListIface, type ConversationMessageIface, type ConversationMessagesPageIface, type ConversationSandboxIface, type ConversationScheduleIface, type CreateConversationScheduleRequestIface, type DecisionsPageIface, type MessageDeliveryIface, type ParticipantIface, type ParticipantInput, type PostConversationEventRequestIface, type ReactionIface, type ReadStateIface, type RespondPendingResponseIface, type SandboxDirectoryIface, type SandboxEditorSessionIface, type SandboxFileIface, type SandboxPathIface, type SandboxPreviewType, type SandboxSearchIface, type SearchMessagesPageIface, type UpdateConversationRequestIface, type UpdateConversationScheduleRequestIface, type UpdateParticipantRequestIface, type WireFallback } from '@finalai/agent-protocol/agent-platform';
+import { type CollectionEvent, type CollectionEventsOptionsIface } from "./collection-events.mjs";
+import { type ClientContextIface, type EnumInput, type SignalOptionsIface } from "./context.mjs";
+import { type RespondArgs } from "./sessions.mjs";
+export interface SandboxFileContentArgsIface {
+    snapshotId?: string;
+    bindingId: string;
+    path: string;
+    download?: boolean;
+    /** One HTTP byte range, for example `bytes=1024-2047`. */
+    range?: string;
+}
+export interface SandboxFileContentRequestIface {
+    url: string;
+    /** Supply these to native download/media clients; never put bearer tokens in URLs. */
+    headers: Record<string, string>;
+    credentials: RequestCredentials;
+}
+export interface ConversationEventMetaIface {
+    topic: string;
+    cursor: string | null;
+    createdAt: string | null;
+    /** True for messages the SDK fetched over HTTP to fill a realtime gap. */
+    replayed: boolean;
+}
+/** A realtime event of the conversation topic, flattened (`event.message`, `event.pending`). */
+export type ConversationEvent = AgentRealtimeEvent & ConversationEventMetaIface;
+export interface ConversationEventsOptionsIface extends SignalOptionsIface {
+    /** Keep streaming; false ends once the subscription is current. Defaults to true. */
+    follow?: boolean;
+    /** Also replay messages (thread replies included) after this conversation seq when the subscription opens. */
+    afterSeq?: number;
+    /** Gateway cursor to resume the topic after. */
+    afterCursor?: string;
+    /**
+     * Messages the caller already has (an earlier stream or page). On the first
+     * subscription the stream recovers everything created or updated since the
+     * newest of them, thread replies included, and skips the versions given, so
+     * a client resuming a conversation it rendered before is left with no gap.
+     */
+    resumeFrom?: readonly ConversationMessageIface[];
+    /**
+     * Called on every resubscribe (after the first) and resync, as the stream
+     * starts recovering messages. State that messages cannot reconstruct, such
+     * as whether an agent's turn ended without a reply, is the caller's to re-read.
+     */
+    onResubscribed?: () => void;
+    /**
+     * Also recover what only realtime carries (default true). On every
+     * (re)subscribe, resync and fallback poll the stream re-reads the open
+     * permission and elicitation requests of the conversation's agent sessions
+     * and emits replayed `acp.pending` events: `created` for an open request it
+     * has not emitted, `resolved` for one it emitted open that no longer is. And
+     * for every turn it saw start whose session is no longer running, it emits a
+     * replayed `conversation.turn.ended` (stop reason null). Turns that started
+     * and ended while it was away arrive only as messages.
+     */
+    recoverTransient?: boolean;
+}
+export interface SendMessageOptionsIface extends SignalOptionsIface {
+    clientMessageId?: string;
+    replyTo?: string;
+    threadRootId?: string;
+    /** Ids of earlier messages in the conversation to quote, in order. */
+    quotes?: string[];
+    /** Mentioned participant ids. */
+    mentions?: string[];
+    attachmentIds?: string[];
+    /** When the person submitted, for the prompt-to-inference trace; defaults to now. */
+    clientSubmittedAtMs?: number;
+}
+export type ParticipantCreateInput = {
+    user: string;
+} | {
+    agent: string;
+    routingMode?: EnumInput<NonNullable<Extract<ParticipantInput, {
+        agent: string;
+    }>['routingMode']>>;
+} | {
+    apiKeyPrincipal: string;
+};
+export interface SentMessageIface {
+    message: ConversationMessageIface;
+    messageId: string;
+    seq: number;
+    /** One entry per agent participant the message was routed to. */
+    deliveries: MessageDeliveryIface[];
+}
+export interface ListMessagesOptionsIface extends SignalOptionsIface {
+    before?: number;
+    after?: number;
+    limit?: number;
+    /** Thread root message id, or `MessageThreadFilter.All` for the timeline plus every thread. */
+    thread?: string;
+    /** ISO instant: messages created or updated after it (the first page of a change scan). */
+    updatedAfter?: string;
+    /** A previous page's `nextUpdatedCursor`: continue the change scan after it. */
+    updatedCursor?: string;
+}
+export interface UploadAttachmentArgsIface extends SignalOptionsIface {
+    name: string;
+    contentType: string;
+    data: Blob | ArrayBuffer;
+}
+export interface ConversationHandleIface {
+    /** Durable accepted prompt receipts for a message, including queued deliveries once admitted. */
+    deliveries: (args: {
+        messageId: string;
+    }, options?: SignalOptionsIface) => Promise<MessageDeliveryIface[]>;
+    id: string;
+    info: (options?: SignalOptionsIface) => Promise<ConversationIface>;
+    send: (content: ContentInput, options?: SendMessageOptionsIface) => Promise<SentMessageIface>;
+    events: (options?: ConversationEventsOptionsIface) => AsyncIterableIterator<ConversationEvent>;
+    messages: (options?: ListMessagesOptionsIface) => Promise<ConversationMessagesPageIface>;
+    /** One message by id (`GET /v1/conversations/:id/messages/:messageId`), e.g. a thread root. */
+    message: (args: {
+        messageId: string;
+    }, options?: SignalOptionsIface) => Promise<ConversationMessageIface>;
+    react: (args: {
+        messageId: string;
+        emoji: string;
+    }, options?: SignalOptionsIface) => Promise<ReactionIface[]>;
+    unreact: (args: {
+        messageId: string;
+        emoji: string;
+    }, options?: SignalOptionsIface) => Promise<ReactionIface[]>;
+    recordPushOpen: (args: {
+        deliveryId: string;
+    }, options?: SignalOptionsIface) => Promise<{
+        recorded: boolean;
+    }>;
+    markRead: (args: {
+        throughSeq: number;
+    }, options?: SignalOptionsIface) => Promise<ReadStateIface>;
+    /**
+     * Marks a thread read through one of its replies' seq and follows it
+     * (`POST …/threads/:rootId/read`); the conversation's own unread count
+     * moves with `markRead`.
+     */
+    markThreadRead: (args: {
+        rootId: string;
+        throughSeq: number;
+    }, options?: SignalOptionsIface) => Promise<void>;
+    /**
+     * Tells the other members the caller is typing (`POST …/typing`), realtime
+     * only. A `true` lapses on its own after a few seconds, so composers repeat
+     * it while typing continues and send `false` when the draft is sent or cleared.
+     */
+    typing: (args: {
+        typing: boolean;
+    }, options?: SignalOptionsIface) => Promise<void>;
+    /**
+     * Posts something that happened outside the conversation (`POST …/events`):
+     * a message from the source's system participant (a Goal, a tool, a
+     * webhook), routed like one. The same `eventId` from the same source posts once.
+     */
+    postEvent: (event: PostConversationEventRequestIface, options?: SignalOptionsIface) => Promise<SentMessageIface>;
+    respond: (args: RespondArgs, options?: SignalOptionsIface) => Promise<RespondPendingResponseIface>;
+    /** Stops the agents' running turns in this conversation. */
+    cancel: (options?: SignalOptionsIface & {
+        reason?: string;
+        throughMessageSeq?: number;
+    }) => Promise<void>;
+    participants: (options?: SignalOptionsIface) => Promise<ParticipantIface[]>;
+    /**
+     * Each agent participant's session state, read now: whether a turn is
+     * running in it. What a client re-reads when it may have missed a
+     * `conversation.turn.ended` (`events()` reconciles the turns it saw itself).
+     */
+    turns: (options?: SignalOptionsIface) => Promise<ConversationAgentTurnIface[]>;
+    addParticipant: (participant: ParticipantCreateInput, options?: SignalOptionsIface) => Promise<ParticipantIface>;
+    /**
+     * Changes an agent's routing mode (owners and admins) or a person's role
+     * (owners, groups only; the last owner cannot step down). One field per call.
+     */
+    updateParticipant: (args: {
+        participantId: string;
+    } & Omit<UpdateParticipantRequestIface, 'routingMode' | 'role'> & {
+        routingMode?: EnumInput<NonNullable<UpdateParticipantRequestIface['routingMode']>>;
+        role?: EnumInput<NonNullable<UpdateParticipantRequestIface['role']>>;
+    }, options?: SignalOptionsIface) => Promise<ParticipantIface>;
+    removeParticipant: (args: {
+        participantId: string;
+    }, options?: SignalOptionsIface) => Promise<void>;
+    update: (patch: UpdateConversationRequestIface, options?: SignalOptionsIface) => Promise<ConversationIface>;
+    delete: (args: {
+        messageId: string;
+    }, options?: SignalOptionsIface) => Promise<void>;
+    uploadAttachment: (args: UploadAttachmentArgsIface) => Promise<AttachmentUploadIface>;
+    /**
+     * A fresh presigned download URL for one attachment
+     * (`GET /v1/conversations/:id/attachments/:attachmentId`). URLs on messages
+     * expire; resolve through this before opening one that may be stale.
+     */
+    attachmentUrl: (args: {
+        attachmentId: string;
+    }, options?: SignalOptionsIface) => Promise<AttachmentDownloadIface>;
+    /**
+     * The conversation's sandboxes (the computer tile): status, capabilities and
+     * whether a preview is available (`GET /v1/conversations/:id/sandboxes`).
+     * Never starts a parked sandbox.
+     */
+    sandboxes: (options?: SignalOptionsIface) => Promise<ConversationSandboxIface[]>;
+    /** One directory of a running sandbox, confined to its workspace (`…/sandboxes/:bindingId/files`). */
+    sandboxFiles: (args: {
+        bindingId: string;
+        path?: string;
+        snapshotId?: string;
+    }, options?: SignalOptionsIface) => Promise<SandboxDirectoryIface>;
+    /** Resolves a file or directory without waking its sandbox. */
+    sandboxPath: (args: {
+        bindingId: string;
+        path?: string;
+        snapshotId?: string;
+    }, options?: SignalOptionsIface) => Promise<SandboxPathIface>;
+    /** Bounded recursive path search; truncated signals incomplete traversal. */
+    searchSandboxFiles: (args: {
+        bindingId: string;
+        path?: string;
+        query: string;
+        limit?: number;
+    }, options?: SignalOptionsIface) => Promise<SandboxSearchIface>;
+    /** A byte range of a file in a running sandbox, at most 1 MiB (`…/sandboxes/:bindingId/file`). */
+    sandboxFile: (args: {
+        bindingId: string;
+        path: string;
+        offset?: number;
+        length?: number;
+        snapshotId?: string;
+    }, options?: SignalOptionsIface) => Promise<SandboxFileIface>;
+    inspectSandboxProcesses(args: {
+        bindingId: string;
+        request: ProcessInspectionRequestIface;
+    }, options?: SignalOptionsIface): Promise<ProcessInspectionResultIface>;
+    /** Opens a provider editor for an existing workspace, with write authorization. */
+    openSandboxEditor(args: {
+        bindingId: string;
+    }, options?: SignalOptionsIface): Promise<SandboxEditorSessionIface>;
+    refreshSandboxEditor(args: {
+        bindingId: string;
+        editorId: string;
+        authorizationId: string;
+    }, options?: SignalOptionsIface): Promise<SandboxEditorSessionIface>;
+    closeSandboxEditor(args: {
+        bindingId: string;
+        editorId: string;
+        authorizationId: string;
+    }, options?: SignalOptionsIface & {
+        keepalive?: boolean;
+    }): Promise<void>;
+    /** Raw streaming bytes (`…/file/content`). The caller consumes or cancels the response body. */
+    sandboxFileContent: (args: SandboxFileContentArgsIface, options?: SignalOptionsIface) => Promise<Response>;
+    /**
+     * An authenticated request for a browser/native media or download client.
+     * Cookie clients can use the URL directly; bearer clients must supply headers.
+     * Every request rechecks membership and confinement; never wakes the sandbox.
+     */
+    sandboxFileContentRequest: (args: SandboxFileContentArgsIface) => Promise<SandboxFileContentRequestIface>;
+    /** A short-lived screen preview of a running sandbox; 404 when it serves none (`…/preview`). */
+    sandboxPreview: (args: {
+        bindingId: string;
+        viewOnly?: boolean;
+    }, options?: SignalOptionsIface) => Promise<SandboxPreviewType>;
+    /** Starts a parked sandbox (conversation owners and admins; `POST …/wake`). */
+    wakeSandbox: (args: {
+        bindingId: string;
+    }, options?: SignalOptionsIface) => Promise<ConversationSandboxIface>;
+    /** The conversation's runtime schedules: reminders and recurring checks (`GET …/schedules`). */
+    schedules: (options?: SignalOptionsIface) => Promise<ConversationScheduleIface[]>;
+    /**
+     * Creates a schedule owned by one agent participant (`POST …/schedules`).
+     * Agents create their own; people need to be conversation owners or admins.
+     */
+    createSchedule: (args: CreateConversationScheduleRequestIface, options?: SignalOptionsIface) => Promise<ConversationScheduleIface>;
+    /** Changes a schedule (its agent, or conversation owners and admins; `PATCH …/schedules/:id`). */
+    updateSchedule: (args: {
+        scheduleId: string;
+    } & UpdateConversationScheduleRequestIface, options?: SignalOptionsIface) => Promise<ConversationScheduleIface>;
+    /** Deletes a schedule (`DELETE …/schedules/:id`). */
+    deleteSchedule: (args: {
+        scheduleId: string;
+    }, options?: SignalOptionsIface) => Promise<void>;
+    /**
+     * The conversations this one handed work to, with what their agents are
+     * doing (`GET …/links`). Their replies and waits arrive here as messages.
+     */
+    links: (options?: SignalOptionsIface) => Promise<ConversationLinkIface[]>;
+    /** Conversations receiving this conversation’s delegated results. */
+    parentLinks: (options?: SignalOptionsIface) => Promise<ConversationLinkIface[]>;
+    /**
+     * Links another conversation the caller belongs to (`POST …/links`); linking
+     * it again returns the same link. Links never form a cycle.
+     */
+    link: (args: {
+        conversationId: string;
+    }, options?: SignalOptionsIface) => Promise<ConversationLinkIface>;
+    /** Removes a link (`DELETE …/links/:linkId`); both conversations remain. */
+    unlink: (args: {
+        linkId: string;
+    }, options?: SignalOptionsIface) => Promise<void>;
+}
+export interface ConversationAgentTurnIface {
+    participantId: string;
+    sessionId: string;
+    state: AgentSessionState | WireFallback;
+    /** A turn is running or waiting on a pending request. */
+    running: boolean;
+}
+/** Session states in which a turn is open. */
+export declare const TURN_OPEN_SESSION_STATES: ReadonlySet<AgentSessionState | WireFallback>;
+export interface OpenedConversationIface extends ConversationHandleIface {
+    conversation: ConversationIface;
+}
+export interface CreateConversationArgsIface extends SignalOptionsIface {
+    kind: EnumInput<ConversationKind>;
+    title?: string;
+    participants: ParticipantCreateInput[];
+    turnPolicy?: EnumInput<AgentTurnPolicy>;
+}
+export interface ConversationsApiIface {
+    list: (options?: SignalOptionsIface & {
+        cursor?: string;
+        limit?: number;
+        includeArchived?: boolean;
+    }) => Promise<ConversationListIface>;
+    /** Finds or creates the caller's direct conversation with an agent. */
+    direct: (args: {
+        agent: string;
+    } & SignalOptionsIface) => Promise<OpenedConversationIface>;
+    /** Finds or creates the caller's Home conversation. */
+    home: (options?: SignalOptionsIface) => Promise<OpenedConversationIface>;
+    create: (args: CreateConversationArgsIface) => Promise<OpenedConversationIface>;
+    /** I/O-free handle. */
+    get: (conversationId: string) => ConversationHandleIface;
+    /** Full-text search over the caller's conversations (or one), newest first. */
+    search: (args: {
+        q: string;
+        conversationId?: string;
+        cursor?: string;
+        limit?: number;
+    } & SignalOptionsIface) => Promise<SearchMessagesPageIface>;
+    /**
+     * The caller's conversation list topic (`user.collection:<userId>:conversations`):
+     * `conversation.list.changed` and `conversation.updated` events, and a
+     * `collection.resync` whenever `list()` must be re-read (on every
+     * subscription, resync and while realtime is down).
+     */
+    listEvents: (options?: CollectionEventsOptionsIface) => AsyncIterableIterator<CollectionEvent>;
+    /** Everything awaiting the caller's answer across conversations. */
+    decisions: (options?: SignalOptionsIface & {
+        cursor?: string;
+        limit?: number;
+    }) => Promise<DecisionsPageIface>;
+}
+/**
+ * Every recovery rescans this far behind the newest change seen: `updated_at`
+ * is a transaction's start time, so a slow write (a lock wait) can commit
+ * after newer changes were delivered.
+ */
+export declare const RECOVERY_SKEW_MS = 30000;
+/** The newest copy of a message the stream has emitted (or the caller already had). */
+export interface MessageVersionIface {
+    /** The server's per-message change counter: a total order when both copies carry it. */
+    revision: number | null;
+    /** `updatedAt` in ms; distinct changes can share a millisecond. */
+    updatedAt: number | null;
+    /** Newest of updatedAt/deletedAt/createdAt, for messages without `updatedAt`. */
+    stamp: number;
+    deleted: boolean;
+    final: boolean;
+    fingerprint: string;
+}
+export declare const messageVersionOf: (message: ConversationMessageIface) => MessageVersionIface;
+/**
+ * Whether `incoming` is newer than the copy already emitted; older or equal
+ * copies are dropped. A deletion is never undone. `revision` orders copies
+ * when both carry it. Otherwise `updatedAt` does, where a finalized reply
+ * beats a streaming copy from the same millisecond; without either, a later
+ * change time wins, a finalized reply is never undone by a copy at the same
+ * time, and equal times fall back to content.
+ */
+export declare const isNewerMessageVersion: (incoming: MessageVersionIface, current: MessageVersionIface | undefined) => boolean;
+export declare const createConversationHandle: (context: ClientContextIface, conversationId: string) => ConversationHandleIface;
+export declare const createConversationsApi: (context: ClientContextIface) => ConversationsApiIface;