@finalai/agents 0.11.0 → 0.13.0

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

@@ -1,4 +1,5 @@
 import {
+  PROCESS_CAPABILITIES,
   ProcessInspectionOperation,
   processInspectionRequestSchema,
   processInspectionResultSchema
@@ -21,14 +22,19 @@ import {
   conversationSandboxSchema,
   conversationScheduleListSchema,
   conversationScheduleSchema,
+  conversationLabelFilter,
+  conversationLookupSchema,
+  conversationResponseSchema,
   conversationSchema,
   createAttachmentUploadRequestSchema,
   createConversationLinkRequestSchema,
   createConversationRequestSchema,
   createConversationScheduleRequestSchema,
   createDirectConversationRequestSchema,
+  scheduleRunResultSchema,
   DecisionEventState,
   decisionRecordListSchema,
+  homeConversationRequestSchema,
   decisionsPageSchema,
   markReadRequestSchema,
   messageDeliveriesSchema,
@@ -39,8 +45,10 @@ import {
   participantInputSchema,
   ParticipantKind,
   participantListSchema,
+  participantProvideResponseSchema,
   participantSchema,
   postConversationEventRequestSchema,
+  provideParticipantRequestSchema,
   postConversationEventResponseSchema,
   pushDeliveryOpenResponseSchema,
   reactionRequestSchema,
@@ -64,9 +72,13 @@ import {
   typingRequestSchema,
   updateConversationRequestSchema,
   updateConversationScheduleRequestSchema,
-  updateParticipantRequestSchema
+  updateParticipantRequestSchema,
+  SandboxProviderKind
 } from "@finalai/agent-protocol/agent-platform";
 import { createAsyncQueue, failOnAbort } from "./async-queue.mjs";
+import {
+  createConversationResources
+} from "./conversation-resources.mjs";
 import {
   streamCollectionEvents
 } from "./collection-events.mjs";
@@ -77,12 +89,24 @@ import {
 import {
   clientError,
   ClientErrorCode,
+  isClientError,
   isRetryableClientError,
   isTerminalRealtimeError,
   realtimeSubscriptionError
 } from "./errors.mjs";
 import { errorFromResponse, HttpMethod } from "./http.mjs";
+import { LocalHostOwnerKind } from "./local-host-protocol.mjs";
+import {
+  provideDocumentOf,
+  provideDocumentOfView,
+  providePatchOf
+} from "./provide.mjs";
+import { createSandboxesApi } from "./sandboxes.mjs";
 import { outcomeOf } from "./sessions.mjs";
+import {
+  startAgent,
+  withWorkersEnvironment
+} from "./start.mjs";
 const TURN_OPEN_SESSION_STATES = /* @__PURE__ */ new Set([
   AgentSessionState.Running,
   AgentSessionState.RequiresAction
@@ -574,8 +598,9 @@ const streamConversationEvents = (args) => {
   }
   return queue.iterator;
 };
-const createConversationHandle = (context, conversationId) => {
+const createConversationHandle = (context, conversationId, starter) => {
   const { http } = context;
+  const participantPath = (participantId, suffix = "") => conversationPath(conversationId, `/participants/${encodePath(participantId)}${suffix}`);
   const sandboxFileContentRequest = async (args) => {
     if (args.path.length === 0 || args.path.length > 4096 || args.path.includes("\0")) {
       throw clientError({
@@ -585,7 +610,7 @@ const createConversationHandle = (context, conversationId) => {
       });
     }
     const target = http.url(
-      conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/file/content`)
+      conversationPath(conversationId, `/sandboxes/${encodePath(args.sandboxId)}/file/content`)
     );
     target.searchParams.set("path", args.path);
     if (args.snapshotId != null) target.searchParams.set("snapshotId", args.snapshotId);
@@ -637,14 +662,20 @@ const createConversationHandle = (context, conversationId) => {
     response: reactionsResponseSchema,
     signal: args.signal
   })).reactions;
+  const info = (signal) => http.request({
+    method: HttpMethod.Get,
+    path: conversationPath(conversationId),
+    response: conversationSchema,
+    signal
+  });
+  const sharedProvide = async (signal) => {
+    const { provide } = await info(signal);
+    return provide == null ? null : provideDocumentOfView(provide);
+  };
   return {
+    ...createConversationResources(context, conversationId),
     id: conversationId,
-    info: (options) => http.request({
-      method: HttpMethod.Get,
-      path: conversationPath(conversationId),
-      response: conversationSchema,
-      signal: options?.signal
-    }),
+    info: (options) => info(options?.signal),
     send: async (content, options) => {
       const sent = await http.request({
         method: HttpMethod.Post,
@@ -659,7 +690,8 @@ const createConversationHandle = (context, conversationId) => {
             quotes: options?.quotes,
             mentions: options?.mentions,
             attachmentIds: options?.attachmentIds,
-            clientSubmittedAtMs: options?.clientSubmittedAtMs ?? context.now()
+            clientSubmittedAtMs: options?.clientSubmittedAtMs ?? context.now(),
+            actor: options?.actor
           }
         },
         response: sendMessageResponseSchema,
@@ -760,7 +792,36 @@ const createConversationHandle = (context, conversationId) => {
         signal: options?.signal
       });
     },
-    participants: (options) => listParticipants({ signal: options?.signal }),
+    participants: Object.assign(
+      (options) => listParticipants({ signal: options?.signal }),
+      {
+        settings: (participantId, options) => http.request({
+          method: HttpMethod.Get,
+          path: participantPath(participantId, "/provide"),
+          response: participantProvideResponseSchema,
+          signal: options?.signal
+        }),
+        provide: async (participantId, patch, options) => {
+          const harness = patch.harness == null || starter.projectId == null ? patch.harness : (await withWorkersEnvironment({
+            context,
+            projectId: starter.projectId,
+            harness: patch.harness,
+            owner: { kind: LocalHostOwnerKind.Conversation, id: conversationId },
+            signal: options?.signal
+          })).harness;
+          return http.request({
+            method: HttpMethod.Put,
+            path: participantPath(participantId, "/provide"),
+            body: {
+              schema: provideParticipantRequestSchema,
+              value: providePatchOf(harness == null ? patch : { ...patch, harness })
+            },
+            response: participantProvideResponseSchema,
+            signal: options?.signal
+          });
+        }
+      }
+    ),
     turns: async (options) => {
       const participants = await listParticipants({ signal: options?.signal });
       return Promise.all(
@@ -780,13 +841,50 @@ const createConversationHandle = (context, conversationId) => {
         })
       );
     },
-    addParticipant: (participant, options) => http.request({
-      method: HttpMethod.Post,
-      path: conversationPath(conversationId, "/participants"),
-      body: { schema: participantInputSchema, value: participant },
-      response: participantSchema,
-      signal: options?.signal
-    }),
+    addParticipant: async (participant, options) => {
+      if ("user" in participant || "actor" in participant)
+        return http.request({
+          method: HttpMethod.Post,
+          path: conversationPath(conversationId, "/participants"),
+          body: {
+            schema: participantInputSchema,
+            value: "user" in participant ? { user: participant.user } : { actor: participant.actor }
+          },
+          response: participantSchema,
+          signal: options?.signal
+        });
+      const own = participant.provide;
+      const shared = own.harness != null && own.compute != null && own.integrations != null ? null : await sharedProvide(options?.signal);
+      const started = await startAgent(starter.deps, {
+        projectId: starter.projectId,
+        agent: participant.agent,
+        provide: own,
+        shared,
+        owner: { kind: LocalHostOwnerKind.Conversation, id: conversationId },
+        signal: options?.signal
+      });
+      try {
+        const added = await http.request({
+          method: HttpMethod.Post,
+          path: conversationPath(conversationId, "/participants"),
+          body: {
+            schema: participantInputSchema,
+            value: {
+              agent: started.ref,
+              routingMode: participant.routingMode,
+              provide: started.provide
+            }
+          },
+          response: participantSchema,
+          signal: options?.signal
+        });
+        started.established();
+        return added;
+      } catch (cause) {
+        started.abandon();
+        throw cause;
+      }
+    },
     updateParticipant: ({ participantId, ...patch }, options) => http.request({
       method: HttpMethod.Patch,
       path: conversationPath(conversationId, `/participants/${encodePath(participantId)}`),
@@ -859,14 +957,14 @@ const createConversationHandle = (context, conversationId) => {
     })).sandboxes,
     sandboxFiles: (args, options) => http.request({
       method: HttpMethod.Get,
-      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/files`),
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.sandboxId)}/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`),
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.sandboxId)}/path`),
       query: { path: args.path, snapshotId: args.snapshotId },
       response: sandboxPathSchema,
       signal: options?.signal
@@ -875,7 +973,7 @@ const createConversationHandle = (context, conversationId) => {
       method: HttpMethod.Get,
       path: conversationPath(
         conversationId,
-        `/sandboxes/${encodePath(args.bindingId)}/files/search`
+        `/sandboxes/${encodePath(args.sandboxId)}/files/search`
       ),
       query: { path: args.path, query: args.query, limit: args.limit },
       response: sandboxSearchSchema,
@@ -883,7 +981,7 @@ const createConversationHandle = (context, conversationId) => {
     }),
     sandboxFile: (args, options) => http.request({
       method: HttpMethod.Get,
-      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/file`),
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.sandboxId)}/file`),
       query: {
         path: args.path,
         offset: args.offset,
@@ -896,7 +994,7 @@ const createConversationHandle = (context, conversationId) => {
     sandboxFileContentRequest,
     openSandboxEditor: (args, options) => http.request({
       method: HttpMethod.Post,
-      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/editor`),
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.sandboxId)}/editor`),
       response: sandboxEditorSessionSchema,
       signal: options?.signal
     }),
@@ -904,7 +1002,7 @@ const createConversationHandle = (context, conversationId) => {
       method: HttpMethod.Post,
       path: conversationPath(
         conversationId,
-        `/sandboxes/${encodePath(args.bindingId)}/editor/${encodePath(args.editorId)}/refresh`
+        `/sandboxes/${encodePath(args.sandboxId)}/editor/${encodePath(args.editorId)}/refresh`
       ),
       body: {
         schema: sandboxEditorAuthorizationSchema,
@@ -918,7 +1016,7 @@ const createConversationHandle = (context, conversationId) => {
         method: HttpMethod.Delete,
         path: conversationPath(
           conversationId,
-          `/sandboxes/${encodePath(args.bindingId)}/editor/${encodePath(args.editorId)}`
+          `/sandboxes/${encodePath(args.sandboxId)}/editor/${encodePath(args.editorId)}`
         ),
         body: {
           schema: sandboxEditorAuthorizationSchema,
@@ -977,7 +1075,7 @@ const createConversationHandle = (context, conversationId) => {
         method: operation === ProcessInspectionOperation.Stop ? HttpMethod.Delete : HttpMethod.Get,
         path: conversationPath(
           conversationId,
-          `/sandboxes/${encodePath(args.bindingId)}/processes${suffix}`
+          `/sandboxes/${encodePath(args.sandboxId)}/processes${suffix}`
         ),
         query,
         response: processInspectionResultSchema,
@@ -987,7 +1085,7 @@ const createConversationHandle = (context, conversationId) => {
     sandboxPreview: (args, options) => {
       const request = {
         method: args.viewOnly === false ? HttpMethod.Post : HttpMethod.Get,
-        path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/preview`),
+        path: conversationPath(conversationId, `/sandboxes/${encodePath(args.sandboxId)}/preview`),
         response: sandboxPreviewSchema,
         signal: options?.signal
       };
@@ -997,7 +1095,7 @@ const createConversationHandle = (context, conversationId) => {
     },
     wakeSandbox: (args, options) => http.request({
       method: HttpMethod.Post,
-      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.bindingId)}/wake`),
+      path: conversationPath(conversationId, `/sandboxes/${encodePath(args.sandboxId)}/wake`),
       response: conversationSandboxSchema,
       signal: options?.signal
     }),
@@ -1029,6 +1127,12 @@ const createConversationHandle = (context, conversationId) => {
         signal: options?.signal
       });
     },
+    runSchedule: (args, options) => http.request({
+      method: HttpMethod.Post,
+      path: conversationPath(conversationId, `/schedules/${encodePath(args.scheduleId)}/run-now`),
+      response: scheduleRunResultSchema,
+      signal: options?.signal
+    }),
     uploadAttachment: async (args) => {
       const sizeBytes = "byteLength" in args.data ? args.data.byteLength : args.data.size;
       const upload = await http.request({
@@ -1060,11 +1164,7 @@ const createConversationHandle = (context, conversationId) => {
     }
   };
 };
-const createConversationsApi = (context) => {
-  const opened = (conversation) => ({
-    ...createConversationHandle(context, conversation.id),
-    conversation
-  });
+const createConversationsApi = (context, starter) => {
   return {
     list: (options) => context.http.request({
       method: HttpMethod.Get,
@@ -1073,48 +1173,16 @@ const createConversationsApi = (context) => {
         cursor: options?.cursor,
         limit: options?.limit,
         includeArchived: options?.includeArchived,
-        projectId: options?.projectId
+        projectId: options?.projectId ?? starter.projectId ?? void 0,
+        includeSubprojects: options?.includeSubprojects,
+        label: options?.labels == null ? void 0 : Object.entries(options.labels).map(
+          ([key, value]) => conversationLabelFilter(key, value)
+        )
       },
       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",
-        query: { projectId: options?.projectId },
-        response: conversationSchema,
-        signal: options?.signal
-      })
-    ),
-    create: async (args) => opened(
-      await context.http.request({
-        method: HttpMethod.Post,
-        path: "/v1/conversations",
-        body: {
-          schema: createConversationRequestSchema,
-          value: {
-            projectId: args.projectId,
-            kind: args.kind,
-            title: args.title,
-            participants: args.participants,
-            turnPolicy: args.turnPolicy
-          }
-        },
-        response: conversationSchema,
-        signal: args.signal
-      })
-    ),
-    get: (conversationId) => createConversationHandle(context, conversationId),
+    get: (conversationId) => createConversationHandle(context, conversationId, starter),
     search: (args) => context.http.request({
       method: HttpMethod.Get,
       path: "/v1/conversations/search",
@@ -1142,11 +1210,258 @@ const createConversationsApi = (context) => {
     })
   };
 };
+const createProjectConversationsApi = (args) => {
+  const { context, projectId } = args;
+  const starter = { deps: args.start, projectId };
+  const base = createConversationsApi(context, starter);
+  const opened = (conversation) => ({
+    ...createConversationHandle(context, conversation.id, starter),
+    conversation
+  });
+  const sandboxes = createSandboxesApi({ context, projectId });
+  const chosenProcessCompute = async (compute, signal) => {
+    const stored = {};
+    const ids = /* @__PURE__ */ new Set();
+    for (const capability of PROCESS_CAPABILITIES) {
+      const id = compute[capability];
+      if (id == null) continue;
+      stored[capability] = id;
+      ids.add(id);
+    }
+    for (const id of ids) {
+      const sandbox = await sandboxes.get(id, { signal }).catch((cause) => {
+        if (isClientError(cause) && cause.status === 404) return null;
+        throw cause;
+      });
+      if (sandbox != null && sandbox.resource.providerKind !== SandboxProviderKind.ClientHost)
+        return stored;
+    }
+    return null;
+  };
+  const withProcessCompute = (provide, filesAndShell) => ({
+    ...provide,
+    compute: {
+      ...Object.fromEntries(
+        Object.entries(provide.compute ?? {}).filter(
+          ([key]) => !PROCESS_CAPABILITIES.some((capability) => capability === key)
+        )
+      ),
+      ...filesAndShell
+    }
+  });
+  const withStarted = async (started, send) => {
+    try {
+      const sent = await send();
+      for (const agent of started) agent.established();
+      return sent;
+    } catch (cause) {
+      for (const agent of started) agent.abandon();
+      throw cause;
+    }
+  };
+  return {
+    ...base,
+    create: async (create) => {
+      const started = [];
+      const participants = [];
+      let conversationId = create.id;
+      let shared = create.provide == null ? null : provideDocumentOf(create.provide);
+      let sharedWorkers = null;
+      const undoShared = () => {
+        void sharedWorkers?.discard().catch(() => void 0);
+      };
+      try {
+        if (shared?.harness != null) {
+          const placed = await withWorkersEnvironment({
+            context,
+            projectId,
+            harness: shared.harness,
+            owner: { kind: LocalHostOwnerKind.Conversation, id: conversationId },
+            signal: create.signal
+          });
+          shared = { ...shared, harness: placed.harness };
+          conversationId = placed.ownerId;
+          sharedWorkers = placed.created;
+        }
+        for (const participant of create.participants) {
+          if ("user" in participant) {
+            participants.push({ user: participant.user });
+            continue;
+          }
+          if ("actor" in participant) {
+            participants.push({ actor: participant.actor });
+            continue;
+          }
+          const agent = await startAgent(args.start, {
+            projectId,
+            agent: participant.agent,
+            provide: participant.provide,
+            shared,
+            owner: { kind: LocalHostOwnerKind.Conversation, id: conversationId },
+            // An id an earlier participant's host or Workers sandbox reserved is not the caller's.
+            ownerIdReserved: create.id == null,
+            signal: create.signal
+          });
+          started.push(agent);
+          conversationId = agent.ownerId ?? conversationId;
+          participants.push({
+            agent: agent.ref,
+            routingMode: participant.routingMode,
+            provide: agent.provide
+          });
+        }
+      } catch (cause) {
+        for (const agent of started) agent.abandon();
+        undoShared();
+        throw cause;
+      }
+      const sent = withStarted(
+        started,
+        () => context.http.request({
+          method: HttpMethod.Post,
+          path: "/v1/conversations",
+          body: {
+            schema: createConversationRequestSchema,
+            value: {
+              id: conversationId,
+              projectId,
+              kind: create.kind,
+              title: create.title,
+              participants,
+              turnPolicy: create.turnPolicy,
+              provide: shared ?? void 0,
+              primary: create.primary,
+              labels: create.labels,
+              actor: create.actor
+            }
+          },
+          response: conversationResponseSchema,
+          signal: create.signal
+        })
+      );
+      const { conversation } = await sent.catch((cause) => {
+        undoShared();
+        throw cause;
+      });
+      if (conversationId != null && conversation.id !== conversationId) {
+        for (const agent of started) agent.abandon();
+        undoShared();
+      }
+      return opened(conversation);
+    },
+    home: async ({ id, provide, signal }) => {
+      const document = provideDocumentOf(provide);
+      const placed = document.harness == null ? null : await withWorkersEnvironment({
+        context,
+        projectId,
+        harness: document.harness,
+        owner: { kind: LocalHostOwnerKind.Conversation, id },
+        signal
+      });
+      const homeId = placed?.ownerId ?? id;
+      const discard = () => void placed?.created?.discard().catch(() => void 0);
+      try {
+        const { conversation } = await context.http.request({
+          method: HttpMethod.Post,
+          path: "/v1/conversations/home",
+          body: {
+            schema: homeConversationRequestSchema,
+            value: {
+              projectId,
+              id: homeId,
+              provide: placed == null ? document : { ...document, harness: placed.harness }
+            }
+          },
+          response: conversationResponseSchema,
+          signal
+        });
+        if (conversation.id !== homeId) discard();
+        return opened(conversation);
+      } catch (cause) {
+        discard();
+        throw cause;
+      }
+    },
+    findHome: async (options) => (await context.http.request({
+      method: HttpMethod.Get,
+      path: "/v1/conversations/home",
+      query: { projectId },
+      response: conversationLookupSchema,
+      signal: options?.signal
+    })).conversation,
+    direct: async ({ id, agent, provide, actor, signal }) => {
+      const started = await startAgent(args.start, {
+        projectId,
+        agent,
+        provide,
+        owner: { kind: LocalHostOwnerKind.Conversation, id },
+        signal
+      });
+      const { conversation } = await withStarted(
+        [started],
+        () => context.http.request({
+          method: HttpMethod.Post,
+          path: "/v1/conversations/direct",
+          body: {
+            schema: createDirectConversationRequestSchema,
+            value: {
+              id: started.ownerId ?? id,
+              projectId,
+              agent: started.ref,
+              provide: started.provide,
+              actor
+            }
+          },
+          response: conversationResponseSchema,
+          signal
+        })
+      );
+      const chat = opened(conversation);
+      if (conversation.id === started.ownerId) return chat;
+      started.abandon();
+      if (started.host == null) return chat;
+      const participant = (await chat.participants({ signal })).find(
+        (member) => member.kind === ParticipantKind.Agent && member.leftAt == null
+      );
+      if (participant == null) throw new Error("the direct chat has no agent participant");
+      const { settings } = await chat.participants.settings(participant.id, { signal });
+      const chosen = await chosenProcessCompute(settings.compute, signal);
+      const attached = await startAgent(args.start, {
+        projectId,
+        agent,
+        provide: chosen == null ? provide : withProcessCompute(provide, chosen),
+        owner: { kind: LocalHostOwnerKind.Conversation, id: conversation.id },
+        signal
+      });
+      await withStarted([attached], async () => {
+        const sandboxId = attached.host?.sandboxId;
+        const local = Object.entries(attached.provide.compute ?? {}).filter(
+          ([, value]) => sandboxId != null && value === sandboxId
+        );
+        if (local.length === 0) return;
+        await chat.participants.provide(
+          participant.id,
+          { compute: Object.fromEntries(local) },
+          { signal }
+        );
+      });
+      return chat;
+    },
+    findDirect: async ({ agent, actorExternalId, signal }) => (await context.http.request({
+      method: HttpMethod.Get,
+      path: "/v1/conversations/direct",
+      query: { projectId, agent, actorExternalId },
+      response: conversationLookupSchema,
+      signal
+    })).conversation
+  };
+};
 export {
   RECOVERY_SKEW_MS,
   TURN_OPEN_SESSION_STATES,
   createConversationHandle,
   createConversationsApi,
+  createProjectConversationsApi,
   isNewerMessageVersion,
   messageVersionOf
 };