@finalai/agents 0.8.0

package/dist/modules/agent-client/conversations.mjs

@@ -0,0 +1,1156 @@
+import {
+  ProcessInspectionOperation,
+  processInspectionRequestSchema,
+  processInspectionResultSchema
+} from "@finalai/agent-protocol";
+import {
+  agentRealtimeFrameSchema,
+  AgentRealtimeFrameType,
+  AgentRealtimeKind,
+  agentRealtimeTopics,
+  AgentSessionState,
+  attachmentDownloadSchema,
+  attachmentUploadSchema,
+  cancelConversationRequestSchema,
+  conversationLinkListSchema,
+  conversationLinkSchema,
+  conversationListSchema,
+  conversationMessageSchema,
+  conversationMessagesPageSchema,
+  conversationSandboxListSchema,
+  conversationSandboxSchema,
+  conversationScheduleListSchema,
+  conversationScheduleSchema,
+  conversationSchema,
+  createAttachmentUploadRequestSchema,
+  createConversationLinkRequestSchema,
+  createConversationRequestSchema,
+  createConversationScheduleRequestSchema,
+  createDirectConversationRequestSchema,
+  decisionsPageSchema,
+  markReadRequestSchema,
+  messageDeliveriesSchema,
+  MessageStreamingState,
+  MessageThreadFilter,
+  okResponseSchema,
+  parseAgentRealtimeEvent,
+  participantInputSchema,
+  ParticipantKind,
+  participantListSchema,
+  participantSchema,
+  PendingEventState,
+  pendingRequestListSchema,
+  postConversationEventRequestSchema,
+  pushDeliveryOpenResponseSchema,
+  reactionRequestSchema,
+  reactionsResponseSchema,
+  readStateSchema,
+  removeParticipantRequestSchema,
+  respondPendingRequestSchema,
+  respondPendingResponseSchema,
+  sandboxDirectorySchema,
+  sandboxEditorAuthorizationSchema,
+  sandboxEditorSessionSchema,
+  sandboxFileSchema,
+  sandboxPathSchema,
+  sandboxPreviewOptionsSchema,
+  sandboxPreviewSchema,
+  sandboxSearchSchema,
+  searchMessagesPageSchema,
+  sendMessageRequestSchema,
+  sendMessageResponseSchema,
+  sessionSchema,
+  typingRequestSchema,
+  updateConversationRequestSchema,
+  updateConversationScheduleRequestSchema,
+  updateParticipantRequestSchema
+} from "@finalai/agent-protocol/agent-platform";
+import { createAsyncQueue, failOnAbort } from "./async-queue.mjs";
+import {
+  streamCollectionEvents
+} from "./collection-events.mjs";
+import {
+  ClientCollection,
+  encodePath
+} from "./context.mjs";
+import {
+  clientError,
+  ClientErrorCode,
+  isRetryableClientError,
+  isTerminalRealtimeError,
+  realtimeSubscriptionError
+} from "./errors.mjs";
+import { errorFromResponse, HttpMethod } from "./http.mjs";
+import { outcomeOf } from "./sessions.mjs";
+const TURN_OPEN_SESSION_STATES = /* @__PURE__ */ new Set([
+  AgentSessionState.Running,
+  AgentSessionState.RequiresAction
+]);
+const conversationPath = (conversationId, suffix = "") => `/v1/conversations/${encodePath(conversationId)}${suffix}`;
+const messagePath = (conversationId, messageId, suffix = "") => conversationPath(conversationId, `/messages/${encodePath(messageId)}${suffix}`);
+const MAX_REMEMBERED = 4096;
+const SESSION_PENDING_LIMIT = 200;
+const remember = (map, key, value) => {
+  map.delete(key);
+  map.set(key, value);
+  if (map.size > MAX_REMEMBERED) {
+    const oldest = map.keys().next();
+    if (oldest.done !== true) map.delete(oldest.value);
+  }
+};
+const isTransientEvent = (event) => event.kind === AgentRealtimeKind.AcpPending || event.kind === AgentRealtimeKind.TurnStarted || event.kind === AgentRealtimeKind.TurnEnded;
+const REPLAY_PAGE = 100;
+const RECOVERY_SKEW_MS = 3e4;
+const stampOf = (message) => Math.max(
+  ...[message.updatedAt, message.deletedAt, message.createdAt].map(
+    (value) => value == null ? 0 : Date.parse(value) || 0
+  )
+);
+const isoMs = (value) => {
+  if (value == null) return null;
+  const ms = Date.parse(value);
+  return Number.isNaN(ms) ? null : ms;
+};
+const messageVersionOf = (message) => ({
+  revision: message.revision,
+  updatedAt: isoMs(message.updatedAt),
+  stamp: stampOf(message),
+  deleted: message.deletedAt != null,
+  final: message.streaming?.state === MessageStreamingState.Final,
+  fingerprint: JSON.stringify([
+    message.deletedAt,
+    message.streaming?.state ?? null,
+    message.body,
+    message.reactions
+  ])
+});
+const isNewerMessageVersion = (incoming, current) => {
+  if (current == null) return true;
+  if (current.deleted && !incoming.deleted) return false;
+  if (incoming.revision != null && current.revision != null) {
+    return incoming.revision > current.revision;
+  }
+  if (incoming.updatedAt != null && current.updatedAt != null) {
+    if (incoming.updatedAt !== current.updatedAt) return incoming.updatedAt > current.updatedAt;
+    return incoming.final && !current.final;
+  }
+  if (incoming.stamp !== current.stamp) return incoming.stamp > current.stamp;
+  if (current.final && !incoming.final) return false;
+  return incoming.fingerprint !== current.fingerprint;
+};
+const streamConversationEvents = (args) => {
+  const topic = agentRealtimeTopics.conversation(args.conversationId);
+  const follow = args.options?.follow ?? true;
+  const controller = new AbortController();
+  const signal = AbortSignal.any([
+    controller.signal,
+    args.context.closeSignal,
+    ...args.options?.signal == null ? [] : [args.options.signal]
+  ]);
+  const versions = /* @__PURE__ */ new Map();
+  let newestStamp = null;
+  const subscribedAt = Date.now();
+  let recoveryFloor = null;
+  let subscribedOnce = false;
+  let recovering = 0;
+  let recovery = Promise.resolve();
+  const held = [];
+  const recoverTransientState = args.options?.recoverTransient ?? true;
+  let transientClock = 0;
+  const pendingSeen = /* @__PURE__ */ new Map();
+  const runningTurns = /* @__PURE__ */ new Map();
+  const endedTurns = /* @__PURE__ */ new Map();
+  let degraded = false;
+  let pollTimer = null;
+  const clearPoll = () => {
+    if (pollTimer != null) clearTimeout(pollTimer);
+    pollTimer = null;
+  };
+  let unsubscribe = null;
+  let detachAbort = () => {
+  };
+  let detachClose = () => {
+  };
+  const queue = createAsyncQueue(() => {
+    controller.abort();
+    held.length = 0;
+    clearPoll();
+    unsubscribe?.();
+    detachAbort();
+    detachClose();
+  });
+  const resumeFrom = args.options?.resumeFrom ?? [];
+  const anchor = resumeFrom.length === 0 && args.options?.afterSeq == null ? args.listMessages({ limit: 1, thread: MessageThreadFilter.All, signal }) : null;
+  anchor?.catch(() => {
+  });
+  for (const message of resumeFrom) {
+    versions.set(message.id, messageVersionOf(message));
+    newestStamp = Math.max(newestStamp ?? 0, stampOf(message));
+  }
+  const emitMessage = (message, meta, live) => {
+    const version = messageVersionOf(message);
+    const previous = versions.get(message.id);
+    if (!isNewerMessageVersion(version, previous)) return;
+    versions.set(message.id, version);
+    newestStamp = Math.max(newestStamp ?? 0, stampOf(message));
+    if (live != null) {
+      queue.push({ ...live, ...meta });
+      return;
+    }
+    queue.push(
+      previous == null ? { kind: AgentRealtimeKind.MessageCreated, message, ...meta } : { kind: AgentRealtimeKind.MessageUpdated, message, ...meta }
+    );
+  };
+  const notePending = (pending, state) => {
+    const seen = pendingSeen.get(pending.id);
+    if (state === PendingEventState.Resolved) {
+      if (seen?.state === PendingEventState.Resolved) return false;
+      transientClock += 1;
+      remember(pendingSeen, pending.id, { state, pending, noted: transientClock });
+      return true;
+    }
+    if (state === PendingEventState.Created) {
+      if (seen != null) return false;
+      transientClock += 1;
+      remember(pendingSeen, pending.id, { state, pending, noted: transientClock });
+      return true;
+    }
+    return true;
+  };
+  const noteTransient = (event) => {
+    if (event.kind === AgentRealtimeKind.AcpPending) return notePending(event.pending, event.state);
+    if (event.kind === AgentRealtimeKind.TurnStarted) {
+      if (!endedTurns.has(event.turnId)) {
+        transientClock += 1;
+        remember(runningTurns, event.turnId, { turn: event, noted: transientClock });
+      }
+      return true;
+    }
+    if (event.kind === AgentRealtimeKind.TurnEnded) {
+      if (endedTurns.has(event.turnId)) return false;
+      remember(endedTurns, event.turnId, true);
+      runningTurns.delete(event.turnId);
+    }
+    return true;
+  };
+  const emitLive = (event, meta) => {
+    if (event.kind === AgentRealtimeKind.MessageCreated || event.kind === AgentRealtimeKind.MessageUpdated) {
+      emitMessage(event.message, meta, event);
+      return;
+    }
+    if (event.kind === AgentRealtimeKind.MessageDeleted) {
+      const current = versions.get(event.messageId);
+      if (current?.deleted === true) return;
+      const deletedAt = isoMs(event.deletedAt) ?? current?.stamp ?? 0;
+      versions.set(event.messageId, {
+        revision: current?.revision ?? null,
+        updatedAt: Math.max(current?.updatedAt ?? 0, deletedAt),
+        stamp: Math.max(current?.stamp ?? 0, deletedAt),
+        deleted: true,
+        final: current?.final ?? false,
+        fingerprint: current?.fingerprint ?? ""
+      });
+    }
+    if (!noteTransient(event)) return;
+    queue.push({ ...event, ...meta });
+  };
+  const replayed = (message) => ({
+    topic,
+    cursor: null,
+    createdAt: message.updatedAt ?? message.createdAt,
+    replayed: true
+  });
+  const emitPage = (messages) => {
+    for (const message of [...messages].sort((left, right) => left.seq - right.seq)) {
+      emitMessage(message, replayed(message), null);
+    }
+  };
+  const recoverChanges = async () => {
+    const since = Math.max(
+      0,
+      Math.min(newestStamp ?? subscribedAt, recoveryFloor ?? Infinity) - RECOVERY_SKEW_MS
+    );
+    let position = {
+      updatedAfter: new Date(since).toISOString()
+    };
+    let nextFloor = null;
+    for (; ; ) {
+      const page = await args.listMessages({
+        ...position,
+        thread: MessageThreadFilter.All,
+        limit: REPLAY_PAGE,
+        signal
+      });
+      if (nextFloor == null && page.recoverySince != null) {
+        const stamp = Date.parse(page.recoverySince);
+        if (Number.isFinite(stamp)) nextFloor = stamp;
+      }
+      emitPage(page.messages);
+      const next = page.nextUpdatedCursor;
+      if (next == null || !page.hasMoreAfter || page.messages.length === 0) {
+        recoveryFloor = nextFloor ?? recoveryFloor;
+        return;
+      }
+      position = { updatedCursor: next };
+    }
+  };
+  const recoverFromAnchor = async (anchor2) => {
+    const page = await anchor2;
+    if (page.recoverySince != null) {
+      const stamp = Date.parse(page.recoverySince);
+      if (Number.isFinite(stamp)) recoveryFloor = stamp;
+    }
+    const newest = page.messages.reduce(
+      (best, message) => best == null || message.seq > best.seq ? message : best,
+      null
+    );
+    if (newest != null && !versions.has(newest.id)) {
+      versions.set(newest.id, messageVersionOf(newest));
+      newestStamp = Math.max(newestStamp ?? 0, stampOf(newest));
+    }
+    await recoverChanges();
+  };
+  const recoverAfterSeq = async (afterSeq) => {
+    let cursor = afterSeq;
+    for (; ; ) {
+      const page = await args.listMessages({
+        after: cursor,
+        thread: MessageThreadFilter.All,
+        limit: REPLAY_PAGE,
+        signal
+      });
+      emitPage(page.messages);
+      const next = Math.max(cursor, ...page.messages.map((message) => message.seq));
+      if (!page.hasMoreAfter || next === cursor) return;
+      cursor = next;
+    }
+  };
+  const recoveredMeta = () => ({
+    topic,
+    cursor: null,
+    createdAt: null,
+    replayed: true
+  });
+  const optional = async (read) => {
+    try {
+      return await read();
+    } catch (cause) {
+      if (isRetryableClientError(cause)) throw cause;
+      return null;
+    }
+  };
+  const emitRecovered = (event) => {
+    held.push({ event, meta: recoveredMeta(), noted: true });
+  };
+  const recoverTransient = async () => {
+    if (!recoverTransientState) return;
+    const asOf = transientClock;
+    const participants = await optional(() => args.listParticipants({ signal }));
+    const current = participants == null ? null : new Set(
+      participants.flatMap(
+        (participant) => participant.kind === ParticipantKind.Agent && participant.sessionId != null && participant.leftAt == null ? [participant.sessionId] : []
+      )
+    );
+    const remembered = /* @__PURE__ */ new Set([
+      ...[...pendingSeen.values()].flatMap(
+        (seen) => seen.state === PendingEventState.Created ? [seen.pending.sessionId] : []
+      ),
+      ...[...runningTurns.values()].map((entry) => entry.turn.sessionId)
+    ]);
+    const checked = await Promise.all(
+      [.../* @__PURE__ */ new Set([...current ?? [], ...remembered])].map(async (sessionId) => {
+        const [session, open] = await Promise.all([
+          optional(() => args.getSession(sessionId, { signal })),
+          optional(() => args.sessionPending(sessionId, { signal }))
+        ]);
+        const departed = current != null && !current.has(sessionId);
+        return {
+          sessionId,
+          running: session == null ? departed ? false : null : TURN_OPEN_SESSION_STATES.has(session.state),
+          open: open ?? (departed ? [] : null)
+        };
+      })
+    );
+    for (const { sessionId, running, open } of checked) {
+      if (open != null) {
+        const complete = open.length < SESSION_PENDING_LIMIT;
+        const openIds = new Set(open.map((pending) => pending.id));
+        for (const pending of open) {
+          if (notePending(pending, PendingEventState.Created))
+            emitRecovered({
+              kind: AgentRealtimeKind.AcpPending,
+              pending,
+              state: PendingEventState.Created
+            });
+        }
+        for (const seen of [...pendingSeen.values()]) {
+          if (!complete || seen.state !== PendingEventState.Created || seen.noted > asOf || seen.pending.sessionId !== sessionId || openIds.has(seen.pending.id))
+            continue;
+          notePending(seen.pending, PendingEventState.Resolved);
+          emitRecovered({
+            kind: AgentRealtimeKind.AcpPending,
+            pending: seen.pending,
+            state: PendingEventState.Resolved
+          });
+        }
+      }
+      if (running !== false) continue;
+      for (const { turn, noted } of [...runningTurns.values()]) {
+        if (turn.sessionId !== sessionId || noted > asOf) continue;
+        runningTurns.delete(turn.turnId);
+        remember(endedTurns, turn.turnId, true);
+        emitRecovered({
+          kind: AgentRealtimeKind.TurnEnded,
+          conversationId: turn.conversationId,
+          participantId: turn.participantId,
+          sessionId: turn.sessionId,
+          turnId: turn.turnId,
+          stopReason: null
+        });
+      }
+    }
+  };
+  const scheduleRecovery = (run) => {
+    recovering += 1;
+    recovery = recovery.then(async () => {
+      let delay = 250;
+      while (!queue.closed()) {
+        try {
+          await run();
+          return;
+        } catch (cause) {
+          if (!follow || !isRetryableClientError(cause)) throw cause;
+          await new Promise((resolve) => {
+            const done = () => {
+              clearTimeout(timer);
+              signal.removeEventListener("abort", done);
+              resolve();
+            };
+            const timer = setTimeout(done, delay);
+            if (signal.aborted) done();
+            else signal.addEventListener("abort", done, { once: true });
+          });
+          delay = Math.min(delay * 2, 3e4);
+        }
+      }
+    }).then(() => {
+      recovering -= 1;
+      if (recovering > 0) return;
+      for (const entry of held.splice(0)) {
+        if (entry.noted) queue.push({ ...entry.event, ...entry.meta });
+        else emitLive(entry.event, entry.meta);
+      }
+    }).catch((cause) => queue.fail(cause));
+  };
+  let newestRecoveryPending = false;
+  let newestRecoveryRequested = false;
+  const recoverFromNewest = () => {
+    newestRecoveryRequested = true;
+    if (newestRecoveryPending) return;
+    newestRecoveryPending = true;
+    scheduleRecovery(async () => {
+      do {
+        newestRecoveryRequested = false;
+        await recoverChanges();
+        await recoverTransient();
+      } while (newestRecoveryRequested && !queue.closed());
+      newestRecoveryPending = false;
+    });
+  };
+  let initialRecoveryStarted = false;
+  const startInitialRecovery = () => {
+    if (initialRecoveryStarted) return;
+    initialRecoveryStarted = true;
+    const afterSeq = args.options?.afterSeq;
+    if (afterSeq != null) scheduleRecovery(() => recoverAfterSeq(afterSeq));
+    if (resumeFrom.length > 0) recoverFromNewest();
+    if (anchor != null)
+      scheduleRecovery(async () => {
+        try {
+          await recoverFromAnchor(anchor);
+        } catch (cause) {
+          if (!isRetryableClientError(cause)) throw cause;
+          await recoverChanges();
+        }
+      });
+    if (resumeFrom.length === 0) scheduleRecovery(recoverTransient);
+  };
+  const poll = () => {
+    pollTimer = null;
+    if (!degraded || queue.closed()) return;
+    if (initialRecoveryStarted) recoverFromNewest();
+    else startInitialRecovery();
+    void recovery.then(() => {
+      if (!degraded || queue.closed() || pollTimer != null) return;
+      pollTimer = setTimeout(poll, args.context.timing.conversationPollIntervalMs);
+    });
+  };
+  const onFrame = (raw) => {
+    const frame = agentRealtimeFrameSchema.safeParse(raw);
+    if (!frame.success || queue.closed()) return;
+    switch (frame.data.type) {
+      case AgentRealtimeFrameType.Event: {
+        const envelope = frame.data;
+        const entry = {
+          event: parseAgentRealtimeEvent(envelope),
+          meta: {
+            topic: envelope.topic,
+            cursor: envelope.cursor,
+            createdAt: envelope.createdAt,
+            replayed: false
+          }
+        };
+        if (recovering > 0) {
+          if (held.length >= 1024) {
+            queue.fail(
+              clientError({
+                code: ClientErrorCode.Network,
+                status: 0,
+                message: "Conversation recovery buffer is full; reconnect from the last message."
+              })
+            );
+            return;
+          }
+          if (isTransientEvent(entry.event)) {
+            if (noteTransient(entry.event)) held.push({ ...entry, noted: true });
+          } else held.push({ ...entry, noted: false });
+        } else emitLive(entry.event, entry.meta);
+        return;
+      }
+      case AgentRealtimeFrameType.Subscribed: {
+        degraded = false;
+        clearPoll();
+        if (!subscribedOnce) {
+          subscribedOnce = true;
+          if (initialRecoveryStarted) recoverFromNewest();
+          else startInitialRecovery();
+        } else {
+          recoverFromNewest();
+          args.options?.onResubscribed?.();
+        }
+        if (!follow) void recovery.then(() => queue.end());
+        return;
+      }
+      case AgentRealtimeFrameType.ResyncRequired:
+        recoverFromNewest();
+        args.options?.onResubscribed?.();
+        return;
+      case AgentRealtimeFrameType.Error:
+        if (isTerminalRealtimeError(frame.data)) {
+          queue.fail(
+            realtimeSubscriptionError({
+              topic: frame.data.topic ?? topic,
+              code: frame.data.code ?? "unknown",
+              message: frame.data.message ?? "Realtime subscription was refused"
+            })
+          );
+          return;
+        }
+        if (!follow) {
+          if (subscribedOnce) return;
+          subscribedOnce = true;
+          startInitialRecovery();
+          void recovery.then(() => queue.end());
+          return;
+        }
+        if (!degraded) {
+          degraded = true;
+          poll();
+        }
+        return;
+      default:
+        return;
+    }
+  };
+  detachAbort = failOnAbort(queue, signal);
+  detachClose = failOnAbort(queue, args.context.closeSignal);
+  if (!queue.closed()) {
+    const subscribeOptions = args.options?.afterCursor == null ? void 0 : { afterCursor: args.options.afterCursor };
+    const stop = args.context.realtime().subscribe(topic, onFrame, subscribeOptions);
+    if (queue.closed()) stop();
+    else unsubscribe = stop;
+  }
+  return queue.iterator;
+};
+const createConversationHandle = (context, conversationId) => {
+  const { http } = context;
+  const sandboxFileContentRequest = async (args) => {
+    if (args.path.length === 0 || args.path.length > 4096 || args.path.includes("\0")) {
+      throw clientError({
+        message: "Invalid sandbox file path",
+        status: 0,
+        code: ClientErrorCode.InvalidRequest
+      });
+    }
+    const target = http.url(
+      conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/file/content`)
+    );
+    target.searchParams.set("path", args.path);
+    if (args.snapshotId != null) target.searchParams.set("snapshotId", args.snapshotId);
+    if (args.download != null) target.searchParams.set("download", String(args.download));
+    const headers = await http.headers();
+    if (args.range != null) headers.range = args.range;
+    return {
+      url: target.toString(),
+      headers,
+      credentials: http.usesCookies ? "include" : "omit"
+    };
+  };
+  const listMessages = (options = {}) => http.request({
+    method: HttpMethod.Get,
+    path: conversationPath(conversationId, "/messages"),
+    query: {
+      before: options.before,
+      after: options.after,
+      limit: options.limit,
+      thread: options.thread,
+      updatedAfter: options.updatedAfter,
+      updatedCursor: options.updatedCursor
+    },
+    response: conversationMessagesPageSchema,
+    signal: options.signal
+  });
+  const listParticipants = async (options) => (await http.request({
+    method: HttpMethod.Get,
+    path: conversationPath(conversationId, "/participants"),
+    response: participantListSchema,
+    signal: options.signal
+  })).participants;
+  const getSession = (sessionId, options) => http.request({
+    method: HttpMethod.Get,
+    path: `/v1/sessions/${encodePath(sessionId)}`,
+    response: sessionSchema,
+    signal: options.signal
+  });
+  const sessionPending = async (sessionId, options) => (await http.request({
+    method: HttpMethod.Get,
+    path: `/v1/sessions/${encodePath(sessionId)}/pending`,
+    response: pendingRequestListSchema,
+    signal: options.signal
+  })).pending;
+  const reaction = async (args) => (await http.request({
+    method: args.method,
+    path: messagePath(conversationId, args.messageId, "/reactions"),
+    body: { schema: reactionRequestSchema, value: { emoji: args.emoji } },
+    response: reactionsResponseSchema,
+    signal: args.signal
+  })).reactions;
+  return {
+    id: conversationId,
+    info: (options) => http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(conversationId),
+      response: conversationSchema,
+      signal: options?.signal
+    }),
+    send: async (content, options) => {
+      const sent = await http.request({
+        method: HttpMethod.Post,
+        path: conversationPath(conversationId, "/messages"),
+        body: {
+          schema: sendMessageRequestSchema,
+          value: {
+            content,
+            clientMessageId: options?.clientMessageId ?? context.newKey(),
+            replyTo: options?.replyTo,
+            threadRootId: options?.threadRootId,
+            quotes: options?.quotes,
+            mentions: options?.mentions,
+            attachmentIds: options?.attachmentIds,
+            clientSubmittedAtMs: options?.clientSubmittedAtMs ?? context.now()
+          }
+        },
+        response: sendMessageResponseSchema,
+        signal: options?.signal
+      });
+      return {
+        message: sent.message,
+        messageId: sent.message.id,
+        seq: sent.message.seq,
+        deliveries: sent.deliveries
+      };
+    },
+    events: (options) => streamConversationEvents({
+      context,
+      conversationId,
+      options,
+      listMessages,
+      listParticipants,
+      getSession,
+      sessionPending
+    }),
+    messages: (options) => listMessages(options),
+    deliveries: async (args, options) => (await http.request({
+      method: HttpMethod.Get,
+      path: `${messagePath(conversationId, args.messageId)}/deliveries`,
+      response: messageDeliveriesSchema,
+      signal: options?.signal
+    })).deliveries,
+    message: (args, options) => http.request({
+      method: HttpMethod.Get,
+      path: messagePath(conversationId, args.messageId),
+      response: conversationMessageSchema,
+      signal: options?.signal
+    }),
+    react: (args, options) => reaction({ method: HttpMethod.Post, ...args, signal: options?.signal }),
+    unreact: (args, options) => reaction({ method: HttpMethod.Delete, ...args, signal: options?.signal }),
+    markThreadRead: async ({ rootId, throughSeq }, options) => {
+      await http.request({
+        method: HttpMethod.Post,
+        path: conversationPath(conversationId, `/threads/${encodePath(rootId)}/read`),
+        body: { schema: markReadRequestSchema, value: { throughSeq } },
+        response: okResponseSchema,
+        signal: options?.signal
+      });
+    },
+    postEvent: async (event, options) => {
+      const sent = await http.request({
+        method: HttpMethod.Post,
+        path: conversationPath(conversationId, "/events"),
+        body: { schema: postConversationEventRequestSchema, value: event },
+        response: sendMessageResponseSchema,
+        signal: options?.signal
+      });
+      return {
+        message: sent.message,
+        messageId: sent.message.id,
+        seq: sent.message.seq,
+        deliveries: sent.deliveries
+      };
+    },
+    typing: async (args, options) => {
+      await http.request({
+        method: HttpMethod.Post,
+        path: conversationPath(conversationId, "/typing"),
+        body: { schema: typingRequestSchema, value: args },
+        response: okResponseSchema,
+        signal: options?.signal
+      });
+    },
+    recordPushOpen: (args, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(
+        conversationId,
+        `/push-deliveries/${encodeURIComponent(args.deliveryId)}/open`
+      ),
+      response: pushDeliveryOpenResponseSchema,
+      signal: options?.signal
+    }),
+    markRead: (args, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(conversationId, "/read"),
+      body: { schema: markReadRequestSchema, value: args },
+      response: readStateSchema,
+      signal: options?.signal
+    }),
+    respond: (args, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(conversationId, "/respond"),
+      body: {
+        schema: respondPendingRequestSchema,
+        value: { pendingId: args.pendingId, outcome: outcomeOf(args) }
+      },
+      response: respondPendingResponseSchema,
+      signal: options?.signal,
+      context: { pendingId: args.pendingId }
+    }),
+    cancel: async (options) => {
+      await http.request({
+        method: HttpMethod.Post,
+        path: conversationPath(conversationId, "/cancel"),
+        body: {
+          schema: cancelConversationRequestSchema,
+          value: { reason: options?.reason, throughMessageSeq: options?.throughMessageSeq }
+        },
+        response: okResponseSchema,
+        signal: options?.signal
+      });
+    },
+    participants: (options) => listParticipants({ signal: options?.signal }),
+    turns: async (options) => {
+      const participants = await listParticipants({ signal: options?.signal });
+      return Promise.all(
+        participants.flatMap((participant) => {
+          const sessionId = participant.sessionId;
+          if (participant.kind !== ParticipantKind.Agent || sessionId == null) return [];
+          return [
+            getSession(sessionId, { signal: options?.signal }).then(
+              (session) => ({
+                participantId: participant.id,
+                sessionId,
+                state: session.state,
+                running: TURN_OPEN_SESSION_STATES.has(session.state)
+              })
+            )
+          ];
+        })
+      );
+    },
+    addParticipant: (participant, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(conversationId, "/participants"),
+      body: { schema: participantInputSchema, value: participant },
+      response: participantSchema,
+      signal: options?.signal
+    }),
+    updateParticipant: ({ participantId, ...patch }, options) => http.request({
+      method: HttpMethod.Patch,
+      path: conversationPath(conversationId, `/participants/${encodePath(participantId)}`),
+      body: { schema: updateParticipantRequestSchema, value: patch },
+      response: participantSchema,
+      signal: options?.signal
+    }),
+    removeParticipant: async (args, options) => {
+      await http.request({
+        method: HttpMethod.Delete,
+        path: conversationPath(conversationId, "/participants"),
+        body: { schema: removeParticipantRequestSchema, value: args },
+        response: okResponseSchema,
+        signal: options?.signal
+      });
+    },
+    update: (patch, options) => http.request({
+      method: HttpMethod.Patch,
+      path: conversationPath(conversationId),
+      body: { schema: updateConversationRequestSchema, value: patch },
+      response: conversationSchema,
+      signal: options?.signal
+    }),
+    delete: async (args, options) => {
+      await http.request({
+        method: HttpMethod.Delete,
+        path: messagePath(conversationId, args.messageId),
+        response: okResponseSchema,
+        signal: options?.signal
+      });
+    },
+    links: async (options) => (await http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(conversationId, "/links"),
+      response: conversationLinkListSchema,
+      signal: options?.signal
+    })).links,
+    parentLinks: async (options) => (await http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(conversationId, "/parent-links"),
+      response: conversationLinkListSchema,
+      signal: options?.signal
+    })).links,
+    link: (args, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(conversationId, "/links"),
+      body: { schema: createConversationLinkRequestSchema, value: args },
+      response: conversationLinkSchema,
+      signal: options?.signal
+    }),
+    unlink: async (args, options) => {
+      await http.request({
+        method: HttpMethod.Delete,
+        path: conversationPath(conversationId, `/links/${encodePath(args.linkId)}`),
+        response: okResponseSchema,
+        signal: options?.signal
+      });
+    },
+    attachmentUrl: (args, options) => http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(conversationId, `/attachments/${encodePath(args.attachmentId)}`),
+      response: attachmentDownloadSchema,
+      signal: options?.signal
+    }),
+    sandboxes: async (options) => (await http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(conversationId, "/sandboxes"),
+      response: conversationSandboxListSchema,
+      signal: options?.signal
+    })).sandboxes,
+    sandboxFiles: (args, options) => http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/files`),
+      query: { path: args.path, snapshotId: args.snapshotId },
+      response: sandboxDirectorySchema,
+      signal: options?.signal
+    }),
+    sandboxPath: (args, options) => http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/path`),
+      query: { path: args.path, snapshotId: args.snapshotId },
+      response: sandboxPathSchema,
+      signal: options?.signal
+    }),
+    searchSandboxFiles: (args, options) => http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(
+        conversationId,
+        `/sandboxes/${encodePath(args.bindingId)}/files/search`
+      ),
+      query: { path: args.path, query: args.query, limit: args.limit },
+      response: sandboxSearchSchema,
+      signal: options?.signal
+    }),
+    sandboxFile: (args, options) => http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/file`),
+      query: {
+        path: args.path,
+        offset: args.offset,
+        length: args.length,
+        snapshotId: args.snapshotId
+      },
+      response: sandboxFileSchema,
+      signal: options?.signal
+    }),
+    sandboxFileContentRequest,
+    openSandboxEditor: (args, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/editor`),
+      response: sandboxEditorSessionSchema,
+      signal: options?.signal
+    }),
+    refreshSandboxEditor: (args, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(
+        conversationId,
+        `/sandboxes/${encodePath(args.bindingId)}/editor/${encodePath(args.editorId)}/refresh`
+      ),
+      body: {
+        schema: sandboxEditorAuthorizationSchema,
+        value: { authorizationId: args.authorizationId }
+      },
+      response: sandboxEditorSessionSchema,
+      signal: options?.signal
+    }),
+    closeSandboxEditor: async (args, options) => {
+      await http.request({
+        method: HttpMethod.Delete,
+        path: conversationPath(
+          conversationId,
+          `/sandboxes/${encodePath(args.bindingId)}/editor/${encodePath(args.editorId)}`
+        ),
+        body: {
+          schema: sandboxEditorAuthorizationSchema,
+          value: { authorizationId: args.authorizationId }
+        },
+        response: okResponseSchema,
+        signal: options?.signal,
+        keepalive: options?.keepalive
+      });
+    },
+    sandboxFileContent: async (args, options) => {
+      const request = await sandboxFileContentRequest(args);
+      let response;
+      try {
+        response = await http.fetch(request.url, {
+          method: HttpMethod.Get,
+          headers: request.headers,
+          credentials: request.credentials,
+          signal: options?.signal
+        });
+      } catch (cause) {
+        if (options?.signal?.aborted === true) throw cause;
+        throw clientError({
+          message: "Sandbox file request failed",
+          status: 0,
+          code: ClientErrorCode.Network,
+          cause
+        });
+      }
+      if (!response.ok) {
+        let text;
+        try {
+          text = await response.text();
+        } catch (cause) {
+          if (options?.signal?.aborted === true) throw cause;
+          throw clientError({
+            message: "Sandbox file response failed",
+            status: 0,
+            code: ClientErrorCode.Network,
+            cause
+          });
+        }
+        throw errorFromResponse({ status: response.status, text, context: void 0 });
+      }
+      return response;
+    },
+    inspectSandboxProcesses: (args, options) => {
+      const request = processInspectionRequestSchema.parse(args.request);
+      const { operation } = request;
+      const suffix = operation === ProcessInspectionOperation.Available ? "/available" : "processId" in request ? "/" + encodePath(request.processId) : "";
+      const query = {};
+      if ("bootId" in request) query.bootId = request.bootId;
+      if ("cursor" in request) query.cursor = request.cursor;
+      if ("limit" in request) query.limit = request.limit;
+      return http.request({
+        method: operation === ProcessInspectionOperation.Stop ? HttpMethod.Delete : HttpMethod.Get,
+        path: conversationPath(
+          conversationId,
+          `/sandboxes/${encodePath(args.bindingId)}/processes${suffix}`
+        ),
+        query,
+        response: processInspectionResultSchema,
+        signal: options?.signal
+      });
+    },
+    sandboxPreview: (args, options) => {
+      const request = {
+        method: args.viewOnly === false ? HttpMethod.Post : HttpMethod.Get,
+        path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/preview`),
+        response: sandboxPreviewSchema,
+        signal: options?.signal
+      };
+      if (args.viewOnly === false)
+        request.body = { schema: sandboxPreviewOptionsSchema, value: { viewOnly: false } };
+      return http.request(request);
+    },
+    wakeSandbox: (args, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/wake`),
+      response: conversationSandboxSchema,
+      signal: options?.signal
+    }),
+    schedules: async (options) => (await http.request({
+      method: HttpMethod.Get,
+      path: conversationPath(conversationId, "/schedules"),
+      response: conversationScheduleListSchema,
+      signal: options?.signal
+    })).schedules,
+    createSchedule: (args, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(conversationId, "/schedules"),
+      body: { schema: createConversationScheduleRequestSchema, value: args },
+      response: conversationScheduleSchema,
+      signal: options?.signal
+    }),
+    updateSchedule: ({ scheduleId, ...patch }, options) => http.request({
+      method: HttpMethod.Patch,
+      path: conversationPath(conversationId, `/schedules/${encodePath(scheduleId)}`),
+      body: { schema: updateConversationScheduleRequestSchema, value: patch },
+      response: conversationScheduleSchema,
+      signal: options?.signal
+    }),
+    deleteSchedule: async (args, options) => {
+      await http.request({
+        method: HttpMethod.Delete,
+        path: conversationPath(conversationId, `/schedules/${encodePath(args.scheduleId)}`),
+        response: okResponseSchema,
+        signal: options?.signal
+      });
+    },
+    uploadAttachment: async (args) => {
+      const sizeBytes = "byteLength" in args.data ? args.data.byteLength : args.data.size;
+      const upload = await http.request({
+        method: HttpMethod.Post,
+        path: conversationPath(conversationId, "/attachments"),
+        body: {
+          schema: createAttachmentUploadRequestSchema,
+          value: { name: args.name, contentType: args.contentType, sizeBytes }
+        },
+        response: attachmentUploadSchema,
+        signal: args.signal
+      });
+      const response = await context.storageFetch(upload.uploadUrl, {
+        method: upload.method,
+        headers: { "content-type": args.contentType, ...upload.headers },
+        body: args.data,
+        signal: args.signal,
+        credentials: "omit"
+      });
+      if (!response.ok) {
+        throw clientError({
+          message: `Attachment upload failed with status ${response.status}`,
+          status: response.status,
+          code: ClientErrorCode.UploadFailed,
+          body: await response.text()
+        });
+      }
+      return upload;
+    }
+  };
+};
+const createConversationsApi = (context) => {
+  const opened = (conversation) => ({
+    ...createConversationHandle(context, conversation.id),
+    conversation
+  });
+  return {
+    list: (options) => context.http.request({
+      method: HttpMethod.Get,
+      path: "/v1/conversations",
+      query: {
+        cursor: options?.cursor,
+        limit: options?.limit,
+        includeArchived: options?.includeArchived
+      },
+      response: conversationListSchema,
+      signal: options?.signal
+    }),
+    direct: async (args) => opened(
+      await context.http.request({
+        method: HttpMethod.Post,
+        path: "/v1/conversations/direct",
+        body: { schema: createDirectConversationRequestSchema, value: { agent: args.agent } },
+        response: conversationSchema,
+        signal: args.signal
+      })
+    ),
+    home: async (options) => opened(
+      await context.http.request({
+        method: HttpMethod.Get,
+        path: "/v1/conversations/home",
+        response: conversationSchema,
+        signal: options?.signal
+      })
+    ),
+    create: async (args) => opened(
+      await context.http.request({
+        method: HttpMethod.Post,
+        path: "/v1/conversations",
+        body: {
+          schema: createConversationRequestSchema,
+          value: {
+            kind: args.kind,
+            title: args.title,
+            participants: args.participants,
+            turnPolicy: args.turnPolicy
+          }
+        },
+        response: conversationSchema,
+        signal: args.signal
+      })
+    ),
+    get: (conversationId) => createConversationHandle(context, conversationId),
+    search: (args) => context.http.request({
+      method: HttpMethod.Get,
+      path: "/v1/conversations/search",
+      query: {
+        q: args.q,
+        conversationId: args.conversationId,
+        cursor: args.cursor,
+        limit: args.limit
+      },
+      response: searchMessagesPageSchema,
+      signal: args.signal
+    }),
+    listEvents: (options) => streamCollectionEvents({
+      context,
+      topicFor: agentRealtimeTopics.userConversations,
+      collection: ClientCollection.Conversations,
+      options
+    }),
+    decisions: (options) => context.http.request({
+      method: HttpMethod.Get,
+      path: "/v1/decisions",
+      query: { cursor: options?.cursor, limit: options?.limit },
+      response: decisionsPageSchema,
+      signal: options?.signal
+    })
+  };
+};
+export {
+  RECOVERY_SKEW_MS,
+  TURN_OPEN_SESSION_STATES,
+  createConversationHandle,
+  createConversationsApi,
+  isNewerMessageVersion,
+  messageVersionOf
+};
+//# sourceMappingURL=conversations.mjs.map