@base44/superagent-native 0.0.1 → 0.0.3

package/src/styles.ts

@@ -1,6 +1,7 @@
 import { StyleSheet } from 'react-native';
+import { createThemedStyles } from './theme';
 
-export const styles = StyleSheet.create({
+export const styles = createThemedStyles({
   safeArea: { flex: 1, backgroundColor: '#000000' },
   container: { paddingBottom: 34, paddingHorizontal: 14, paddingTop: 10 },
   homeTopBar: {
@@ -25,7 +26,14 @@ export const styles = StyleSheet.create({
     minWidth: 0,
   },
   topBarTitle: { color: '#F7F7F7', fontSize: 17, fontWeight: '900', letterSpacing: 0, lineHeight: 21 },
-  homeIntro: { marginBottom: 14, paddingTop: 2 },
+  homeTitle: {
+    color: '#FAFAFA',
+    fontSize: 24,
+    fontWeight: '900',
+    marginBottom: 30,
+    marginTop: 60,
+    textAlign: 'center',
+  },
   header: {
     alignItems: 'center',
     flexDirection: 'row',
@@ -52,14 +60,14 @@ export const styles = StyleSheet.create({
     alignItems: 'center',
     backgroundColor: '#0B0B0C',
     borderColor: '#242427',
-    borderRadius: 18,
+    borderRadius: 16,
     borderWidth: 1,
     padding: 32,
   },
   heroPanel: {
     backgroundColor: '#0B0B0C',
     borderColor: '#242427',
-    borderRadius: 22,
+    borderRadius: 16,
     borderWidth: 1,
     overflow: 'hidden',
     padding: 14,
@@ -74,21 +82,16 @@ export const styles = StyleSheet.create({
   agentCard: {
     alignItems: 'flex-start',
     flexDirection: 'row',
-    minHeight: 100,
   },
   avatar: {
     alignItems: 'center',
-    backgroundColor: '#111111',
-    borderColor: '#2A2A2A',
-    borderRadius: 24,
-    borderWidth: 1,
     height: 52,
     justifyContent: 'center',
     width: 52,
   },
   avatarText: { color: '#F7F7F7', fontSize: 18, fontWeight: '900' },
   agentCardBody: { flex: 1, marginLeft: 13, minWidth: 0 },
-  agentName: { color: '#F7F7F7', fontSize: 21, fontWeight: '900', lineHeight: 25 },
+  agentName: { color: '#F7F7F7', fontSize: 16, fontWeight: '900', lineHeight: 20 },
   agentDescription: { color: '#BDBDC2', fontSize: 14, fontWeight: '600', lineHeight: 20, marginTop: 7 },
   chevron: { color: '#8E8E93', fontSize: 20, fontWeight: '900' },
   agentMetaRow: { flexDirection: 'row', flexWrap: 'wrap', marginLeft: 65, marginTop: 14 },
@@ -106,7 +109,7 @@ export const styles = StyleSheet.create({
   emptyPanel: {
     backgroundColor: '#0B0B0C',
     borderColor: '#242427',
-    borderRadius: 22,
+    borderRadius: 16,
     borderWidth: 1,
     padding: 16,
   },
@@ -134,6 +137,9 @@ export const styles = StyleSheet.create({
     paddingHorizontal: 18,
   },
   primaryButtonText: { color: '#111111', fontSize: 16, fontWeight: '900' },
+  // Overrides primaryButton's marginTop so the card's continue button sits 12px
+  // below the agent description (no meta pills between them anymore).
+  heroContinueButton: { marginTop: 12 },
   secondaryButton: {
     alignItems: 'center',
     backgroundColor: '#151515',
@@ -147,6 +153,13 @@ export const styles = StyleSheet.create({
     paddingHorizontal: 16,
   },
   secondaryButtonText: { color: '#F4F4F5', fontSize: 14, fontWeight: '900', marginLeft: 7 },
+  linkButton: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginTop: 14,
+    paddingVertical: 12,
+  },
+  linkButtonText: { color: '#FF5A1F', fontSize: 14, fontWeight: '900' },
   recentSection: { marginTop: 22 },
   sectionHeader: {
     alignItems: 'center',
@@ -160,7 +173,7 @@ export const styles = StyleSheet.create({
     alignItems: 'center',
     backgroundColor: '#0B0B0C',
     borderColor: '#242427',
-    borderRadius: 17,
+    borderRadius: 16,
     borderWidth: 1,
     flexDirection: 'row',
     justifyContent: 'space-between',
@@ -174,10 +187,6 @@ export const styles = StyleSheet.create({
   agentRowDescription: { color: '#8E8E93', fontSize: 12, fontWeight: '600', lineHeight: 17, marginTop: 3 },
   compactAvatar: {
     alignItems: 'center',
-    backgroundColor: '#111111',
-    borderColor: '#2A2A2A',
-    borderRadius: 15,
-    borderWidth: 1,
     height: 38,
     justifyContent: 'center',
     width: 38,

package/src/superagentApiClient.ts

@@ -16,6 +16,7 @@ import type {
   SuperagentSecret,
   SuperagentTelegramChannelStatus,
   SuperagentToolPermissionConfig,
+  SuperagentWhatsAppChannelStatus,
 } from './types';
 import { SUPERAGENT_CONNECTOR_CATALOG } from './connectorCatalog';
 import { DEFAULT_SANDBOX_FILE_PATHS, normalizeFilePaths } from './fileTreeUtils';
@@ -80,6 +81,7 @@ type UserAgentApp = {
 type AppIntegration = {
   integration_type: string;
   integration_account_identifier?: string | null;
+  requires_connection_config?: boolean;
   scopes?: string[];
   status?: string;
 };
@@ -127,13 +129,22 @@ type IMessageStatusResponse = {
   phone_number?: string | null;
 };
 
+type WhatsAppStatusResponse = {
+  connected: boolean;
+  user_handle?: string | null;
+};
+
 type IMessageActivationResponse = {
   code?: string;
   phone_number?: string;
 };
 
-type SandboxFileListResponse = {
-  files?: string[];
+// /sandbox/files/list-entries returns rich entries (path + size/modified_at), and
+// honors include_all (binaries). Legacy sandbox drivers may still emit bare path
+// strings, so accept either.
+type SandboxFileEntry = { path: string };
+type SandboxFileEntriesResponse = {
+  files?: Array<SandboxFileEntry | string>;
 };
 
 export type SuperagentConnectorsResult = {
@@ -160,15 +171,16 @@ export function createSuperagentApiClient(config: SuperagentApiClientConfig) {
 
   return {
   async listAgents(): Promise<SuperagentAgent[]> {
-    const query = {
-      app_type: 'user_agent',
-      ...(config.currentUserId ? {owner_id: config.currentUserId} : {}),
-    };
+    // Match the web Superagent home/sidebar query: filter only by app_type and let
+    // the backend default (all_apps_workspace) scope to apps the user can access —
+    // owned AND those shared with them as an editor collaborator. Adding owner_id /
+    // filter_mode=owned_by_me intersects with ownership and hides shared agents
+    // (owned_by_me is also an admin-only mode on the backend). The backend already
+    // enforces access, so this only widens the list to what web already shows.
     const endpoint = buildUrl(appsEndpoint, {
       fields: AGENT_FIELDS,
-      filter_mode: 'owned_by_me',
       limit: '9',
-      q: JSON.stringify(query),
+      q: JSON.stringify({app_type: 'user_agent'}),
       skip: '0',
       sort: '-updated_date',
     });
@@ -240,7 +252,10 @@ export function createSuperagentApiClient(config: SuperagentApiClientConfig) {
   async saveSecret(agentId: string, name: string, value: string): Promise<void> {
     const response = await httpClient.post(
       `${appsEndpoint}/${encodeURIComponent(agentId)}/secrets`,
-      {[name.trim().toUpperCase()]: value.trim()},
+      // Normalize only the key name — preserve the secret value byte-for-byte.
+      // Credentials (PEM/private keys, tokens with a trailing newline, passwords)
+      // can require exact leading/trailing whitespace; trimming would corrupt them.
+      {[name.trim().toUpperCase()]: value},
       true,
     );
     assertSuccess(response, 'Failed to save Superagent secret');
@@ -365,6 +380,12 @@ export function createSuperagentApiClient(config: SuperagentApiClientConfig) {
     return response.data.token;
   },
 
+  // The token rides in the query string here (unlike runtimeRequest's
+  // Authorization header) on purpose: this URL is opened as a *browser
+  // navigation* via nativeAdapters.openUrl (not an XHR), so headers can't be
+  // attached — the backend must authenticate it from the `token` query param.
+  // Hardening to a dedicated short-lived/single-use connect token is a backend
+  // follow-up; until that exists this is the only auth channel for a nav URL.
   getWhatsAppConnectUrl(agentId: string, runtimeAuthToken: string): string {
     return buildUrl(`${appsEndpoint}/${encodeURIComponent(agentId)}/agents/${USER_AGENT_AGENT_NAME}/whatsapp`, {
       token: runtimeAuthToken,
@@ -372,19 +393,24 @@ export function createSuperagentApiClient(config: SuperagentApiClientConfig) {
   },
 
   async getChannelStatus(agentId: string, runtimeAuthToken: string): Promise<SuperagentChannelStatus> {
-    const [telegram, imessage] = await Promise.all([
+    const [telegram, imessage, whatsapp] = await Promise.all([
       this.getTelegramStatus(agentId, runtimeAuthToken).catch(() => ({connected: false})),
       this.getIMessageStatus(agentId, runtimeAuthToken).catch(() => ({connected: false})),
+      // null signals the editor-gated status call failed (e.g. 403 for viewers).
+      this.getWhatsAppStatus(agentId, runtimeAuthToken).catch(() => null),
     ]);
 
     return {
       imessage,
       line: {connected: false},
       telegram,
-      whatsapp: {
-        connected: false,
-        connectUrl: this.getWhatsAppConnectUrl(agentId, runtimeAuthToken),
-      },
+      // Only expose connectUrl (which carries the runtime token) when the
+      // editor-gated /whatsapp/status call succeeded. Viewers get a 403 there, so
+      // omit it — otherwise they'd hold a working WhatsApp connect URL even though
+      // the backend redirect doesn't re-check editor access.
+      whatsapp: whatsapp
+        ? {...whatsapp, connectUrl: this.getWhatsAppConnectUrl(agentId, runtimeAuthToken)}
+        : {connected: false},
     };
   },
 
@@ -404,6 +430,14 @@ export function createSuperagentApiClient(config: SuperagentApiClientConfig) {
     return normalizeIMessageStatus(response.data);
   },
 
+  async getWhatsAppStatus(agentId: string, runtimeAuthToken: string): Promise<SuperagentWhatsAppChannelStatus> {
+    const response = await runtimeRequest<WhatsAppStatusResponse>(httpClient, appsEndpoint, agentId, runtimeAuthToken, '/whatsapp/status', {
+      method: 'GET',
+    });
+    assertSuccess(response, 'Failed to load WhatsApp status');
+    return normalizeWhatsAppStatus(response.data);
+  },
+
   async generateIMessageCode(agentId: string, runtimeAuthToken: string): Promise<SuperagentIMessageActivation> {
     const response = await runtimeRequest<IMessageActivationResponse>(httpClient, appsEndpoint, agentId, runtimeAuthToken, '/imessage/generate-code', {
       method: 'POST',
@@ -664,13 +698,18 @@ async function listSandboxFilesAt(
   agentId: string,
   path: string,
 ): Promise<string[]> {
-  const endpoint = buildUrl(`${appsEndpoint}/${encodeURIComponent(agentId)}/sandbox/files/list`, {
+  // Use list-entries, not list: /sandbox/files/list ignores include_all and
+  // filters out binary assets (PNG/PDF/...), so they never reach the native tree.
+  // recursive=true so nested files under each listed directory appear — the native
+  // tree is built from this one listing and has no per-folder lazy fetch.
+  const endpoint = buildUrl(`${appsEndpoint}/${encodeURIComponent(agentId)}/sandbox/files/list-entries`, {
     include_all: 'true',
     path,
+    recursive: 'true',
   });
-  const response = await httpClient.get<SandboxFileListResponse>(endpoint, true);
+  const response = await httpClient.get<SandboxFileEntriesResponse>(endpoint, true);
   assertSuccess(response, 'Failed to load Superagent files');
-  return response.data?.files ?? [];
+  return (response.data?.files ?? []).map((entry) => (typeof entry === 'string' ? entry : entry.path));
 }
 
 async function listUserAgentSandboxFilePaths(
@@ -747,6 +786,9 @@ function toConnector(integration: AppIntegration): SuperagentConnector {
     iconUrl: meta?.iconUrl,
     id: integration.integration_type,
     name: meta?.name ?? formatConnectorName(integration.integration_type),
+    // Trust the live backend flag from /external-auth/list as well as the static
+    // catalog metadata — either signalling config-required must surface in the UI.
+    requiresConnectionConfig: meta?.requiresConnectionConfig || integration.requires_connection_config,
     scopes: integration.scopes,
     status: normalizeConnectorStatus(integration.status),
     subtitle: meta?.subtitle,
@@ -812,7 +854,8 @@ function getAutomationType(automation: SuperagentAutomation) {
   if (
     automation.automation_type === 'scheduled' ||
     automation.automation_type === 'entity' ||
-    automation.automation_type === 'connector'
+    automation.automation_type === 'connector' ||
+    automation.automation_type === 'in_app_agent'
   ) {
     return automation.automation_type;
   }
@@ -850,6 +893,13 @@ function normalizeIMessageStatus(status: IMessageStatusResponse | undefined): Su
   };
 }
 
+function normalizeWhatsAppStatus(status: WhatsAppStatusResponse | undefined): SuperagentWhatsAppChannelStatus {
+  return {
+    connected: !!status?.connected,
+    userHandle: status?.user_handle ?? null,
+  };
+}
+
 async function runtimeRequest<T = unknown>(
   httpClient: SuperagentHttpClient,
   appsEndpoint: string,

package/src/theme.ts

@@ -0,0 +1,254 @@
+import { createContext, useContext } from 'react';
+import { StyleSheet } from 'react-native';
+
+/**
+ * Theming for the Superagent native package.
+ *
+ * All stylesheets in this package are authored in the original dark palette;
+ * light mode (the default) is derived by remapping those colors through the
+ * tables below. `createThemedStyles` builds both StyleSheets up front and
+ * returns a proxy that resolves against the active scheme on every property
+ * read, so existing `styles.foo` call sites keep working unchanged. The
+ * scheme lives in module state synced from the provider in
+ * SuperagentHomeScreen during render; nothing in the tree is memoized, so a
+ * scheme change at the root re-renders (and re-reads) everything.
+ */
+
+export type SuperagentColorScheme = 'light' | 'dark';
+
+let currentScheme: SuperagentColorScheme = 'light';
+
+export function getSuperagentColorScheme(): SuperagentColorScheme {
+  return currentScheme;
+}
+
+export function syncSuperagentColorScheme(scheme: SuperagentColorScheme) {
+  currentScheme = scheme;
+}
+
+export const SuperagentThemeContext = createContext<{
+  scheme: SuperagentColorScheme;
+  setScheme: (scheme: SuperagentColorScheme) => void;
+}>({ scheme: 'light', setScheme: () => {} });
+
+export function useSuperagentTheme() {
+  return useContext(SuperagentThemeContext);
+}
+
+// Dark background -> light background.
+const BG_MAP: Record<string, string> = {
+  '#000000': '#F3F3F3',
+  '#050505': '#FFFFFF',
+  '#070707': '#FFFFFF',
+  '#080808': '#FFFFFF',
+  '#0A0A0A': '#FFFFFF',
+  '#0B0B0C': '#FFFFFF',
+  '#0F0F10': '#FFFFFF',
+  '#101010': '#FFFFFF',
+  '#101012': '#FFFFFF',
+  '#111111': '#FFFFFF',
+  '#111113': '#FFFFFF',
+  '#141414': '#FFFFFF',
+  '#151515': '#F4F4F5',
+  '#171717': '#F4F4F5',
+  '#181818': '#F4F4F5',
+  '#1B1B1B': '#F4F4F5',
+  '#1F1F22': '#F4F4F5',
+  '#1F1F23': '#F4F4F5',
+  '#242424': '#F4F4F5',
+  '#242427': '#F4F4F5',
+  '#252528': '#F4F4F5',
+  '#262626': '#F4F4F5',
+  '#2A2A2A': '#E4E4E7',
+  '#2C2C2E': '#E4E4E7',
+  '#3A3A3E': '#E4E4E7',
+  '#BDBDC2': '#A1A1AA',
+  '#F4F4F5': '#18181B',
+  // Cream CTAs become the dark CTA treatment on light surfaces.
+  '#F7F3E7': '#18181B',
+  '#F4F0E6': '#18181B',
+  // Status / accent tints.
+  '#11251A': '#DCFCE7',
+  '#13231D': '#DCFCE7',
+  '#21110A': '#FFEDD5',
+  '#1D120D': '#FFEDD5',
+  '#1C0F10': '#FEE2E2',
+  '#241111': '#FEE2E2',
+  '#351516': '#FEE2E2',
+  '#102036': '#DBEAFE',
+  '#1E1B4B': '#E0E7FF',
+  '#312E81': '#E0E7FF',
+};
+
+// Dark border -> light border.
+const BORDER_MAP: Record<string, string> = {
+  '#101012': '#E4E4E7',
+  '#1F1F23': '#E4E4E7',
+  '#242427': '#E4E4E7',
+  '#242429': '#E4E4E7',
+  '#252529': '#E4E4E7',
+  '#27272A': '#E4E4E7',
+  '#29292E': '#E4E4E7',
+  '#2A2A2A': '#E4E4E7',
+  '#2A2A2D': '#E4E4E7',
+  '#2A2A2E': '#E4E4E7',
+  '#303035': '#E4E4E7',
+  '#333333': '#E4E4E7',
+  '#333338': '#E4E4E7',
+  '#34343A': '#E4E4E7',
+  '#353535': '#E4E4E7',
+  '#353539': '#E4E4E7',
+  '#38383D': '#E4E4E7',
+  '#3A3A3C': '#E4E4E7',
+  '#3F3F46': '#D4D4D8',
+  '#F4F4F5': '#18181B',
+  // Status borders.
+  '#3B2222': '#FECACA',
+  '#552022': '#FECACA',
+  '#5F2424': '#FECACA',
+  '#3A2317': '#FED7AA',
+  '#4A2413': '#FED7AA',
+};
+
+// Dark foreground (text / icons) -> light foreground.
+const TEXT_MAP: Record<string, string> = {
+  '#FFFFFF': '#18181B',
+  // Home title: near-white in dark mode, #0F0F0F in light (per design spec).
+  '#FAFAFA': '#0F0F0F',
+  // Dark-on-light-accent foregrounds invert with their CTA surfaces.
+  '#111111': '#FFFFFF',
+  '#F7F7F7': '#18181B',
+  '#F4F4F5': '#18181B',
+  '#E4E4E7': '#3F3F46',
+  '#DADADA': '#3F3F46',
+  '#D4D4D8': '#3F3F46',
+  '#C7C7CC': '#52525B',
+  '#BDBDC2': '#52525B',
+  '#A1A1AA': '#52525B',
+  '#8E8E93': '#71717A',
+  '#73737A': '#A1A1AA',
+  // Status / accent foregrounds tuned for light surfaces.
+  '#FCA5A5': '#DC2626',
+  '#FECACA': '#B91C1C',
+  '#FF6B6B': '#DC2626',
+  '#86EFAC': '#15803D',
+  '#34D399': '#059669',
+  '#FDE68A': '#A16207',
+  '#F8D77B': '#A16207',
+  '#FDE047': '#A16207',
+  '#FBBF24': '#B45309',
+  '#C9CAF8': '#4F46E5',
+  '#A5B4FC': '#4F46E5',
+  '#E0E7FF': '#3730A3',
+  '#93C5FD': '#1D4ED8',
+  '#8AB4F8': '#1D4ED8',
+};
+
+/** Light-mode color for a dark-authored foreground (text / icon) color. */
+export function themedColor(darkColor: string): string {
+  if (currentScheme === 'dark') {
+    return darkColor;
+  }
+  return TEXT_MAP[darkColor.toUpperCase()] ?? darkColor;
+}
+
+/** Light-mode color for a dark-authored surface (background) color. */
+export function themedSurface(darkColor: string): string {
+  if (currentScheme === 'dark') {
+    return darkColor;
+  }
+  return BG_MAP[darkColor.toUpperCase()] ?? darkColor;
+}
+
+/** Light-mode color for a dark-authored border color. */
+export function themedBorder(darkColor: string): string {
+  if (currentScheme === 'dark') {
+    return darkColor;
+  }
+  return BORDER_MAP[darkColor.toUpperCase()] ?? darkColor;
+}
+
+// Brand typography: Wix Madefor, with the original heavy weights stepped
+// down to match the web app's lighter look. Native consumers must bundle the
+// "Wix Madefor Text" font family; the web demo loads it from Google Fonts.
+const SUPERAGENT_FONT_FAMILY = 'Wix Madefor Text';
+
+const FONT_WEIGHT_MAP: Record<string, string> = {
+  '900': '600',
+  '800': '500',
+  '700': '500',
+  '600': '400',
+  bold: '600',
+};
+
+function applyTypography(style: Record<string, unknown>) {
+  const isText = 'fontSize' in style || 'fontWeight' in style || 'lineHeight' in style;
+  if (!isText) {
+    return style;
+  }
+  const next = { ...style };
+  if (!next.fontFamily) {
+    next.fontFamily = SUPERAGENT_FONT_FAMILY;
+  }
+  const weight = next.fontWeight;
+  if (typeof weight === 'string' && FONT_WEIGHT_MAP[weight]) {
+    next.fontWeight = FONT_WEIGHT_MAP[weight];
+  }
+  return next;
+}
+
+const BG_KEYS = new Set(['backgroundColor']);
+const BORDER_KEYS = new Set([
+  'borderColor',
+  'borderTopColor',
+  'borderBottomColor',
+  'borderLeftColor',
+  'borderRightColor',
+]);
+const TEXT_KEYS = new Set(['color', 'textDecorationColor', 'tintColor']);
+// shadowColor stays dark in both schemes.
+
+function toLightStyle(style: Record<string, unknown>) {
+  const light: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(style)) {
+    if (typeof value === 'string' && value.startsWith('#')) {
+      const upper = value.toUpperCase();
+      if (BG_KEYS.has(key)) {
+        light[key] = BG_MAP[upper] ?? value;
+        continue;
+      }
+      if (BORDER_KEYS.has(key)) {
+        light[key] = BORDER_MAP[upper] ?? value;
+        continue;
+      }
+      if (TEXT_KEYS.has(key)) {
+        light[key] = TEXT_MAP[upper] ?? value;
+        continue;
+      }
+    }
+    light[key] = value;
+  }
+  return light;
+}
+
+/**
+ * Drop-in replacement for StyleSheet.create: takes dark-authored styles and
+ * returns a proxy resolving each style against the active color scheme.
+ */
+export function createThemedStyles<T extends StyleSheet.NamedStyles<T>>(base: T): T {
+  const typographyBase = Object.fromEntries(
+    Object.entries(base).map(([name, style]) => [name, applyTypography(style as Record<string, unknown>)]),
+  );
+  const dark = StyleSheet.create(typographyBase as unknown as T);
+  const lightBase = Object.fromEntries(
+    Object.entries(typographyBase).map(([name, style]) => [name, toLightStyle(style as Record<string, unknown>)]),
+  );
+  const light = StyleSheet.create(lightBase as unknown as T);
+
+  return new Proxy(dark, {
+    get(_, property) {
+      const sheets = currentScheme === 'dark' ? dark : light;
+      return sheets[property as keyof T];
+    },
+  });
+}

package/src/types.ts

@@ -1,6 +1,8 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { ProviderProps } from 'react-native-paper';
 
+import type { SuperagentColorScheme } from './theme';
+
 export type SuperagentToolCall = {
   id?: string;
   name: string;
@@ -144,10 +146,15 @@ export type SuperagentConversation = {
   messages?: SuperagentMessage[];
 };
 
+export type SuperagentAgentDonePayload = {
+  sender_platform_user_id?: string;
+  bootstrap_intro?: boolean;
+};
+
 export type SuperagentRealtimeHandlers = {
   onMessage?: (message: SuperagentMessage) => void;
   onConversation?: (conversation: SuperagentConversation) => void;
-  onAgentDone?: () => void;
+  onAgentDone?: (payload?: SuperagentAgentDonePayload) => void;
   onReconnect?: () => void;
   onError?: (error: unknown) => void;
 };
@@ -241,6 +248,7 @@ export type SuperagentTelegramChannelStatus = {
 export type SuperagentWhatsAppChannelStatus = {
   connected?: boolean;
   connectUrl?: string | null;
+  userHandle?: string | null;
 };
 
 export type SuperagentLineActivation = {
@@ -380,6 +388,10 @@ export type SuperagentNativeClient = {
   getConversation(conversationId: string): Promise<SuperagentConversation>;
   getMessages(conversationId: string, params?: { limit?: number; before?: string }): Promise<SuperagentPaginatedMessages>;
   createConversation(metadata?: Record<string, unknown>): Promise<SuperagentConversation>;
+  // Seeds a brand-new conversation with the lightweight intro turn. Unlike
+  // addMessage, the backend persists the seed hidden and skips sandbox acquisition,
+  // so opening an empty chat doesn't stall on a cold sandbox or burn a tool turn.
+  bootstrapIntro(conversationId: string, messageParams?: Record<string, unknown>): Promise<{ started: boolean }>;
   addMessage(conversationId: string, message: Partial<SuperagentMessage>): Promise<unknown>;
   stopConversation(conversationId: string): Promise<void>;
   getQueuedMessages(conversationId: string): Promise<{ messages: QueuedSuperagentMessage[] }>;
@@ -421,6 +433,11 @@ export type SuperagentMarkdownRendererProps = {
 export type SuperagentMarkdownRenderer = ComponentType<SuperagentMarkdownRendererProps>;
 
 export type SuperagentHomeScreenProps = {
+  activeAgentId?: string | null;
+  /** Initial color scheme; the in-app settings toggle can change it. Defaults to 'light'. */
+  defaultColorScheme?: SuperagentColorScheme;
+  /** Called when the user changes the scheme from settings (e.g. to persist it). */
+  onColorSchemeChange?: (scheme: SuperagentColorScheme) => void;
   agents?: SuperagentAgent[];
   latestMessages?: SuperagentMessage[];
   messagesByAgentId?: Record<string, SuperagentMessage[]>;
@@ -433,6 +450,9 @@ export type SuperagentHomeScreenProps = {
   navigationMode?: 'internal' | 'external';
   paperTheme?: ProviderProps['theme'];
   currentUserAvatarUrl?: string | null;
+  // Platform user id of the signed-in user. Used to ignore agent_done events from
+  // other collaborators in shared conversations (sender_platform_user_id filter).
+  currentUserId?: string | null;
   currentUserName?: string;
   fileLoadError?: string | null;
   fileLoadFailed?: boolean;
@@ -465,7 +485,7 @@ export type SuperagentHomeScreenProps = {
   isLoadingChannels?: boolean;
   isLoadingConnectors?: boolean;
   onCancelConnectorConnection?: (input: { agentId: string; connectorId: string }) => void;
-  onConnectConnector?: (input: SuperagentConnectorActionInput) => Promise<boolean | void> | boolean | void;
+  onConnectConnector?: (input: SuperagentConnectorActionInput) => Promise<boolean | string | void> | boolean | string | void;
   onDisconnectConnector?: (input: SuperagentConnectorActionInput) => Promise<void> | void;
   onArchiveAutomation?: (input: SuperagentAutomationActionInput) => Promise<void> | void;
   onCloneAgent?: (input: SuperagentAgentActionInput) => Promise<void> | void;