@base44/superagent-native 0.0.1

package/src/superagentApiClient.ts

@@ -0,0 +1,895 @@
+import type {
+  SuperagentAgent,
+  SuperagentAutomation,
+  SuperagentAutomationCreditsSummary,
+  SuperagentChannelStatus,
+  SuperagentCollaborator,
+  SuperagentConnector,
+  SuperagentConnectorAccessMode,
+  SuperagentConnectorActionInput,
+  SuperagentIMessageActivation,
+  SuperagentIMessageChannelStatus,
+  SuperagentInviteCollaboratorsResult,
+  SuperagentLineActivation,
+  SuperagentModelChoice,
+  SuperagentSandboxFileContent,
+  SuperagentSecret,
+  SuperagentTelegramChannelStatus,
+  SuperagentToolPermissionConfig,
+} from './types';
+import { SUPERAGENT_CONNECTOR_CATALOG } from './connectorCatalog';
+import { DEFAULT_SANDBOX_FILE_PATHS, normalizeFilePaths } from './fileTreeUtils';
+
+const AGENT_FIELDS = [
+  'id',
+  'name',
+  'user_description',
+  'status',
+  'updated_date',
+  'logo_url',
+  'created_date',
+  'app_type',
+  'avatar_index',
+  'model',
+  'organization_id',
+  'tools_permission_config',
+].join(',');
+
+const USER_AGENT_AGENT_NAME = 'your_agent';
+const USER_AGENT_SANDBOX_LIST_PATHS = [
+  '.agents',
+  '.agents/rules',
+  '.agents/skills',
+  '.agents/mcps',
+  '.agents/hooks',
+  '.agents/cron',
+  '.agents/memory',
+  'incoming_files',
+];
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+
+type HttpRequestOptions = {
+  authRequired?: boolean;
+  body?: unknown;
+  headers?: Record<string, string>;
+  method: HttpMethod;
+};
+
+export type SuperagentApiClientConfig = {
+  baseUrl: string;
+  currentUserId?: string | null;
+  getAccessToken: () => Promise<string | null | undefined> | string | null | undefined;
+  getHeaders?: () => Promise<Record<string, string> | undefined> | Record<string, string> | undefined;
+};
+
+type UserAgentApp = {
+  id: string;
+  name?: string;
+  user_description?: string;
+  logo_url?: string;
+  model?: SuperagentModelChoice | string | null;
+  organization_id?: string | null;
+  avatar_index?: number | null;
+  tools_permission_config?: SuperagentToolPermissionConfig | null;
+  updated_date?: string;
+  created_date?: string;
+  app_type?: string;
+};
+
+type AppIntegration = {
+  integration_type: string;
+  integration_account_identifier?: string | null;
+  scopes?: string[];
+  status?: string;
+};
+
+type HttpResult<T> = {
+  success: boolean;
+  data?: T;
+  error?: {
+    message: string;
+    status?: number;
+  };
+};
+
+type SuperagentHttpClient = ReturnType<typeof createHttpClient>;
+
+export type SuperagentVoiceLiveSession = {
+  sessionId: string;
+  streamToken: string;
+  websocketUrl: string;
+};
+
+type VoiceLiveSessionResponse = {
+  session_id?: string;
+  stream_token?: string;
+};
+
+type RuntimeAuthTokenResponse = {
+  token?: string;
+};
+
+type TelegramStatusResponse = {
+  connected: boolean;
+  bot_link?: string | null;
+  bot_name?: string | null;
+  bot_username?: string | null;
+};
+
+type LineActivationResponse = {
+  add_friend_url?: string;
+  code?: string;
+};
+
+type IMessageStatusResponse = {
+  connected: boolean;
+  phone_number?: string | null;
+};
+
+type IMessageActivationResponse = {
+  code?: string;
+  phone_number?: string;
+};
+
+type SandboxFileListResponse = {
+  files?: string[];
+};
+
+export type SuperagentConnectorsResult = {
+  availableConnectors: SuperagentConnector[];
+  connectedConnectors: SuperagentConnector[];
+};
+
+export type InitiateConnectorConnectionResult = {
+  already_authorized?: boolean;
+  connection_id?: string | null;
+  error?: string | null;
+  error_message?: string | null;
+  other_user_email?: string | null;
+  redirect_url?: string | null;
+};
+
+export type ConnectorConnectionStatus = 'ACTIVE' | 'FAILED' | 'PENDING';
+
+const OAUTH_INJECTED_SCOPES = new Set(['email', 'openid', 'profile', 'User.Read', 'offline_access']);
+
+export function createSuperagentApiClient(config: SuperagentApiClientConfig) {
+  const appsEndpoint = `${normalizeBaseUrl(config.baseUrl)}/api/apps`;
+  const httpClient = createHttpClient(config);
+
+  return {
+  async listAgents(): Promise<SuperagentAgent[]> {
+    const query = {
+      app_type: 'user_agent',
+      ...(config.currentUserId ? {owner_id: config.currentUserId} : {}),
+    };
+    const endpoint = buildUrl(appsEndpoint, {
+      fields: AGENT_FIELDS,
+      filter_mode: 'owned_by_me',
+      limit: '9',
+      q: JSON.stringify(query),
+      skip: '0',
+      sort: '-updated_date',
+    });
+
+    const response = await httpClient.get<UserAgentApp[]>(endpoint, true);
+    assertSuccess(response, 'Failed to load Superagents');
+    return (response.data ?? []).map(toAgent);
+  },
+
+  async createAgent(): Promise<SuperagentAgent> {
+    const response = await httpClient.post<UserAgentApp>(appsEndpoint, {app_type: 'user_agent'}, true);
+    assertSuccess(response, 'Failed to create Superagent');
+    if (!response.data?.id) {
+      throw new Error('Superagent creation returned no app id');
+    }
+    return toAgent(response.data);
+  },
+
+  async renameAgent(agentId: string, name: string): Promise<SuperagentAgent> {
+    return updateAgent(httpClient, appsEndpoint, agentId, {name});
+  },
+
+  async updateAgentModel(agentId: string, model: SuperagentModelChoice | string): Promise<SuperagentAgent> {
+    return updateAgent(httpClient, appsEndpoint, agentId, {model});
+  },
+
+  async updateToolPermissions(agentId: string, config: SuperagentToolPermissionConfig): Promise<SuperagentAgent> {
+    return updateAgent(httpClient, appsEndpoint, agentId, {tools_permission_config: config});
+  },
+
+  async deleteAgent(agentId: string): Promise<void> {
+    const response = await httpClient.delete(`${appsEndpoint}/${encodeURIComponent(agentId)}`, true);
+    assertSuccess(response, 'Failed to delete Superagent');
+  },
+
+  async listCollaborators(agentId: string): Promise<SuperagentCollaborator[]> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/users/collaborators`;
+    const response = await httpClient.get<SuperagentCollaborator[]>(endpoint, true);
+    assertSuccess(response, 'Failed to load shared chat members');
+    return response.data ?? [];
+  },
+
+  async inviteCollaborators(
+    agentId: string,
+    emails: string[],
+    addAsGuest = false,
+  ): Promise<SuperagentInviteCollaboratorsResult> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/users/invite-users`;
+    const response = await httpClient.post<SuperagentInviteCollaboratorsResult>(
+      endpoint,
+      {
+        add_as_guest: addAsGuest,
+        collaborator_role: 'editor',
+        role: 'admin',
+        user_emails: emails,
+      },
+      true,
+    );
+    assertSuccess(response, 'Failed to invite collaborators');
+    return response.data ?? {results: []};
+  },
+
+  async listSecrets(agentId: string): Promise<SuperagentSecret[]> {
+    const response = await httpClient.get<Record<string, string>>(`${appsEndpoint}/${encodeURIComponent(agentId)}/secrets`, true);
+    assertSuccess(response, 'Failed to load Superagent secrets');
+    return Object.entries(response.data ?? {}).map(([name, value]) => ({name, value: String(value)}));
+  },
+
+  async saveSecret(agentId: string, name: string, value: string): Promise<void> {
+    const response = await httpClient.post(
+      `${appsEndpoint}/${encodeURIComponent(agentId)}/secrets`,
+      {[name.trim().toUpperCase()]: value.trim()},
+      true,
+    );
+    assertSuccess(response, 'Failed to save Superagent secret');
+  },
+
+  async deleteSecret(agentId: string, name: string): Promise<void> {
+    const endpoint = buildUrl(`${appsEndpoint}/${encodeURIComponent(agentId)}/secrets`, {
+      secret_name: name,
+    });
+    const response = await httpClient.delete(endpoint, true);
+    assertSuccess(response, 'Failed to delete Superagent secret');
+  },
+
+  async listConnectors(agentId: string): Promise<SuperagentConnectorsResult> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/external-auth/list`;
+    const response = await httpClient.get<{integrations?: AppIntegration[]}>(endpoint, true);
+    assertSuccess(response, 'Failed to load Superagent connectors');
+
+    const connectedConnectors = (response.data?.integrations ?? [])
+      .filter((integration) => !isPaymentIntegration(integration.integration_type))
+      .map(toConnector);
+    const connectedIds = new Set(connectedConnectors.map((connector) => connector.id));
+    const availableConnectors = SUPERAGENT_CONNECTOR_CATALOG.filter((connector) => !connectedIds.has(connector.id));
+
+    return {
+      availableConnectors,
+      connectedConnectors,
+    };
+  },
+
+  async listAutomations(agentId: string): Promise<SuperagentAutomation[]> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/automations`;
+    const response = await httpClient.get<SuperagentAutomation[]>(endpoint, true);
+    assertSuccess(response, 'Failed to load Superagent automations');
+    return (response.data ?? []).sort((a, b) => getAutomationTime(b) - getAutomationTime(a));
+  },
+
+  async listAutomationCredits(agentId: string): Promise<Record<string, SuperagentAutomationCreditsSummary>> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/automations/credits-summary`;
+    const response = await httpClient.get<Record<string, SuperagentAutomationCreditsSummary>>(endpoint, true);
+    assertSuccess(response, 'Failed to load Superagent automation credits');
+    return response.data ?? {};
+  },
+
+  async listSandboxFiles(agentId: string): Promise<string[]> {
+    const rootFiles = await listSandboxFilesAt(httpClient, appsEndpoint, agentId, '.');
+    const agentFiles = await listUserAgentSandboxFilePaths(httpClient, appsEndpoint, agentId);
+
+    if (normalizeFilePaths(rootFiles).length === 0) {
+      return agentFiles;
+    }
+
+    return mergeSandboxFilePaths(rootFiles, agentFiles);
+  },
+
+  async readSandboxFile(agentId: string, path: string): Promise<SuperagentSandboxFileContent> {
+    const endpoint = buildUrl(`${appsEndpoint}/${encodeURIComponent(agentId)}/sandbox/files/content`, {
+      path,
+    });
+    const response = await httpClient.get<SuperagentSandboxFileContent>(endpoint, true);
+    assertSuccess(response, 'Failed to open Superagent file');
+    if (typeof response.data?.content !== 'string') {
+      throw new Error('The backend returned no file content.');
+    }
+    return {
+      content: response.data.content,
+      path: response.data.path || path,
+    };
+  },
+
+  async writeSandboxFile(agentId: string, path: string, content: string): Promise<void> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/sandbox/files/content`;
+    const response = await httpClient.request(endpoint, {
+      authRequired: true,
+      body: {content, path},
+      method: 'PUT',
+    });
+    assertSuccess(response, 'Failed to save Superagent file');
+  },
+
+  async initiateConnectorConnection(
+    agentId: string,
+    connectorId: string,
+    options: Pick<SuperagentConnectorActionInput, 'accessMode' | 'forceReconnect' | 'scopes'> = {},
+  ): Promise<InitiateConnectorConnectionResult> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/external-auth/initiate`;
+    const scopes = options.scopes ?? getConnectorScopes(connectorId, options.accessMode);
+    const response = await httpClient.post<InitiateConnectorConnectionResult>(
+      endpoint,
+      {
+        force_reconnect: options.forceReconnect ?? false,
+        integration_type: connectorId,
+        scopes,
+      },
+      true,
+    );
+    assertSuccess(response, 'Failed to start connector authorization');
+    return response.data ?? {};
+  },
+
+  async getConnectorConnectionStatus(
+    agentId: string,
+    connectorId: string,
+    connectionId: string,
+  ): Promise<ConnectorConnectionStatus> {
+    const endpoint = buildUrl(`${appsEndpoint}/${encodeURIComponent(agentId)}/external-auth/status`, {
+      connection_id: connectionId,
+      integration_type: connectorId,
+    });
+    const response = await httpClient.get<{status?: ConnectorConnectionStatus}>(endpoint, true);
+    assertSuccess(response, 'Failed to check connector authorization status');
+    return response.data?.status ?? 'PENDING';
+  },
+
+  async getRuntimeAuthToken(agentId: string): Promise<string> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/auth/token`;
+    const response = await httpClient.get<RuntimeAuthTokenResponse>(endpoint, true);
+    assertSuccess(response, 'Failed to start Superagent realtime');
+    if (!response.data?.token) {
+      throw new Error('Superagent realtime returned no auth token');
+    }
+    return response.data.token;
+  },
+
+  getWhatsAppConnectUrl(agentId: string, runtimeAuthToken: string): string {
+    return buildUrl(`${appsEndpoint}/${encodeURIComponent(agentId)}/agents/${USER_AGENT_AGENT_NAME}/whatsapp`, {
+      token: runtimeAuthToken,
+    });
+  },
+
+  async getChannelStatus(agentId: string, runtimeAuthToken: string): Promise<SuperagentChannelStatus> {
+    const [telegram, imessage] = await Promise.all([
+      this.getTelegramStatus(agentId, runtimeAuthToken).catch(() => ({connected: false})),
+      this.getIMessageStatus(agentId, runtimeAuthToken).catch(() => ({connected: false})),
+    ]);
+
+    return {
+      imessage,
+      line: {connected: false},
+      telegram,
+      whatsapp: {
+        connected: false,
+        connectUrl: this.getWhatsAppConnectUrl(agentId, runtimeAuthToken),
+      },
+    };
+  },
+
+  async getTelegramStatus(agentId: string, runtimeAuthToken: string): Promise<SuperagentTelegramChannelStatus> {
+    const response = await runtimeRequest<TelegramStatusResponse>(httpClient, appsEndpoint, agentId, runtimeAuthToken, '/telegram/status', {
+      method: 'GET',
+    });
+    assertSuccess(response, 'Failed to load Telegram status');
+    return normalizeTelegramStatus(response.data);
+  },
+
+  async getIMessageStatus(agentId: string, runtimeAuthToken: string): Promise<SuperagentIMessageChannelStatus> {
+    const response = await runtimeRequest<IMessageStatusResponse>(httpClient, appsEndpoint, agentId, runtimeAuthToken, '/imessage/status', {
+      method: 'GET',
+    });
+    assertSuccess(response, 'Failed to load iMessage status');
+    return normalizeIMessageStatus(response.data);
+  },
+
+  async generateIMessageCode(agentId: string, runtimeAuthToken: string): Promise<SuperagentIMessageActivation> {
+    const response = await runtimeRequest<IMessageActivationResponse>(httpClient, appsEndpoint, agentId, runtimeAuthToken, '/imessage/generate-code', {
+      method: 'POST',
+    });
+    assertSuccess(response, 'Failed to generate iMessage code');
+    if (!response.data?.code || !response.data.phone_number) {
+      throw new Error('iMessage setup returned no activation code.');
+    }
+
+    return {
+      code: response.data.code,
+      phoneNumber: response.data.phone_number,
+    };
+  },
+
+  async disconnectIMessage(agentId: string, runtimeAuthToken: string): Promise<SuperagentIMessageChannelStatus> {
+    const response = await runtimeRequest<IMessageStatusResponse>(httpClient, appsEndpoint, agentId, runtimeAuthToken, '/imessage/disconnect', {
+      method: 'DELETE',
+    });
+    assertSuccess(response, 'Failed to disconnect iMessage');
+    return normalizeIMessageStatus(response.data);
+  },
+
+  async setupTelegram(agentId: string, runtimeAuthToken: string, token: string): Promise<SuperagentTelegramChannelStatus> {
+    const response = await runtimeRequest<TelegramStatusResponse>(httpClient, appsEndpoint, agentId, runtimeAuthToken, '/telegram/setup', {
+      body: {bot_token: token},
+      method: 'POST',
+    });
+    assertSuccess(response, 'Failed to connect Telegram');
+    return normalizeTelegramStatus(response.data);
+  },
+
+  async disconnectTelegram(agentId: string, runtimeAuthToken: string): Promise<void> {
+    const response = await runtimeRequest(httpClient, appsEndpoint, agentId, runtimeAuthToken, '/telegram/disconnect', {
+      method: 'DELETE',
+    });
+    assertSuccess(response, 'Failed to disconnect Telegram');
+  },
+
+  async generateLineCode(agentId: string, runtimeAuthToken: string): Promise<SuperagentLineActivation> {
+    const response = await runtimeRequest<LineActivationResponse>(httpClient, appsEndpoint, agentId, runtimeAuthToken, '/line/generate-code', {
+      method: 'POST',
+    });
+    assertSuccess(response, 'Failed to generate LINE code');
+    if (!response.data?.code || !response.data.add_friend_url) {
+      throw new Error('LINE setup returned no activation code.');
+    }
+
+    return {
+      addFriendUrl: response.data.add_friend_url,
+      code: response.data.code,
+    };
+  },
+
+  async disconnectConnector(agentId: string, connectorId: string): Promise<void> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/external-auth/integrations/${encodeURIComponent(connectorId)}`;
+    const response = await httpClient.delete(endpoint, true);
+    assertSuccess(response, 'Failed to disconnect connector');
+  },
+
+  async removeConnector(agentId: string, connectorId: string): Promise<void> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/external-auth/integrations/${encodeURIComponent(connectorId)}/remove`;
+    const response = await httpClient.delete(endpoint, true);
+    assertSuccess(response, 'Failed to remove connector');
+  },
+
+  async toggleAutomation(agentId: string, automation: SuperagentAutomation): Promise<SuperagentAutomation> {
+    const response = await httpClient.post<SuperagentAutomation>(
+      `${getAutomationPath(appsEndpoint, agentId, automation)}/toggle`,
+      undefined,
+      true,
+    );
+    assertSuccess(response, 'Failed to update automation status');
+    return normalizeAutomationResponse(response.data, automation);
+  },
+
+  async archiveAutomation(agentId: string, automation: SuperagentAutomation): Promise<SuperagentAutomation> {
+    const response = await httpClient.post<SuperagentAutomation>(
+      `${getAutomationPath(appsEndpoint, agentId, automation)}/archive`,
+      undefined,
+      true,
+    );
+    assertSuccess(response, 'Failed to archive automation');
+    return normalizeAutomationResponse(response.data, automation);
+  },
+
+  async restoreAutomation(agentId: string, automation: SuperagentAutomation): Promise<SuperagentAutomation> {
+    const response = await httpClient.post<SuperagentAutomation>(
+      `${getAutomationPath(appsEndpoint, agentId, automation)}/unarchive`,
+      undefined,
+      true,
+    );
+    assertSuccess(response, 'Failed to restore automation');
+    return normalizeAutomationResponse(response.data, automation);
+  },
+
+  async deleteAutomation(agentId: string, automation: SuperagentAutomation): Promise<void> {
+    const response = await httpClient.delete(getAutomationPath(appsEndpoint, agentId, automation), true);
+    assertSuccess(response, 'Failed to delete automation');
+  },
+
+  async runAutomationNow(agentId: string, automation: SuperagentAutomation): Promise<void> {
+    if (automation.automation_type !== 'scheduled') {
+      throw new Error('Only scheduled automations can be run manually from mobile.');
+    }
+
+    const response = await httpClient.post(
+      `${getAutomationPath(appsEndpoint, agentId, automation)}/run`,
+      undefined,
+      true,
+    );
+    assertSuccess(response, 'Failed to run automation');
+  },
+
+  async createVoiceLiveSession(agentId: string, conversationId: string | null): Promise<SuperagentVoiceLiveSession> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/user-agent/voice/live-session`;
+    const response = await httpClient.post<VoiceLiveSessionResponse>(
+      endpoint,
+      {
+        conversation_id: conversationId,
+      },
+      true,
+    );
+    if (!response.success && response.error?.status === 404) {
+      throw new Error(
+        `Live Voice is not available on ${normalizeBaseUrl(config.baseUrl)}. Deploy the Superagent voice session endpoint or point the mobile app to a backend that has /user-agent/voice/live-session.`,
+      );
+    }
+    assertSuccess(response, 'Failed to start Live Voice');
+    if (!response.data?.session_id || !response.data.stream_token) {
+      throw new Error('Live Voice returned no session token');
+    }
+    return {
+      sessionId: response.data.session_id,
+      streamToken: response.data.stream_token,
+      websocketUrl: buildVoiceStreamUrl(config.baseUrl, agentId, response.data.session_id),
+    };
+  },
+
+  async deleteVoiceLiveSession(agentId: string, sessionId: string): Promise<void> {
+    const endpoint = `${appsEndpoint}/${encodeURIComponent(agentId)}/user-agent/voice/live-session/${encodeURIComponent(sessionId)}`;
+    const response = await httpClient.delete(endpoint, true);
+    assertSuccess(response, 'Failed to clean up Live Voice session');
+  },
+  };
+}
+
+function createHttpClient(config: SuperagentApiClientConfig) {
+  return {
+    async request<T>(endpoint: string, options: HttpRequestOptions): Promise<HttpResult<T>> {
+      const {
+        authRequired = true,
+        body,
+        headers = {},
+        method,
+      } = options;
+
+      const requestHeaders: Record<string, string> = {
+        'X-Client-Platform': 'mobile_native',
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        ...(await config.getHeaders?.()),
+        ...headers,
+      };
+
+      if (authRequired) {
+        const accessToken = await config.getAccessToken();
+        if (!accessToken) {
+          return {
+            success: false,
+            error: {message: 'User not authenticated'},
+          };
+        }
+        requestHeaders.Authorization = `Bearer ${accessToken}`;
+      }
+
+      try {
+        const response = await fetch(endpoint, {
+          body: body === undefined ? undefined : JSON.stringify(body),
+          headers: requestHeaders,
+          method,
+        });
+
+        const data = response.status === 204 ? undefined : await parseJson(response);
+        if (!response.ok) {
+          return {
+            success: false,
+            error: {
+              message: getResponseErrorMessage(data, response.status),
+              status: response.status,
+            },
+          };
+        }
+
+        return {
+          success: true,
+          data: data as T,
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: {message: error instanceof Error ? error.message : 'Request failed'},
+        };
+      }
+    },
+
+    get<T = unknown>(endpoint: string, authRequired = true): Promise<HttpResult<T>> {
+      return this.request<T>(endpoint, { authRequired, method: 'GET' });
+    },
+
+    post<T = unknown>(endpoint: string, body?: unknown, authRequired = true): Promise<HttpResult<T>> {
+      return this.request<T>(endpoint, { authRequired, body, method: 'POST' });
+    },
+
+    delete<T = unknown>(endpoint: string, authRequired = true): Promise<HttpResult<T>> {
+      return this.request<T>(endpoint, { authRequired, method: 'DELETE' });
+    },
+  };
+}
+
+async function parseJson(response: Response) {
+  try {
+    return await response.json();
+  } catch {
+    return undefined;
+  }
+}
+
+function getResponseErrorMessage(data: unknown, status: number) {
+  if (data && typeof data === 'object') {
+    const body = data as { detail?: unknown; message?: unknown };
+    if (typeof body.message === 'string') {
+      return body.message;
+    }
+    if (typeof body.detail === 'string') {
+      return body.detail;
+    }
+  }
+
+  return `Request failed with status ${status}`;
+}
+
+function normalizeBaseUrl(url: string) {
+  return url.trim().replace(/\/+$/, '');
+}
+
+function buildVoiceStreamUrl(baseUrl: string, agentId: string, sessionId: string) {
+  const normalized = normalizeBaseUrl(baseUrl);
+  const websocketBase = normalized
+    .replace(/^https:/i, 'wss:')
+    .replace(/^http:/i, 'ws:');
+
+  return `${websocketBase}/api/apps/${encodeURIComponent(agentId)}/user-agent/voice/live-session/${encodeURIComponent(sessionId)}/stream`;
+}
+
+async function listSandboxFilesAt(
+  httpClient: SuperagentHttpClient,
+  appsEndpoint: string,
+  agentId: string,
+  path: string,
+): Promise<string[]> {
+  const endpoint = buildUrl(`${appsEndpoint}/${encodeURIComponent(agentId)}/sandbox/files/list`, {
+    include_all: 'true',
+    path,
+  });
+  const response = await httpClient.get<SandboxFileListResponse>(endpoint, true);
+  assertSuccess(response, 'Failed to load Superagent files');
+  return response.data?.files ?? [];
+}
+
+async function listUserAgentSandboxFilePaths(
+  httpClient: SuperagentHttpClient,
+  appsEndpoint: string,
+  agentId: string,
+) {
+  const paths = new Set(DEFAULT_SANDBOX_FILE_PATHS);
+
+  await Promise.all(
+    USER_AGENT_SANDBOX_LIST_PATHS.map(async (sandboxPath) => {
+      try {
+        const files = await listSandboxFilesAt(httpClient, appsEndpoint, agentId, sandboxPath);
+        files.forEach((filePath) => paths.add(joinSandboxPath(sandboxPath, filePath)));
+      } catch {
+        // Missing optional directories should not make the Files tab look empty.
+      }
+    }),
+  );
+
+  return [...paths];
+}
+
+function mergeSandboxFilePaths(...pathGroups: string[][]) {
+  return [...new Set(pathGroups.flat())];
+}
+
+function joinSandboxPath(parentPath: string, childPath: string) {
+  return `${parentPath.replace(/\/+$/, '')}/${childPath.replace(/^\/+/, '')}`;
+}
+
+async function updateAgent(
+  httpClient: SuperagentHttpClient,
+  appsEndpoint: string,
+  agentId: string,
+  body: Partial<UserAgentApp>,
+): Promise<SuperagentAgent> {
+  const response = await httpClient.request<UserAgentApp>(`${appsEndpoint}/${encodeURIComponent(agentId)}`, {
+    authRequired: true,
+    body,
+    method: 'PUT',
+  });
+  assertSuccess(response, 'Failed to update Superagent');
+  if (!response.data?.id) {
+    throw new Error('Superagent update returned no app id');
+  }
+  return toAgent(response.data);
+}
+
+function toAgent(app: UserAgentApp): SuperagentAgent {
+  return {
+    id: app.id,
+    name: app.name || 'New Superagent',
+    description: app.user_description,
+    logoUrl: app.logo_url,
+    model: app.model ?? 'default',
+    organizationId: app.organization_id ?? null,
+    toolsPermissionConfig: app.tools_permission_config ?? undefined,
+    avatarIndex: app.avatar_index,
+    updatedAt: app.updated_date ?? app.created_date,
+  };
+}
+
+function toConnector(integration: AppIntegration): SuperagentConnector {
+  const meta = SUPERAGENT_CONNECTOR_CATALOG.find((connector) => connector.id === integration.integration_type);
+  return {
+    accessMode: detectAccessMode(integration.scopes ?? [], integration.integration_type),
+    accountIdentifier: integration.integration_account_identifier,
+    accessModes: meta?.accessModes,
+    category: meta?.category,
+    exampleScopes: meta?.exampleScopes,
+    iconBackgroundColor: meta?.iconBackgroundColor,
+    iconFallbackLabel: meta?.iconFallbackLabel,
+    iconUrl: meta?.iconUrl,
+    id: integration.integration_type,
+    name: meta?.name ?? formatConnectorName(integration.integration_type),
+    scopes: integration.scopes,
+    status: normalizeConnectorStatus(integration.status),
+    subtitle: meta?.subtitle,
+    supportsReadOnly: meta?.supportsReadOnly,
+  };
+}
+
+function detectAccessMode(scopes: string[], connectorId?: string): SuperagentConnectorAccessMode {
+  const connector = connectorId ? SUPERAGENT_CONNECTOR_CATALOG.find((item) => item.id === connectorId) : undefined;
+  if (connector?.accessModes) {
+    const filtered = scopes.filter((scope) => !OAUTH_INJECTED_SCOPES.has(scope));
+    const readOnlyScopes = connector.accessModes.readOnly;
+    const readOnlySet = new Set(readOnlyScopes);
+    if (filtered.length === readOnlyScopes.length && filtered.every((scope) => readOnlySet.has(scope))) {
+      return 'read_only';
+    }
+    return 'full_access';
+  }
+
+  const hasWriteScope = scopes.some((scope) => /write|send|create|edit|delete|manage|modify|repo/i.test(scope));
+  return hasWriteScope ? 'full_access' : 'read_only';
+}
+
+function formatConnectorName(connectorId: string) {
+  return connectorId
+    .split(/[_-]/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function getConnectorScopes(connectorId: string, accessMode?: SuperagentConnectorAccessMode) {
+  const connector = SUPERAGENT_CONNECTOR_CATALOG.find((item) => item.id === connectorId);
+  if (!connector) {
+    return null;
+  }
+
+  if (connector.accessModes) {
+    return accessMode === 'read_only' ? connector.accessModes.readOnly : connector.accessModes.fullAccess;
+  }
+
+  return connector.exampleScopes ?? null;
+}
+
+function isPaymentIntegration(integrationType: string) {
+  return integrationType === 'stripe' || integrationType === 'stripe_payment' || integrationType === 'wix_payments';
+}
+
+function normalizeConnectorStatus(status?: string): SuperagentConnector['status'] {
+  const normalized = status?.toLowerCase();
+  if (normalized === 'expired' || normalized === 'disconnected') {
+    return normalized;
+  }
+  return 'active';
+}
+
+function getAutomationPath(appsEndpoint: string, agentId: string, automation: SuperagentAutomation) {
+  const type = getAutomationType(automation);
+  return `${appsEndpoint}/${encodeURIComponent(agentId)}/automations/${type}/${encodeURIComponent(automation.id)}`;
+}
+
+function getAutomationType(automation: SuperagentAutomation) {
+  if (
+    automation.automation_type === 'scheduled' ||
+    automation.automation_type === 'entity' ||
+    automation.automation_type === 'connector'
+  ) {
+    return automation.automation_type;
+  }
+
+  throw new Error(`Unsupported automation type: ${automation.automation_type}`);
+}
+
+function normalizeAutomationResponse(
+  updated: SuperagentAutomation | undefined,
+  fallback: SuperagentAutomation,
+): SuperagentAutomation {
+  if (!updated?.id) {
+    return fallback;
+  }
+
+  return {
+    ...updated,
+    automation_type: updated.automation_type ?? fallback.automation_type,
+  };
+}
+
+function normalizeTelegramStatus(status: TelegramStatusResponse | undefined): SuperagentTelegramChannelStatus {
+  return {
+    botLink: status?.bot_link,
+    botName: status?.bot_name,
+    botUsername: status?.bot_username,
+    connected: !!status?.connected,
+  };
+}
+
+function normalizeIMessageStatus(status: IMessageStatusResponse | undefined): SuperagentIMessageChannelStatus {
+  return {
+    connected: !!status?.connected,
+    phoneNumber: status?.phone_number ?? null,
+  };
+}
+
+async function runtimeRequest<T = unknown>(
+  httpClient: SuperagentHttpClient,
+  appsEndpoint: string,
+  agentId: string,
+  runtimeAuthToken: string,
+  path: string,
+  options: {
+    body?: unknown;
+    method: 'DELETE' | 'GET' | 'POST';
+  },
+) {
+  return httpClient.request<T>(`${appsEndpoint}/${encodeURIComponent(agentId)}${path}`, {
+    authRequired: false,
+    body: options.body,
+    headers: {
+      Authorization: `Bearer ${runtimeAuthToken}`,
+    },
+    method: options.method,
+  });
+}
+
+function getAutomationTime(automation: SuperagentAutomation) {
+  const dateValue = automation.updated_date ?? automation.created_date ?? automation.last_run_at;
+  if (!dateValue) {
+    return 0;
+  }
+
+  const timestamp = Date.parse(dateValue);
+  return Number.isNaN(timestamp) ? 0 : timestamp;
+}
+
+function assertSuccess<T>(response: HttpResult<T>, fallback: string): asserts response is HttpResult<T> & {success: true} {
+  if (!response.success) {
+    throw new Error(response.error?.message || fallback);
+  }
+}
+
+function buildUrl(baseUrl: string, query: Record<string, string>) {
+  const queryString = Object.entries(query)
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+    .join('&');
+  return `${baseUrl}?${queryString}`;
+}