@socialseal/cli 0.1.1 → 0.1.3

package/src/index.js

@@ -12,8 +12,10 @@ const CLI_KEY_HEADER = 'X-CLI-Key';
 const WORKSPACE_HEADER = 'X-Workspace-Id';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 300000;
+const DEFAULT_POLL_INTERVAL_MS = 2000;
 const MAX_TIMEOUT_MS = 900000;
 const LEGACY_ENABLED = process.env.SOCIALSEAL_ENABLE_LEGACY === '1';
+const STATIC_TOOL_REGISTRY_NOTE = 'This registry is shipped with the CLI for stable discovery. It is not live backend enumeration, so environment-specific availability can drift.';
 const EXIT_CODES = {
   OK: 0,
   UNKNOWN: 1,
@@ -28,18 +30,66 @@ const KNOWN_TOOLS = [
   { name: 'deep-exploration-runs', category: 'agent', description: 'Read or persist deep exploration render runs.' },
   { name: 'workspace-notes', category: 'agent', description: 'Search, create, update, and pin workspace note memory.' },
   { name: 'workspace-onboarding', category: 'agent', description: 'Read or update workspace onboarding metadata used by the agent.' },
-  { name: 'brand-group-management', category: 'brand', description: 'Manage brand groups, aliases, competitors, and rule configuration.' },
-  { name: 'enqueue-brand-metrics-backfill', category: 'brand', description: 'Queue backfill jobs for brand metrics refreshes.' },
+  {
+    name: 'brand-group-management',
+    category: 'brand',
+    description: 'Manage brand groups, aliases, competitors, and rule configuration.',
+    objectType: 'brand_group',
+    transport: 'rest_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['list', 'create', 'update', 'delete', 'add_member', 'remove_member'],
+    notes: 'Brand groups are not tracking groups.',
+  },
+  {
+    name: 'enqueue-brand-metrics-backfill',
+    category: 'brand',
+    description: 'Queue backfill jobs for brand metrics refreshes.',
+    objectType: 'brand_metrics_backfill_job',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    notes: 'Refreshes brand metrics for brands/workspaces. It does not refresh a tracking group by UUID.',
+  },
   { name: 'export-report', category: 'export', description: 'Generate report exports (csv/json/markdown/html/excel_data).' },
-  { name: 'export_tracking_data', category: 'export', description: 'Stream tracking exports as CSV for a group or tracking item.' },
+  {
+    name: 'export_tracking_data',
+    category: 'export',
+    description: 'Stream tracking exports as CSV for a group or tracking item.',
+    objectType: 'tracking_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'disabled_by_default',
+    notes: 'group_id expects a numeric tracking_group id, not a brand_group UUID.',
+  },
   { name: 'douyin-geo-api', category: 'search', description: 'Query Douyin search and geo data.' },
   { name: 'google-ai-search', category: 'search', description: 'Run Google AI search queries and fetch result snapshots.' },
   { name: 'instagram-geo-api', category: 'search', description: 'Query Instagram search and geo data.' },
   { name: 'tiktok-geo-api', category: 'search', description: 'Query TikTok search and geo data.' },
   { name: 'xhs-geo-api', category: 'search', description: 'Query Xiaohongshu search and geo data.' },
   { name: 'youtube-geo-api', category: 'search', description: 'Query YouTube search and geo data.' },
-  { name: 'group-management', category: 'tracking', description: 'Create, update, list, and delete tracking groups and memberships.' },
-  { name: 'tracking', category: 'tracking', description: 'Create, update, list, refresh, and delete tracking items.' },
+  {
+    name: 'group-management',
+    category: 'tracking',
+    description: 'Manage tracking groups and memberships.',
+    objectType: 'tracking_group',
+    transport: 'rest_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'disabled_by_default',
+    actionAliases: ['list', 'get', 'create', 'update', 'delete', 'refresh', 'list_items'],
+    notes: 'REST-style surface under /groups. Use action aliases via `tools call` or raw REST semantics.',
+  },
+  {
+    name: 'tracking',
+    category: 'tracking',
+    description: 'Manage tracking items.',
+    objectType: 'tracking_item',
+    transport: 'rest_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['list', 'get', 'create', 'update', 'delete', 'refresh'],
+    notes: 'REST-style surface. The CLI normalizes common action payloads for this tool.',
+  },
   { name: 'journey-feedback', category: 'vnext', description: 'Record acceptance or rejection feedback for opportunity bundles.' },
   { name: 'opportunity-bundle-approve', category: 'vnext', description: 'Approve an opportunity bundle and create tracking coverage.' },
   { name: 'search-journey-run', category: 'vnext', description: 'Run a search journey for a subject across supported platforms.' },
@@ -58,8 +108,12 @@ const KNOWN_TOOLS = [
   { name: 'vnext-topics-auto-tag', category: 'vnext', description: 'Auto-tag keyword and topic assignments with Gemini-assisted review.' },
 ];
 
+function getConfigPath() {
+  return process.env.SOCIALSEAL_CONFIG || DEFAULT_CONFIG_PATH;
+}
+
 function loadConfig() {
-  const configPath = process.env.SOCIALSEAL_CONFIG || DEFAULT_CONFIG_PATH;
+  const configPath = getConfigPath();
   try {
     if (!fs.existsSync(configPath)) return {};
     const raw = fs.readFileSync(configPath, 'utf8');
@@ -70,6 +124,15 @@ function loadConfig() {
   }
 }
 
+function saveConfig(config) {
+  const configPath = getConfigPath();
+  const normalizedConfig = Object.fromEntries(
+    Object.entries(config || {}).filter(([, value]) => value !== undefined),
+  );
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(normalizedConfig, null, 2)}\n`);
+}
+
 function resolveApiKey(opts, config) {
   return opts.apiKey || process.env.SOCIALSEAL_API_KEY || config.apiKey;
 }
@@ -86,6 +149,19 @@ function resolveSupabaseUrl(opts, config) {
   return opts.supabaseUrl || process.env.SOCIALSEAL_SUPABASE_URL || config.supabaseUrl;
 }
 
+function resolveWorkspaceSelection(opts, config) {
+  if (typeof opts.workspaceId === 'string' && opts.workspaceId.trim().length > 0) {
+    return { workspaceId: opts.workspaceId.trim(), source: 'flag' };
+  }
+  if (typeof process.env.SOCIALSEAL_WORKSPACE_ID === 'string' && process.env.SOCIALSEAL_WORKSPACE_ID.trim().length > 0) {
+    return { workspaceId: process.env.SOCIALSEAL_WORKSPACE_ID.trim(), source: 'env' };
+  }
+  if (typeof config.workspaceId === 'string' && config.workspaceId.trim().length > 0) {
+    return { workspaceId: config.workspaceId.trim(), source: 'config' };
+  }
+  return { workspaceId: null, source: null };
+}
+
 class CliError extends Error {
   constructor(message, { code = 'CLI_ERROR', exitCode = EXIT_CODES.UNKNOWN, status, hint, details } = {}) {
     super(message);
@@ -252,6 +328,800 @@ function ensureJsonObject(value, label) {
   return value;
 }
 
+function mergeWorkspaceIdIntoPayload(payload, workspaceId) {
+  if (!workspaceId) return payload;
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return payload;
+  }
+  if (typeof payload.workspaceId === 'string' && payload.workspaceId.trim().length > 0) {
+    return payload;
+  }
+  return { ...payload, workspaceId };
+}
+
+function hasOwn(value, key) {
+  return Boolean(value) && Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function firstDefined(source, keys) {
+  if (!source || typeof source !== 'object' || Array.isArray(source)) return undefined;
+  for (const key of keys) {
+    if (hasOwn(source, key) && source[key] !== undefined && source[key] !== null) {
+      return source[key];
+    }
+  }
+  return undefined;
+}
+
+function trimString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function stripUndefinedEntries(value) {
+  return Object.fromEntries(
+    Object.entries(value || {}).filter(([, entry]) => entry !== undefined),
+  );
+}
+
+function resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) {
+  const workspaceId = firstDefined(payload, ['workspace_id', 'workspaceId']);
+  if (typeof workspaceId === 'string' && workspaceId.trim().length > 0) {
+    return workspaceId.trim();
+  }
+  return fallbackWorkspaceId || null;
+}
+
+function isUuidLike(value) {
+  return typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(value.trim());
+}
+
+function coercePositiveInteger(value, label) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const parsed = Number(value);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  throw new CliError(`Invalid ${label}: expected a positive integer.`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: isUuidLike(value)
+      ? `${label} expects a numeric tracking id. Brand-group ids are UUIDs and use brand-group-management instead.`
+      : null,
+    details: value,
+  });
+}
+
+function buildPathWithQuery(basePath, query) {
+  const params = new URLSearchParams();
+  for (const [key, rawValue] of Object.entries(query || {})) {
+    if (rawValue === undefined || rawValue === null || rawValue === '') continue;
+    if (Array.isArray(rawValue)) {
+      for (const entry of rawValue) {
+        if (entry !== undefined && entry !== null && entry !== '') {
+          params.append(key, String(entry));
+        }
+      }
+      continue;
+    }
+    params.set(key, String(rawValue));
+  }
+  const queryString = params.toString();
+  return queryString ? `${basePath}?${queryString}` : basePath;
+}
+
+function normalizeTrackingType(value) {
+  const normalized = trimString(value).toLowerCase();
+  if (!normalized) return undefined;
+  if (normalized === 'keyword' || normalized === 'search') return 'search';
+  if (normalized === 'account' || normalized === 'creator') return 'creator';
+  if (normalized === 'hashtag') return 'hashtag';
+  throw new CliError(`Invalid tracking type: ${value}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Use keyword/search, hashtag, or account/creator.',
+  });
+}
+
+function normalizeTrackingPayload(payload, fallbackWorkspaceId) {
+  const trackValue = firstDefined(payload, ['track_value', 'trackValue', 'value']);
+  const refreshFrequency = firstDefined(payload, ['refresh_frequency', 'refreshFrequency']);
+  const nextRefreshAt = firstDefined(payload, ['next_refresh_at', 'nextRefreshAt']);
+  const region = firstDefined(payload, ['region']);
+  const platform = firstDefined(payload, ['platform']);
+  const brandIds = firstDefined(payload, ['brand_ids', 'brandIds']);
+  const includeInactive = firstDefined(payload, ['includeInactive', 'include_inactive']);
+  const isActive = firstDefined(payload, ['is_active', 'isActive']);
+  const limit = firstDefined(payload, ['limit']);
+  const page = firstDefined(payload, ['page']);
+  const offset = firstDefined(payload, ['offset']);
+  const itemId = firstDefined(payload, ['item_id', 'itemId', 'id']);
+
+  return stripUndefinedEntries({
+    action: trimString(firstDefined(payload, ['action'])) || undefined,
+    workspaceId: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId),
+    item_id: coercePositiveInteger(itemId, 'item_id'),
+    name: trimString(firstDefined(payload, ['name'])) || (trimString(trackValue) || undefined),
+    track_type: normalizeTrackingType(firstDefined(payload, ['track_type', 'trackType', 'type'])),
+    track_value: trimString(trackValue) || undefined,
+    refresh_frequency: trimString(refreshFrequency) || undefined,
+    next_refresh_at: nextRefreshAt ?? undefined,
+    region: typeof region === 'string' ? region.trim() || undefined : region,
+    platform: trimString(platform) || undefined,
+    brand_ids: Array.isArray(brandIds) ? brandIds : undefined,
+    limit: limit !== undefined ? Number(limit) : undefined,
+    page: page !== undefined ? Number(page) : undefined,
+    offset: offset !== undefined ? Number(offset) : undefined,
+    is_active: typeof isActive === 'boolean' ? isActive : undefined,
+    include_inactive: typeof includeInactive === 'boolean' ? includeInactive : undefined,
+  });
+}
+
+function normalizeGroupManagementPayload(payload, fallbackWorkspaceId) {
+  const groupId = firstDefined(payload, ['group_id', 'groupId', 'id']);
+  const limit = firstDefined(payload, ['limit']);
+  const page = firstDefined(payload, ['page']);
+  return stripUndefinedEntries({
+    action: trimString(firstDefined(payload, ['action'])) || undefined,
+    workspaceId: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId),
+    group_id: coercePositiveInteger(groupId, 'group_id'),
+    name: trimString(firstDefined(payload, ['name'])) || undefined,
+    description: firstDefined(payload, ['description']),
+    platform: trimString(firstDefined(payload, ['platform', 'groupPlatform'])) || undefined,
+    refresh_frequency: trimString(firstDefined(payload, ['refresh_frequency', 'refreshFrequency'])) || undefined,
+    next_refresh_at: firstDefined(payload, ['next_refresh_at', 'nextRefreshAt']) ?? undefined,
+    brand_id: trimString(firstDefined(payload, ['brand_id', 'brandId'])) || undefined,
+    limit: limit !== undefined ? Number(limit) : undefined,
+    page: page !== undefined ? Number(page) : undefined,
+  });
+}
+
+function normalizeBrandGroupPayload(payload, fallbackWorkspaceId) {
+  return stripUndefinedEntries({
+    action: trimString(firstDefined(payload, ['action'])) || undefined,
+    workspaceId: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId),
+    workspace_id: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) || undefined,
+    brand_group_id: trimString(firstDefined(payload, ['brand_group_id', 'brandGroupId', 'group_id', 'groupId', 'id'])) || undefined,
+    brand_id: trimString(firstDefined(payload, ['brand_id', 'brandId'])) || undefined,
+    name: trimString(firstDefined(payload, ['name'])) || undefined,
+    description: firstDefined(payload, ['description']),
+  });
+}
+
+function normalizeBackfillPayload(payload, fallbackWorkspaceId) {
+  return stripUndefinedEntries({
+    workspace_id: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) || undefined,
+    brand_id: trimString(firstDefined(payload, ['brand_id', 'brandId'])) || undefined,
+    tracking_group_ids: firstDefined(payload, ['tracking_group_ids', 'trackingGroupIds']),
+    backfill_days: firstDefined(payload, ['backfill_days', 'backfillDays']),
+    max_tracking_groups: firstDefined(payload, ['max_tracking_groups', 'maxTrackingGroups']),
+    max_videos: firstDefined(payload, ['max_videos', 'maxVideos']),
+    max_summaries: firstDefined(payload, ['max_summaries', 'maxSummaries']),
+    bump_user_revision: firstDefined(payload, ['bump_user_revision', 'bumpUserRevision']),
+    bump_workspace_revision: firstDefined(payload, ['bump_workspace_revision', 'bumpWorkspaceRevision']),
+  });
+}
+
+function normalizeTrackingExportPayload(payload, fallbackWorkspaceId) {
+  const groupId = firstDefined(payload, ['group_id', 'groupId', 'tracking_group_id', 'trackingGroupId']);
+  const itemId = firstDefined(payload, ['tracking_item_id', 'trackingItemId', 'item_id', 'itemId']);
+  return stripUndefinedEntries({
+    workspace_id: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) || undefined,
+    group_id: coercePositiveInteger(groupId, 'group_id'),
+    tracking_item_id: coercePositiveInteger(itemId, 'tracking_item_id'),
+    time_period: trimString(firstDefined(payload, ['time_period', 'timePeriod'])) || undefined,
+  });
+}
+
+function translateTrackingAction(payload, workspaceId) {
+  const action = payload.action ? payload.action.toLowerCase() : null;
+  if (!action) {
+    return {
+      method: 'POST',
+      pathSuffix: '',
+      body: stripUndefinedEntries({
+        name: payload.name,
+        track_type: payload.track_type,
+        track_value: payload.track_value,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        region: payload.region,
+        platform: payload.platform,
+        brand_ids: payload.brand_ids,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'list' || action === 'item_list') {
+    const limit = Number.isFinite(payload.limit) ? payload.limit : 20;
+    const page = Number.isFinite(payload.page) ? Math.max(1, payload.page) : 1;
+    const offset = Number.isFinite(payload.offset) ? Math.max(0, payload.offset) : ((page - 1) * limit);
+    const isActive = typeof payload.is_active === 'boolean'
+      ? payload.is_active
+      : (payload.include_inactive ? undefined : true);
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('', {
+        workspace_id: workspaceId || undefined,
+        limit,
+        offset,
+        track_type: payload.track_type,
+        track_value: payload.track_value,
+        platform: payload.platform,
+        region: payload.region,
+        is_active: isActive,
+      }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'get' || action === 'item_get') {
+    const itemId = coercePositiveInteger(payload.item_id, 'item_id');
+    if (!itemId) {
+      throw new CliError('item_id is required for tracking get.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery(`/${itemId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'create' || action === 'item_create') {
+    return {
+      method: 'POST',
+      pathSuffix: '',
+      body: stripUndefinedEntries({
+        name: payload.name,
+        track_type: payload.track_type,
+        track_value: payload.track_value,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        region: payload.region,
+        platform: payload.platform,
+        brand_ids: payload.brand_ids,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'update' || action === 'item_update') {
+    const itemId = coercePositiveInteger(payload.item_id, 'item_id');
+    if (!itemId) {
+      throw new CliError('item_id is required for tracking update.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'PATCH',
+      pathSuffix: buildPathWithQuery(`/${itemId}`, { workspace_id: workspaceId || undefined }),
+      body: stripUndefinedEntries({
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'delete' || action === 'item_delete') {
+    const itemId = coercePositiveInteger(payload.item_id, 'item_id');
+    if (!itemId) {
+      throw new CliError('item_id is required for tracking delete.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: buildPathWithQuery(`/${itemId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'refresh' || action === 'item_refresh') {
+    const itemId = coercePositiveInteger(payload.item_id, 'item_id');
+    if (!itemId) {
+      throw new CliError('item_id is required for tracking refresh.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery(`/${itemId}/refresh`, { workspace_id: workspaceId || undefined }),
+      body: {},
+      workspaceId,
+    };
+  }
+
+  throw new CliError(`Unsupported tracking action: ${payload.action}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Supported tracking actions: list, get, create, update, delete, refresh.',
+  });
+}
+
+function translateGroupManagementAction(payload, workspaceId, originalMethod) {
+  const action = payload.action ? payload.action.toLowerCase() : null;
+
+  if (!action && originalMethod === 'GET') {
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('/groups', { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (!action) {
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery('/groups', { workspace_id: workspaceId || undefined }),
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        platform: payload.platform,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        brand_id: payload.brand_id,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'list' || action === 'group_list') {
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('/groups', { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'get' || action === 'group_get') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group get.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'create' || action === 'group_create') {
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery('/groups', { workspace_id: workspaceId || undefined }),
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        platform: payload.platform,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        brand_id: payload.brand_id,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'update' || action === 'group_update') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group update.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'PATCH',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}`, { workspace_id: workspaceId || undefined }),
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        brand_id: payload.brand_id,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'delete' || action === 'group_delete') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group delete.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'refresh' || action === 'group_refresh') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group refresh.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/refresh`, { workspace_id: workspaceId || undefined }),
+      body: {},
+      workspaceId,
+    };
+  }
+
+  if (action === 'list_items' || action === 'group_list_items') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group list_items.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/items`, {
+        workspace_id: workspaceId || undefined,
+        page: Number.isFinite(payload.page) ? payload.page : undefined,
+        limit: Number.isFinite(payload.limit) ? payload.limit : undefined,
+      }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  throw new CliError(`Unsupported group-management action: ${payload.action}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Supported group-management actions: list, get, create, update, delete, refresh, list_items.',
+  });
+}
+
+function translateBrandGroupAction(payload, workspaceId) {
+  const action = payload.action ? payload.action.toLowerCase() : null;
+  const brandGroupId = payload.brand_group_id || undefined;
+  const effectiveWorkspaceId = payload.workspace_id || workspaceId || undefined;
+
+  if (!action) {
+    return {
+      method: 'POST',
+      pathSuffix: '',
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        workspace_id: effectiveWorkspaceId,
+      }),
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'list') {
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('', { workspace_id: effectiveWorkspaceId }),
+      body: undefined,
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'create') {
+    return {
+      method: 'POST',
+      pathSuffix: '',
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        workspace_id: effectiveWorkspaceId,
+      }),
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'update') {
+    if (!brandGroupId) {
+      throw new CliError('brand_group_id is required for brand-group update.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'PATCH',
+      pathSuffix: `/${brandGroupId}`,
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+      }),
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'delete') {
+    if (!brandGroupId) {
+      throw new CliError('brand_group_id is required for brand-group delete.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: `/${brandGroupId}`,
+      body: undefined,
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'add_member') {
+    if (!brandGroupId || !payload.brand_id) {
+      throw new CliError('brand_group_id and brand_id are required for brand-group add_member.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: `/${brandGroupId}/members`,
+      body: { brand_id: payload.brand_id },
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'remove_member') {
+    if (!brandGroupId || !payload.brand_id) {
+      throw new CliError('brand_group_id and brand_id are required for brand-group remove_member.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: `/${brandGroupId}/members/${payload.brand_id}`,
+      body: undefined,
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  throw new CliError(`Unsupported brand-group-management action: ${payload.action}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Supported brand-group-management actions: list, create, update, delete, add_member, remove_member.',
+  });
+}
+
+function translateToolInvocation({ functionName, method, payload, resolvedWorkspaceId }) {
+  if (!isJsonObject(payload)) {
+    return {
+      method,
+      pathSuffix: '',
+      body: payload,
+      workspaceId: resolvedWorkspaceId,
+      normalizedPayload: payload,
+    };
+  }
+
+  if (functionName === 'tracking') {
+    const normalizedPayload = normalizeTrackingPayload(payload, resolvedWorkspaceId);
+    const workspaceId = normalizedPayload.workspaceId || resolvedWorkspaceId || null;
+    const translated = translateTrackingAction(normalizedPayload, workspaceId);
+    return { ...translated, normalizedPayload };
+  }
+
+  if (functionName === 'group-management') {
+    const normalizedPayload = normalizeGroupManagementPayload(payload, resolvedWorkspaceId);
+    const workspaceId = normalizedPayload.workspaceId || resolvedWorkspaceId || null;
+    const translated = translateGroupManagementAction(normalizedPayload, workspaceId, method);
+    return { ...translated, normalizedPayload };
+  }
+
+  if (functionName === 'brand-group-management') {
+    const normalizedPayload = normalizeBrandGroupPayload(payload, resolvedWorkspaceId);
+    const workspaceId = normalizedPayload.workspaceId || resolvedWorkspaceId || null;
+    const translated = translateBrandGroupAction(normalizedPayload, workspaceId);
+    return { ...translated, normalizedPayload };
+  }
+
+  if (functionName === 'enqueue-brand-metrics-backfill') {
+    const normalizedPayload = normalizeBackfillPayload(payload, resolvedWorkspaceId);
+    if (!normalizedPayload.brand_id && hasOwn(payload, 'group_id')) {
+      throw new CliError('enqueue-brand-metrics-backfill expects brand_id, not group_id.', {
+        code: 'INVALID_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+        hint: 'Use group-management refresh for tracking groups. Backfill jobs refresh brand metrics for a workspace brand.',
+      });
+    }
+    return {
+      method,
+      pathSuffix: '',
+      body: normalizedPayload,
+      workspaceId: resolvedWorkspaceId,
+      normalizedPayload,
+    };
+  }
+
+  if (functionName === 'export_tracking_data') {
+    const normalizedPayload = normalizeTrackingExportPayload(payload, resolvedWorkspaceId);
+    return {
+      method,
+      pathSuffix: '',
+      body: normalizedPayload,
+      workspaceId: normalizedPayload.workspace_id || resolvedWorkspaceId || null,
+      normalizedPayload,
+    };
+  }
+
+  return {
+    method,
+    pathSuffix: '',
+    body: payload,
+    workspaceId: resolvedWorkspaceId,
+    normalizedPayload: payload,
+  };
+}
+
+function isJsonObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isStateChangingMethod(method) {
+  return !['GET', 'HEAD', 'OPTIONS'].includes(method);
+}
+
+function emitWorkspaceContext(opts, { workspaceId, source, functionName, method }) {
+  if (!workspaceId || !isStateChangingMethod(method)) return;
+  process.stderr.write(
+    `[socialseal] Workspace: ${workspaceId}${source ? ` (${source})` : ''} for ${functionName} ${method}\n`,
+  );
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function resolvePollIntervalMs(opts) {
+  const raw = opts.pollInterval ?? process.env.SOCIALSEAL_POLL_INTERVAL_MS;
+  return parseTimeoutMs(raw, { defaultValue: DEFAULT_POLL_INTERVAL_MS, label: 'poll interval' });
+}
+
+function shouldHandleSearchJourneyRunAsync(functionName, method, payload, opts) {
+  if (String(functionName || '').trim() !== 'search-journey-run') return false;
+  if (method !== 'POST') return false;
+  if (!isJsonObject(payload)) return false;
+  if (payload.action === 'status') return false;
+  return opts.async === true || payload.executionMode === 'async';
+}
+
+function applySearchJourneyRunAsyncStart(payload, opts) {
+  if (!shouldHandleSearchJourneyRunAsync(opts.function, normalizeMethod(opts.method), payload, opts)) {
+    return payload;
+  }
+  return {
+    ...payload,
+    executionMode: 'async',
+  };
+}
+
+function formatJsonOutput(value, pretty) {
+  return JSON.stringify(value, null, pretty ? 2 : 0);
+}
+
+function emitJsonOutput(value, pretty) {
+  process.stdout.write(formatJsonOutput(value, pretty) + '\n');
+}
+
+function buildSearchJourneyRunFailure(data) {
+  const message = isJsonObject(data) && typeof data.error === 'string' && data.error.trim().length > 0
+    ? data.error
+    : 'search-journey-run failed';
+  return new CliError(message, {
+    code: 'ASYNC_RUN_FAILED',
+    exitCode: EXIT_CODES.SERVER,
+    details: truncateDetails(data),
+  });
+}
+
+async function pollSearchJourneyRun({
+  apiBase,
+  apiKey,
+  path,
+  workspaceId,
+  timeoutMs,
+  pollIntervalMs,
+  runId,
+  opts,
+}) {
+  if (!workspaceId) {
+    throw new CliError('Async search-journey-run polling requires a workspace id.', {
+      code: 'WORKSPACE_REQUIRED',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace.',
+    });
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus = null;
+
+  for (;;) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      throw new CliError('Timed out waiting for search-journey-run async completion.', {
+        code: 'ASYNC_WAIT_TIMEOUT',
+        exitCode: EXIT_CODES.SERVER,
+        hint: 'Increase --timeout <ms> or use --no-poll to return the run id immediately.',
+        details: truncateDetails({ runId, workspaceId, lastStatus }),
+      });
+    }
+
+    await sleep(Math.min(pollIntervalMs, remainingMs));
+
+    const res = await callApi({
+      apiBase,
+      apiKey,
+      path,
+      method: 'POST',
+      body: {
+        action: 'status',
+        workspaceId,
+        runId,
+      },
+      workspaceId,
+      timeoutMs: remainingMs,
+    });
+
+    if (!res.ok) {
+      throw await buildHttpError(res, {
+        label: 'Tool status poll',
+        functionName: 'search-journey-run',
+        method: 'POST',
+      });
+    }
+
+    const contentType = res.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      throw new CliError('search-journey-run status poll returned a non-JSON response.', {
+        code: 'INVALID_STATUS_RESPONSE',
+        exitCode: EXIT_CODES.SERVER,
+      });
+    }
+
+    const data = await res.json();
+    const status = isJsonObject(data) && typeof data.status === 'string' ? data.status : null;
+    if (status && status !== lastStatus) {
+      emitInfo(opts, `search-journey-run status: ${status}`);
+      lastStatus = status;
+    }
+
+    if (status === 'completed') return data;
+    if (status === 'failed') throw buildSearchJourneyRunFailure(data);
+    if (status === 'pending' || status === 'processing') continue;
+
+    throw new CliError('search-journey-run status poll returned an unexpected payload.', {
+      code: 'INVALID_STATUS_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+      details: truncateDetails(data),
+    });
+  }
+}
+
 function mapStatusToExitCode(status) {
   if (status === 401 || status === 403) return EXIT_CODES.AUTH;
   if (status === 404) return EXIT_CODES.NOT_FOUND;
@@ -260,6 +1130,10 @@ function mapStatusToExitCode(status) {
   return EXIT_CODES.UNKNOWN;
 }
 
+function isLocallyDisabledByDefaultFunction(functionName) {
+  return functionName === 'group-management' || functionName === 'export_tracking_data';
+}
+
 function buildStatusHint(status, context = {}) {
   switch (status) {
     case 401:
@@ -267,13 +1141,16 @@ function buildStatusHint(status, context = {}) {
       return 'Check your CLI key and workspace access.';
     case 404:
       if (context.functionName) {
+        if (isLocallyDisabledByDefaultFunction(context.functionName)) {
+          return `Unknown function "${context.functionName}". This tool is listed in the static registry, but it is disabled by default in some local Supabase environments. Check the deployment or enable it in supabase/config.toml.`;
+        }
         return `Unknown function "${context.functionName}". Double-check the name and API base.`;
       }
       return 'Check the API base URL and endpoint path.';
     case 405:
       return `Method not allowed. Try --method GET or ensure the endpoint supports ${context.method || 'this method'}.`;
     case 422:
-      return 'Validation error. Review the JSON payload schema.';
+      return 'Validation error. Review the JSON payload schema. For tracking/group tools, prefer the CLI action aliases or the documented REST semantics.';
     default:
       return null;
   }
@@ -437,6 +1314,68 @@ async function callApi({ apiBase, apiKey, path, method = 'POST', body, workspace
   return res;
 }
 
+async function fetchWorkspaceDirectory({ apiBase, apiKey, timeoutMs }) {
+  const res = await callApi({
+    apiBase,
+    apiKey,
+    path: '/cli/workspaces',
+    method: 'GET',
+    timeoutMs,
+  });
+  if (!res.ok) {
+    throw await buildHttpError(res, { label: 'Workspace discovery' });
+  }
+  const payload = await res.json();
+  return payload?.data || {};
+}
+
+function matchWorkspaceIdentifier(workspaces, identifier) {
+  const normalized = String(identifier || '').trim();
+  if (!normalized) {
+    throw new CliError('Missing workspace identifier.', {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Use a workspace id, slug, or exact name from `socialseal workspace list`.',
+    });
+  }
+
+  const exactId = workspaces.find((workspace) => workspace.id === normalized);
+  if (exactId) return exactId;
+
+  const exactSlug = workspaces.find((workspace) => workspace.slug === normalized);
+  if (exactSlug) return exactSlug;
+
+  const exactNameMatches = workspaces.filter(
+    (workspace) => typeof workspace.name === 'string' && workspace.name.trim().toLowerCase() === normalized.toLowerCase(),
+  );
+  if (exactNameMatches.length === 1) {
+    return exactNameMatches[0];
+  }
+  if (exactNameMatches.length > 1) {
+    throw new CliError(`Workspace name "${normalized}" is ambiguous.`, {
+      code: 'AMBIGUOUS_WORKSPACE',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Use the workspace id or slug from `socialseal workspace list`.',
+    });
+  }
+
+  throw new CliError(`Workspace "${normalized}" was not found.`, {
+    code: 'WORKSPACE_NOT_FOUND',
+    exitCode: EXIT_CODES.NOT_FOUND,
+    hint: 'Run `socialseal workspace list` to discover available workspaces.',
+  });
+}
+
+function formatWorkspaceLine(workspace, { isEffective = false, source = null, isSuggested = false } = {}) {
+  const tags = [];
+  if (workspace.isPersonalWorkspace) tags.push('personal');
+  if (isEffective) tags.push(source === 'config' ? 'default' : `active:${source}`);
+  if (isSuggested) tags.push('suggested');
+  const tagText = tags.length > 0 ? ` [${tags.join(', ')}]` : '';
+  const slugText = workspace.slug ? ` slug=${workspace.slug}` : '';
+  return `- ${workspace.name} (${workspace.id}) role=${workspace.role}${slugText}${tagText}`;
+}
+
 async function handleAgentRun(opts) {
   const config = loadConfig();
   const apiKey = requireApiKey(opts, config);
@@ -445,12 +1384,33 @@ async function handleAgentRun(opts) {
   const { resolvedApiBase, legacyUrl } = resolveApiTarget({ apiBase, legacyUrl: agentUrl });
   const timeoutMs = resolveTimeoutMs(opts, config);
   const idleTimeoutMs = resolveAgentIdleTimeoutMs(opts, config, timeoutMs);
+  const continuationToken = typeof opts.continue === 'string' ? opts.continue.trim() : '';
+  const { workspaceId: resolvedWorkspaceIdInput } = resolveWorkspaceSelection(opts, config);
+
+  if (continuationToken && opts.conversationId) {
+    throw new CliError('Use either --continue or --conversation-id, not both.', {
+      code: 'INVALID_ARGUMENTS',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  if (continuationToken && opts.createNew) {
+    throw new CliError('Use either --continue or --create-new, not both.', {
+      code: 'INVALID_ARGUMENTS',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  if (opts.conversationId && opts.createNew) {
+    throw new CliError('Use either --conversation-id or --create-new, not both.', {
+      code: 'INVALID_ARGUMENTS',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
 
   const headers = {
     'Content-Type': 'application/json',
     [CLI_KEY_HEADER]: apiKey,
   };
-  if (opts.workspaceId) headers[WORKSPACE_HEADER] = opts.workspaceId;
+  if (resolvedWorkspaceIdInput) headers[WORKSPACE_HEADER] = resolvedWorkspaceIdInput;
 
   const sessionUrl = resolvedApiBase
     ? `${resolvedApiBase.replace(/\/$/, '')}/cli/agent/session`
@@ -460,8 +1420,9 @@ async function handleAgentRun(opts) {
     method: 'POST',
     headers,
     body: JSON.stringify({
-      conversationId: opts.conversationId || undefined,
-      createNew: !!opts.createNew,
+      continuationToken: continuationToken || undefined,
+      conversationId: continuationToken ? undefined : (opts.conversationId || undefined),
+      createNew: continuationToken || opts.conversationId ? undefined : true,
     }),
   }, timeoutMs);
 
@@ -472,6 +1433,8 @@ async function handleAgentRun(opts) {
   const sessionData = await sessionRes.json();
   const sessionId = sessionData?.data?.sessionId || null;
   const initialConversationId = sessionData?.data?.activeConversationId || opts.conversationId || null;
+  const resolvedWorkspaceId = sessionData?.data?.workspaceId || resolvedWorkspaceIdInput || null;
+  const nextContinuationToken = sessionData?.data?.continuationToken || null;
   const wsUrl = sessionData?.data?.websocketUrl;
   if (!wsUrl) {
     throw new CliError('Missing websocketUrl in session response.', {
@@ -483,6 +1446,19 @@ async function handleAgentRun(opts) {
     opts,
     `Agent session created${sessionId ? ` (session ${sessionId})` : ''}${initialConversationId ? ` for conversation ${initialConversationId}` : ''}.`,
   );
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({
+      type: 'session_bootstrap',
+      payload: {
+        sessionId,
+        conversationId: initialConversationId,
+        workspaceId: resolvedWorkspaceId,
+        continuationToken: nextContinuationToken,
+      },
+    }) + '\n');
+  } else if (nextContinuationToken) {
+    process.stderr.write(`[socialseal] Continuation token: ${nextContinuationToken}\n`);
+  }
 
   const context = parseJsonInput(opts.context, { label: 'context', allowString: true });
   const message = opts.message;
@@ -721,16 +1697,38 @@ async function handleToolsCall(opts) {
   const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
   const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
   const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
+
+  const parsedPayload = parseJsonInput(opts.body, { label: 'body' }) ?? {};
+  const mergedPayload = mergeWorkspaceIdIntoPayload(parsedPayload, resolvedWorkspaceId);
+  const requestedMethod = normalizeMethod(opts.method);
+  const payload = applySearchJourneyRunAsyncStart(mergedPayload, { ...opts, method: requestedMethod });
+  const translated = translateToolInvocation({
+    functionName: opts.function,
+    method: requestedMethod,
+    payload,
+    resolvedWorkspaceId,
+  });
+  const method = normalizeMethod(translated.method);
+  const effectiveWorkspaceId = translated.workspaceId ?? resolvedWorkspaceId ?? null;
+  const path = useGateway
+    ? `/cli/tools/${opts.function}${translated.pathSuffix || ''}`
+    : `/functions/v1/${opts.function}${translated.pathSuffix || ''}`;
+
+  emitWorkspaceContext(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceId === resolvedWorkspaceId ? workspaceSource : 'body',
+    functionName: opts.function,
+    method,
+  });
 
-  const payload = parseJsonInput(opts.body, { label: 'body' }) ?? {};
-  const method = normalizeMethod(opts.method);
   const res = await callApi({
     apiBase: useGateway ? resolvedApiBase : legacyUrl,
     apiKey,
-    path: useGateway ? `/cli/tools/${opts.function}` : `/functions/v1/${opts.function}`,
+    path,
     method,
-    body: payload,
-    workspaceId: opts.workspaceId,
+    body: translated.body,
+    workspaceId: effectiveWorkspaceId,
     timeoutMs,
   });
 
@@ -745,7 +1743,45 @@ async function handleToolsCall(opts) {
   const contentType = res.headers.get('content-type') || '';
   if (contentType.includes('application/json')) {
     const data = await res.json();
-    process.stdout.write(JSON.stringify(data, null, opts.pretty ? 2 : 0) + '\n');
+    const shouldPoll = shouldHandleSearchJourneyRunAsync(opts.function, method, payload, opts) && opts.poll !== false;
+    if (!shouldPoll) {
+      emitJsonOutput(data, opts.pretty);
+      return;
+    }
+
+    const startStatus = isJsonObject(data) && typeof data.status === 'string' ? data.status : null;
+    if (startStatus === 'failed') {
+      throw buildSearchJourneyRunFailure(data);
+    }
+    if (startStatus === 'completed') {
+      emitJsonOutput(data, opts.pretty);
+      return;
+    }
+
+    const runId = isJsonObject(data) && typeof data.runId === 'string' ? data.runId : null;
+    if (!runId) {
+      throw new CliError('Async search-journey-run start response did not include a runId.', {
+        code: 'INVALID_START_RESPONSE',
+        exitCode: EXIT_CODES.SERVER,
+        details: truncateDetails(data),
+      });
+    }
+
+    emitInfo(opts, `search-journey-run async run started: ${runId}`);
+    const finalData = await pollSearchJourneyRun({
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      path: useGateway ? `/cli/tools/${opts.function}` : `/functions/v1/${opts.function}`,
+      workspaceId: isJsonObject(payload) && typeof payload.workspaceId === 'string'
+        ? payload.workspaceId
+        : resolvedWorkspaceId,
+      timeoutMs,
+      pollIntervalMs: resolvePollIntervalMs(opts),
+      runId,
+      opts,
+    });
+
+    emitJsonOutput(finalData, opts.pretty);
     return;
   }
 
@@ -757,7 +1793,7 @@ function handleToolsList(opts) {
   const payload = {
     discovery: 'built_in_registry',
     tools: KNOWN_TOOLS,
-    note: 'This registry is shipped with the CLI for stable discovery. It is not live backend enumeration.',
+    note: STATIC_TOOL_REGISTRY_NOTE,
   };
 
   if (opts.json) {
@@ -774,7 +1810,16 @@ function handleToolsList(opts) {
       currentCategory = tool.category;
       process.stdout.write(`\n${currentCategory}\n`);
     }
-    process.stdout.write(`- ${tool.name}: ${tool.description}\n`);
+    const qualifiers = [
+      tool.objectType ? `object=${tool.objectType}` : null,
+      tool.transport ? `transport=${tool.transport}` : null,
+      tool.knownLocalDevState ? `local=${tool.knownLocalDevState}` : null,
+    ].filter(Boolean);
+    const qualifierText = qualifiers.length > 0 ? ` [${qualifiers.join(', ')}]` : '';
+    process.stdout.write(`- ${tool.name}${qualifierText}: ${tool.description}\n`);
+    if (tool.notes) {
+      process.stdout.write(`  note: ${tool.notes}\n`);
+    }
   }
 
   process.stdout.write('\n[socialseal] Call a tool with: socialseal tools call --function <name> --body @payload.json\n');
@@ -787,6 +1832,7 @@ async function handleDataExportTracking(opts) {
   const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
   const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
   const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId } = resolveWorkspaceSelection(opts, config);
 
   if (!opts.groupId && !opts.itemId) {
     throw new CliError('Provide --group-id or --item-id.', {
@@ -795,6 +1841,13 @@ async function handleDataExportTracking(opts) {
     });
   }
 
+  if (opts.groupId !== undefined) {
+    opts.groupId = coercePositiveInteger(opts.groupId, 'group_id');
+  }
+  if (opts.itemId !== undefined) {
+    opts.itemId = coercePositiveInteger(opts.itemId, 'tracking_item_id');
+  }
+
   const payload = {
     tracking_item_id: opts.itemId || undefined,
     group_id: opts.groupId || undefined,
@@ -807,7 +1860,7 @@ async function handleDataExportTracking(opts) {
     path: useGateway ? '/cli/tools/export_tracking_data' : '/functions/v1/export_tracking_data',
     method: 'POST',
     body: payload,
-    workspaceId: opts.workspaceId,
+    workspaceId: resolvedWorkspaceId,
     timeoutMs,
   });
 
@@ -838,6 +1891,7 @@ async function handleDataExportReport(opts) {
   const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
   const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
   const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId } = resolveWorkspaceSelection(opts, config);
 
   const payload = ensureJsonObject(parseJsonInput(opts.payload, { label: 'payload' }), 'payload');
 
@@ -851,7 +1905,7 @@ async function handleDataExportReport(opts) {
       format: opts.format,
       payload,
     },
-    workspaceId: opts.workspaceId,
+    workspaceId: resolvedWorkspaceId,
     timeoutMs,
   });
 
@@ -893,6 +1947,150 @@ async function handleDataExportReport(opts) {
   process.stdout.write(JSON.stringify(json, null, opts.pretty ? 2 : 0) + '\n');
 }
 
+async function handleWorkspaceList(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const { resolvedApiBase } = resolveApiTarget({ apiBase, legacyUrl: null });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const directory = await fetchWorkspaceDirectory({
+    apiBase: resolvedApiBase,
+    apiKey,
+    timeoutMs,
+  });
+  const selection = resolveWorkspaceSelection({}, config);
+  const workspaces = Array.isArray(directory.workspaces) ? directory.workspaces : [];
+  const payload = {
+    ...directory,
+    effectiveWorkspaceId: selection.workspaceId,
+    effectiveWorkspaceSource: selection.source,
+  };
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  process.stdout.write('[socialseal] Available workspaces\n');
+  if (workspaces.length === 0) {
+    process.stdout.write('[socialseal] No accessible workspaces were returned for this key.\n');
+    return;
+  }
+
+  for (const workspace of workspaces) {
+    const isEffective = selection.workspaceId === workspace.id;
+    const isSuggested = !selection.workspaceId && directory.defaultWorkspaceId === workspace.id;
+    process.stdout.write(`${formatWorkspaceLine(workspace, { isEffective, source: selection.source, isSuggested })}\n`);
+  }
+
+  if (!selection.workspaceId && directory.defaultWorkspaceId) {
+    process.stdout.write('\n[socialseal] No local default is configured. Set one with: socialseal workspace use <id>\n');
+  }
+}
+
+async function handleWorkspaceCurrent(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const { resolvedApiBase } = resolveApiTarget({ apiBase, legacyUrl: null });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const directory = await fetchWorkspaceDirectory({
+    apiBase: resolvedApiBase,
+    apiKey,
+    timeoutMs,
+  });
+  const selection = resolveWorkspaceSelection({}, config);
+  const workspaces = Array.isArray(directory.workspaces) ? directory.workspaces : [];
+  const effectiveWorkspace = selection.workspaceId
+    ? workspaces.find((workspace) => workspace.id === selection.workspaceId) || null
+    : null;
+
+  if (selection.workspaceId && !effectiveWorkspace) {
+    throw new CliError(`Configured workspace "${selection.workspaceId}" is not accessible with this CLI key.`, {
+      code: 'WORKSPACE_NOT_ACCESSIBLE',
+      exitCode: EXIT_CODES.NOT_FOUND,
+      hint: 'Run `socialseal workspace list` to pick a valid workspace or `socialseal workspace clear` to unset the default.',
+    });
+  }
+
+  const payload = {
+    effectiveWorkspaceId: selection.workspaceId,
+    effectiveWorkspaceSource: selection.source,
+    workspace: effectiveWorkspace,
+    defaultWorkspaceId: directory.defaultWorkspaceId || null,
+    personalWorkspaceId: directory.personalWorkspaceId || null,
+  };
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  if (effectiveWorkspace) {
+    process.stdout.write(`[socialseal] Effective workspace: ${effectiveWorkspace.name} (${effectiveWorkspace.id}) via ${selection.source}\n`);
+    return;
+  }
+
+  if (directory.defaultWorkspaceId) {
+    const suggestedWorkspace = workspaces.find((workspace) => workspace.id === directory.defaultWorkspaceId) || null;
+    if (suggestedWorkspace) {
+      process.stdout.write(`[socialseal] No local default workspace is configured. Suggested workspace: ${suggestedWorkspace.name} (${suggestedWorkspace.id})\n`);
+      return;
+    }
+  }
+
+  process.stdout.write('[socialseal] No default workspace is configured and no accessible workspace suggestion is available.\n');
+}
+
+async function handleWorkspaceUse(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const { resolvedApiBase } = resolveApiTarget({ apiBase, legacyUrl: null });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const directory = await fetchWorkspaceDirectory({
+    apiBase: resolvedApiBase,
+    apiKey,
+    timeoutMs,
+  });
+  const workspaces = Array.isArray(directory.workspaces) ? directory.workspaces : [];
+  const workspace = matchWorkspaceIdentifier(workspaces, opts.identifier);
+  saveConfig({
+    ...config,
+    workspaceId: workspace.id,
+  });
+
+  const payload = {
+    success: true,
+    workspaceId: workspace.id,
+    workspace,
+    configPath: getConfigPath(),
+  };
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  process.stdout.write(`[socialseal] Default workspace set to ${workspace.name} (${workspace.id})\n`);
+}
+
+function handleWorkspaceClear(opts) {
+  const config = loadConfig();
+  const nextConfig = { ...config };
+  delete nextConfig.workspaceId;
+  saveConfig(nextConfig);
+
+  const payload = {
+    success: true,
+    configPath: getConfigPath(),
+  };
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  process.stdout.write('[socialseal] Default workspace cleared.\n');
+}
+
 const program = new Command();
 program
   .name('socialseal')
@@ -905,7 +2103,7 @@ if (typeof program.showHelpAfterError === 'function') {
 if (typeof program.showSuggestionAfterError === 'function') {
   program.showSuggestionAfterError(true);
 }
-program.addHelpText('after', `\nExamples:\n  socialseal agent run --message \"ping\"\n  socialseal tools list\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal data export-tracking --group-id 123 --time-period 30d\n`);
+program.addHelpText('after', `\nExamples:\n  socialseal workspace list\n  socialseal workspace use <workspace-id>\n  socialseal agent run --message \"ping\"\n  socialseal tools list\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>\n  socialseal data export-tracking --group-id 123 --time-period 30d\n`);
 
 program
   .command('agent')
@@ -916,6 +2114,7 @@ program
   .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
   .option('--api-key <key>', 'CLI API key')
   .option('--workspace-id <id>', 'Workspace id (for scoped keys)')
+  .option('--continue <token>', 'Continuation token from a previous agent run')
   .option('--conversation-id <id>', 'Conversation id to resume')
   .option('--create-new', 'Create a new conversation')
   .option('--json', 'Emit NDJSON events')
@@ -924,6 +2123,49 @@ program
   .option('--verbose', 'Show error details')
   .action((opts) => runCommand(handleAgentRun, opts));
 
+const workspace = program.command('workspace').description('Discover and manage the default workspace');
+
+workspace
+  .command('list')
+  .description('List accessible workspaces for this CLI key')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleWorkspaceList, opts));
+
+workspace
+  .command('current')
+  .description('Show the effective default workspace')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleWorkspaceCurrent, opts));
+
+workspace
+  .command('use <identifier>')
+  .description('Persist a default workspace by id, slug, or exact name')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((identifier, opts) => runCommand(handleWorkspaceUse, { ...opts, identifier }));
+
+workspace
+  .command('clear')
+  .description('Clear the locally configured default workspace')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleWorkspaceClear, opts));
+
 const tools = program.command('tools').description('Call edge functions directly (tool backends)');
 
 tools
@@ -939,6 +2181,9 @@ tools
   .requiredOption('--function <name>', 'Tool name (see official docs)')
   .option('--method <method>', 'HTTP method', 'POST')
   .option('--body <jsonOrFile>', 'JSON body or @file.json')
+  .option('--async', 'Request async execution for supported tool backends')
+  .option('--no-poll', 'Return immediately after async start instead of polling to completion')
+  .option('--poll-interval <ms>', 'Polling interval in milliseconds for supported async tool calls')
   .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
   .option('--api-key <key>', 'CLI API key')
   .option('--workspace-id <id>', 'Workspace id (for scoped keys)')