@socialseal/cli 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,8 +1,17 @@
 # Changelog
 
 ## Unreleased
+
+## 0.1.2 - 2026-03-18
+- Add `search-journey-run` async CLI ergonomics: `--async` starts the backend async mode, polling is on by default, and `--no-poll` returns the initial `runId` immediately.
+- Add `--poll-interval <ms>` for async `search-journey-run` status polling.
+- Treat terminal async `search-journey-run` failures as non-zero CLI exits instead of silent `200` JSON output.
+
+## 0.1.1 - 2026-03-13
 - Document public base URL and CLI error output.
 - Add request timeouts, verbose error output, and OSS-safe tool discovery behavior.
+- Ship a stable built-in tool registry for `tools list` instead of the hard-disabled discovery message.
+- Fail fast on agent WebSocket `error` events and surface session/tool progress diagnostics in `--verbose` mode.
 
 ## 0.1.0
 - Initial CLI with agent streaming, tools calls, and provisional data exports.

package/README.md

@@ -9,7 +9,9 @@
 Environment variables:
 - `SOCIALSEAL_API_KEY`
 - `SOCIALSEAL_API_BASE` (default `https://api.socialseal.co`)
+- `SOCIALSEAL_WORKSPACE_ID` (optional workspace override; takes precedence over config)
 - `SOCIALSEAL_TIMEOUT_MS` (optional request timeout override)
+- `SOCIALSEAL_AGENT_IDLE_TIMEOUT_MS` (optional agent WebSocket inactivity timeout override; default 300000)
 
 Optional config file:
 - `~/.config/socialseal/config.json`
@@ -18,22 +20,34 @@ Optional config file:
 {
   "apiKey": "ss_cli_...",
   "apiBase": "https://api.socialseal.co",
-  "timeoutMs": 30000
+  "workspaceId": "00000000-0000-0000-0000-000000000000",
+  "timeoutMs": 30000,
+  "agentIdleTimeoutMs": 300000
 }
 ```
 
 ## Commands
+- Workspace discovery/defaults:
+  - `socialseal workspace list`
+  - `socialseal workspace current`
+  - `socialseal workspace use <workspace-id|slug|exact-name>`
+  - `socialseal workspace clear`
+
 - Agent (non-interactive, streaming):
   - `socialseal agent run --message "..." --api-base https://api.socialseal.co --api-key <key> [--workspace-id <uuid>]`
+  - `socialseal agent run --message "..." --continue <token>`
   - `socialseal agent run --message "..." --timeout 60000`
+  - `socialseal agent run --message "..." --idle-timeout 300000 --verbose`
 
-- Tools list (limited):
+- Tools list (built-in registry):
   - `socialseal tools list`
   - `socialseal tools list --json`
 
 - Tools (direct edge function call):
   - `socialseal tools call --function <tool> --body @payload.json --api-base https://api.socialseal.co --api-key <key>`
   - `socialseal tools call --function <tool> --body @payload.json --json`
+  - `socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>`
+  - `socialseal tools call --function search-journey-run --body @payload.json --async --no-poll --workspace-id <uuid>`
 
 - Data exports (provisional):
   - `socialseal data export-tracking --group-id 123 --time-period 30d --out out.csv`
@@ -41,13 +55,29 @@ Optional config file:
 
 ## Notes
 - `export-report` and `export_tracking_data` are provisional until CLI export specs are finalized.
-- `tools list` does not enumerate internal endpoints in the OSS build. Refer to official docs for supported tool names.
-- Use `--timeout <ms>` to override the default 30s timeout for network calls.
+- `tools list` ships a stable built-in registry of supported direct-call function targets. It is not live backend enumeration.
+- `--timeout <ms>` controls HTTP request timeouts. Agent runs default to a 5-minute WebSocket inactivity timeout unless you set `--idle-timeout <ms>` (or the matching env/config value).
+- `search-journey-run` supports CLI-managed async polling: `--async` starts backend async mode, polling is on by default, `--no-poll` returns the initial `runId`, and `--poll-interval <ms>` controls the status polling cadence.
+- `socialseal agent run` now defaults to a fresh conversation. The CLI prints a continuation token to `stderr`; pass it back with `--continue <token>` to resume the same agent conversation explicitly.
+- Effective workspace precedence is: `--workspace-id` → `SOCIALSEAL_WORKSPACE_ID` → config `workspaceId` → backend personal-workspace fallback.
+- `socialseal workspace use ...` writes a local default workspace into `~/.config/socialseal/config.json`, which the CLI reuses for `agent`, `tools`, and `data` commands.
+- `socialseal workspace list` discovers the workspaces accessible to the current CLI key and marks the active/suggested default.
+- If a scoped CLI key cannot safely infer a workspace, `agent run` now fails closed and tells you to set `--workspace-id` or configure a local default first.
 
 ## Errors and exit codes
 - Exit codes: `2` (usage), `3` (auth), `4` (not found), `5` (server), `1` (unknown)
 - Add `--json` to `tools call` or `data` commands to emit machine-readable errors.
-- Add `--verbose` to print error details (suppressed by default).
+- Add `--verbose` to print error details plus agent session/tool progress diagnostics.
+
+## Troubleshooting
+- `SUPABASE_ANON_KEY not configured`
+  - This comes from the CLI gateway, not the local CLI install.
+  - The deployed gateway is missing its `SUPABASE_ANON_KEY` secret, so `/cli/tools/*` cannot proxy to Supabase Edge Functions.
+  - Fix on the server side with `wrangler secret put SUPABASE_ANON_KEY --env <staging|production>` for the gateway Worker, then re-run a `socialseal tools call ...` smoke test.
+- `AI_UNSUPPORTED_LOCATION` or `The live agent is unavailable in this region right now.`
+  - This is raised when the upstream Gemini API rejects the worker egress location.
+  - The agent worker currently uses Google Gemini directly from Cloudflare Workers; there is no SocialSeal-side region allowlist in the CLI.
+  - If this reproduces from a supported Google AI region, treat it as an infrastructure/runtime issue. Practical workarounds are to run the agent from a worker placement/egress region that Google accepts, or switch the agent runtime to Vertex AI for server-side calls.
 
 ## Smoke Test (manual)
 1. `SOCIALSEAL_API_KEY=... socialseal agent run --message "ping"`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socialseal/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "SocialSeal CLI (non-interactive)",

package/src/index.js

@@ -11,7 +11,9 @@ const DEFAULT_API_BASE = 'https://api.socialseal.co';
 const CLI_KEY_HEADER = 'X-CLI-Key';
 const WORKSPACE_HEADER = 'X-Workspace-Id';
 const DEFAULT_TIMEOUT_MS = 30000;
-const MAX_TIMEOUT_MS = 300000;
+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 EXIT_CODES = {
   OK: 0,
@@ -22,10 +24,47 @@ const EXIT_CODES = {
   SERVER: 5,
 };
 const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
-const KNOWN_TOOLS = [];
+const KNOWN_TOOLS = [
+  { name: 'agent-tool-jobs', category: 'agent', description: 'Poll queued agent-backed tool jobs and fetch their results.' },
+  { 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: '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: '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: '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.' },
+  { name: 'vnext-blueprints-create', category: 'vnext', description: 'Create a vNext blueprint from grounded evidence.' },
+  { name: 'vnext-blueprints-generate', category: 'vnext', description: 'Generate a vNext blueprint from workspace opportunity data.' },
+  { name: 'vnext-blueprints-read', category: 'vnext', description: 'Read vNext blueprint history and specific versions.' },
+  { name: 'vnext-briefs-create', category: 'vnext', description: 'Create a vNext brief record.' },
+  { name: 'vnext-briefs-generate', category: 'vnext', description: 'Generate a vNext brief from a blueprint or opportunity.' },
+  { name: 'vnext-briefs-read', category: 'vnext', description: 'Read generated vNext briefs and version history.' },
+  { name: 'vnext-intents', category: 'vnext', description: 'List, create, update, or delete vNext intents.' },
+  { name: 'vnext-journeys', category: 'vnext', description: 'List journey runs and inspect their latest outputs.' },
+  { name: 'vnext-keywords', category: 'vnext', description: 'List, create, update, or delete vNext keywords.' },
+  { name: 'vnext-personas', category: 'vnext', description: 'List, create, update, retire, or reactivate vNext personas.' },
+  { name: 'vnext-pillars', category: 'vnext', description: 'List, create, update, or delete vNext content pillars.' },
+  { name: 'vnext-topics', category: 'vnext', description: 'Manage topics, assignments, queues, and topic suggestions.' },
+  { 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');
@@ -36,6 +75,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;
 }
@@ -52,6 +100,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);
@@ -76,12 +137,11 @@ function normalizeMethod(method) {
   return normalized;
 }
 
-function resolveTimeoutMs(opts, config) {
-  const raw = opts.timeout ?? process.env.SOCIALSEAL_TIMEOUT_MS ?? config.timeoutMs;
-  if (raw == null || raw === '') return DEFAULT_TIMEOUT_MS;
+function parseTimeoutMs(raw, { defaultValue = DEFAULT_TIMEOUT_MS, label = 'timeout' } = {}) {
+  if (raw == null || raw === '') return defaultValue;
   const parsed = Number(raw);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError('Invalid timeout value. Use a positive number of milliseconds.', {
+    throw new CliError(`Invalid ${label} value. Use a positive number of milliseconds.`, {
       code: 'INVALID_TIMEOUT',
       exitCode: EXIT_CODES.USAGE,
     });
@@ -89,6 +149,31 @@ function resolveTimeoutMs(opts, config) {
   return Math.min(parsed, MAX_TIMEOUT_MS);
 }
 
+function resolveTimeoutMs(opts, config) {
+  const raw = opts.timeout ?? process.env.SOCIALSEAL_TIMEOUT_MS ?? config.timeoutMs;
+  return parseTimeoutMs(raw, { defaultValue: DEFAULT_TIMEOUT_MS, label: 'timeout' });
+}
+
+function resolveAgentIdleTimeoutMs(opts, config, fallbackTimeoutMs) {
+  const explicitIdleTimeout =
+    opts.idleTimeout
+    ?? process.env.SOCIALSEAL_AGENT_IDLE_TIMEOUT_MS
+    ?? config.agentIdleTimeoutMs;
+  if (explicitIdleTimeout != null && explicitIdleTimeout !== '') {
+    return parseTimeoutMs(explicitIdleTimeout, {
+      defaultValue: DEFAULT_AGENT_IDLE_TIMEOUT_MS,
+      label: 'idle timeout',
+    });
+  }
+
+  const explicitTimeout = opts.timeout ?? process.env.SOCIALSEAL_TIMEOUT_MS ?? config.timeoutMs;
+  if (explicitTimeout != null && explicitTimeout !== '') {
+    return fallbackTimeoutMs;
+  }
+
+  return DEFAULT_AGENT_IDLE_TIMEOUT_MS;
+}
+
 function resolveLegacyUrl(value, label) {
   if (!value) return null;
   if (!LEGACY_ENABLED) {
@@ -101,6 +186,52 @@ function resolveLegacyUrl(value, label) {
   return value;
 }
 
+function emitInfo(opts, message) {
+  if (opts?.verbose) {
+    process.stderr.write(`[socialseal] ${message}\n`);
+  }
+}
+
+function formatCloseReason(reason) {
+  if (reason == null) return '';
+  if (Buffer.isBuffer(reason)) return reason.toString('utf8');
+  if (typeof reason === 'string') return reason;
+  return String(reason);
+}
+
+async function readNodeResponseBody(response, limit = 2000) {
+  if (!response) return null;
+
+  return await new Promise((resolve) => {
+    const chunks = [];
+    let bufferedBytes = 0;
+    let totalBytes = 0;
+    let settled = false;
+
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    response.on('data', (chunk) => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+      totalBytes += buffer.length;
+      if (bufferedBytes >= limit) return;
+
+      const remaining = limit - bufferedBytes;
+      const slice = buffer.subarray(0, remaining);
+      chunks.push(slice);
+      bufferedBytes += slice.length;
+    });
+    response.on('end', () => {
+      const text = chunks.length > 0 ? Buffer.concat(chunks).toString('utf8') : '';
+      finish(totalBytes > limit ? `${text}…` : text);
+    });
+    response.on('error', () => finish(null));
+  });
+}
+
 function parseJsonInput(value, { label = 'payload', allowString = false } = {}) {
   if (!value) return null;
   if (value.startsWith('@')) {
@@ -148,6 +279,150 @@ 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 isJsonObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+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;
@@ -231,7 +506,11 @@ function emitError(err, opts = {}) {
     process.stderr.write(`[socialseal] ${payload.error.hint}\n`);
   }
   if (showDetails && payload.error.details) {
-    process.stderr.write(`[socialseal] Details: ${payload.error.details}\n`);
+    const detailsText =
+      typeof payload.error.details === 'string'
+        ? payload.error.details
+        : JSON.stringify(payload.error.details);
+    process.stderr.write(`[socialseal] Details: ${detailsText}\n`);
   } else if (!showDetails && err.details) {
     process.stderr.write('[socialseal] Use --verbose to see error details.\n');
   }
@@ -329,6 +608,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);
@@ -336,12 +677,34 @@ async function handleAgentRun(opts) {
   const agentUrl = resolveLegacyUrl(resolveAgentUrl(opts, config), 'SOCIALSEAL_AGENT_URL');
   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`
@@ -351,8 +714,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);
 
@@ -361,6 +725,10 @@ 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.', {
@@ -368,6 +736,23 @@ async function handleAgentRun(opts) {
       exitCode: EXIT_CODES.SERVER,
     });
   }
+  emitInfo(
+    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;
@@ -375,10 +760,36 @@ async function handleAgentRun(opts) {
   await new Promise((resolve, reject) => {
     const ws = new WebSocket(wsUrl);
     let finished = false;
+    let settled = false;
     let inactivityTimer = null;
+    let sawAssistantChunk = false;
+    let sawToolCall = false;
+    let sawThinking = false;
+    let lastMessageType = 'none';
+    let activeConversationId = initialConversationId;
+    const toolProgressStatus = new Map();
+
+    const settleResolve = () => {
+      if (settled) return;
+      settled = true;
+      if (inactivityTimer) clearTimeout(inactivityTimer);
+      resolve();
+    };
+
+    const settleReject = (error) => {
+      if (settled) return;
+      settled = true;
+      if (inactivityTimer) clearTimeout(inactivityTimer);
+      try {
+        ws.terminate();
+      } catch {
+        // ignore
+      }
+      reject(error);
+    };
 
     const resetInactivity = () => {
-      if (!timeoutMs) return;
+      if (!idleTimeoutMs) return;
       if (inactivityTimer) clearTimeout(inactivityTimer);
       inactivityTimer = setTimeout(() => {
         try {
@@ -386,38 +797,74 @@ async function handleAgentRun(opts) {
         } catch {
           // ignore
         }
-        reject(new CliError('WebSocket timed out waiting for agent response.', {
+        settleReject(new CliError('WebSocket timed out waiting for agent response.', {
           code: 'WEBSOCKET_TIMEOUT',
           exitCode: EXIT_CODES.SERVER,
-          hint: 'Increase the timeout with --timeout <ms>.',
+          hint: 'Increase the timeout with --idle-timeout <ms> or --timeout <ms>.',
+          details: truncateDetails({
+            sessionId,
+            activeConversationId,
+            lastMessageType,
+            sawAssistantChunk,
+            sawToolCall,
+            sawThinking,
+            idleTimeoutMs,
+          }),
         }));
-      }, timeoutMs);
+      }, idleTimeoutMs);
     };
 
     ws.on('open', () => {
       resetInactivity();
+      emitInfo(opts, 'Connected to agent WebSocket.');
       const payload = {
         type: 'user_message',
         payload: { content: message, context: context || undefined },
         timestamp: Date.now(),
       };
       ws.send(JSON.stringify(payload));
+      emitInfo(opts, 'User message sent to agent.');
     });
 
     ws.on('message', (data) => {
       try {
         resetInactivity();
         const msg = JSON.parse(data.toString());
+        lastMessageType = msg.type || 'unknown';
+
+        if (msg.type === 'session_state' && msg.payload?.activeConversationId) {
+          activeConversationId = msg.payload.activeConversationId;
+          emitInfo(
+            opts,
+            `Session state received${sessionId ? ` for session ${sessionId}` : ''}${activeConversationId ? ` (conversation ${activeConversationId})` : ''}.`,
+          );
+        }
+
         if (opts.json) {
           process.stdout.write(JSON.stringify(msg) + '\n');
           if (msg.type === 'assistant_chunk' && msg.payload?.done) {
             finished = true;
             ws.close(1000, 'done');
           }
+          if (msg.type === 'error') {
+            const payload = msg.payload || {};
+            settleReject(new CliError(`Agent error: ${payload.message || 'unknown'}`, {
+              code: payload.code || 'AGENT_ERROR',
+              exitCode: EXIT_CODES.SERVER,
+              hint: payload.retryable ? 'Retry the request or inspect backend status.' : null,
+              details: truncateDetails({
+                ...payload,
+                sessionId,
+                activeConversationId,
+                lastMessageType,
+              }),
+            }));
+          }
           return;
         }
         if (msg.type === 'assistant_chunk') {
           const chunk = msg.payload?.chunk ?? '';
+          sawAssistantChunk = sawAssistantChunk || chunk.length > 0 || !!msg.payload?.done;
           if (chunk) process.stdout.write(chunk);
           if (msg.payload?.done) {
             finished = true;
@@ -425,28 +872,114 @@ async function handleAgentRun(opts) {
             ws.close(1000, 'done');
           }
         } else if (msg.type === 'error') {
-          process.stderr.write(`\n[socialseal] Agent error: ${msg.payload?.message || 'unknown'}\n`);
+          const payload = msg.payload || {};
+          settleReject(new CliError(`Agent error: ${payload.message || 'unknown'}`, {
+            code: payload.code || 'AGENT_ERROR',
+            exitCode: EXIT_CODES.SERVER,
+            hint: payload.retryable ? 'Retry the request or inspect backend status.' : null,
+            details: truncateDetails({
+              ...payload,
+              sessionId,
+              activeConversationId,
+              lastMessageType,
+            }),
+          }));
+        } else if (msg.type === 'thinking_chunk') {
+          sawThinking = true;
+          emitInfo(opts, 'Agent is thinking.');
+        } else if (msg.type === 'assistant_status') {
+          const code = msg.payload?.code || 'unknown';
+          const statusMessage = msg.payload?.message || 'Agent reported a status update.';
+          emitInfo(opts, `Agent status [${code}]: ${statusMessage}`);
+        } else if (msg.type === 'tool_call_start') {
+          sawToolCall = true;
+          emitInfo(opts, `Tool start: ${msg.payload?.name || 'unknown'}`);
+        } else if (msg.type === 'tool_call_progress') {
+          const toolCallId = msg.payload?.toolCallId || '';
+          const progressStatus = msg.payload?.status || 'running';
+          if (toolProgressStatus.get(toolCallId) !== progressStatus) {
+            toolProgressStatus.set(toolCallId, progressStatus);
+            emitInfo(opts, `Tool progress: ${progressStatus}`);
+          }
+        } else if (msg.type === 'tool_call_complete') {
+          const error = msg.payload?.error;
+          const duration = typeof msg.payload?.duration_ms === 'number'
+            ? `${msg.payload.duration_ms}ms`
+            : 'unknown duration';
+          if (error) {
+            emitInfo(opts, `Tool failed after ${duration}: ${error}`);
+          } else {
+            emitInfo(opts, `Tool completed in ${duration}.`);
+          }
         }
       } catch (err) {
-        process.stderr.write(`\n[socialseal] Failed to parse agent message: ${err.message || err}\n`);
+        settleReject(new CliError(`Failed to parse agent message: ${err.message || err}`, {
+          code: 'INVALID_AGENT_MESSAGE',
+          exitCode: EXIT_CODES.SERVER,
+          details: data.toString(),
+        }));
       }
     });
 
-    ws.on('close', () => {
-      if (inactivityTimer) clearTimeout(inactivityTimer);
+    ws.on('unexpected-response', async (_req, response) => {
+      const statusText = response.statusCode
+        ? `${response.statusCode}${response.statusMessage ? ` ${response.statusMessage}` : ''}`
+        : 'unknown';
+      const details = await readNodeResponseBody(response);
+      settleReject(new CliError(`WebSocket upgrade failed: ${statusText}`.trim(), {
+        code: 'WEBSOCKET_UPGRADE_FAILED',
+        exitCode:
+          response.statusCode === 401 || response.statusCode === 403
+            ? EXIT_CODES.AUTH
+            : EXIT_CODES.SERVER,
+        hint:
+          response.statusCode === 401 || response.statusCode === 403
+            ? 'Check your CLI key, workspace scope, and session endpoint auth.'
+            : 'Retry with --verbose to inspect gateway or backend behavior.',
+        details: truncateDetails({
+          sessionId,
+          activeConversationId,
+          responseBody: details,
+        }),
+      }));
+    });
+
+    ws.on('close', (code, reason) => {
+      const closeReason = formatCloseReason(reason);
       if (!finished) {
-        reject(new CliError('WebSocket closed before completion.', {
-          code: 'WEBSOCKET_CLOSED',
-          exitCode: EXIT_CODES.SERVER,
-        }));
+        settleReject(new CliError(
+          `WebSocket closed before completion (code ${code}${closeReason ? `: ${closeReason}` : ''}).`,
+          {
+            code: 'WEBSOCKET_CLOSED',
+            exitCode: EXIT_CODES.SERVER,
+            hint: sawAssistantChunk
+              ? 'The agent disconnected mid-response. Retry the request.'
+              : 'The agent closed the connection before completing. Retry with --verbose for more diagnostics.',
+            details: truncateDetails({
+              sessionId,
+              activeConversationId,
+              lastMessageType,
+              sawAssistantChunk,
+              sawToolCall,
+              sawThinking,
+            }),
+          },
+        ));
       } else {
-        resolve();
+        settleResolve();
       }
     });
 
     ws.on('error', (err) => {
-      if (inactivityTimer) clearTimeout(inactivityTimer);
-      reject(err);
+      settleReject(new CliError(`WebSocket error: ${err.message || err}`, {
+        code: 'WEBSOCKET_ERROR',
+        exitCode: EXIT_CODES.SERVER,
+        details: truncateDetails({
+          sessionId,
+          activeConversationId,
+          lastMessageType,
+        }),
+      }));
     });
   });
 }
@@ -458,16 +991,19 @@ 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 } = resolveWorkspaceSelection(opts, config);
 
-  const payload = parseJsonInput(opts.body, { label: 'body' }) ?? {};
+  const parsedPayload = parseJsonInput(opts.body, { label: 'body' }) ?? {};
+  const mergedPayload = mergeWorkspaceIdIntoPayload(parsedPayload, resolvedWorkspaceId);
   const method = normalizeMethod(opts.method);
+  const payload = applySearchJourneyRunAsyncStart(mergedPayload, { ...opts, method });
   const res = await callApi({
     apiBase: useGateway ? resolvedApiBase : legacyUrl,
     apiKey,
     path: useGateway ? `/cli/tools/${opts.function}` : `/functions/v1/${opts.function}`,
     method,
     body: payload,
-    workspaceId: opts.workspaceId,
+    workspaceId: resolvedWorkspaceId,
     timeoutMs,
   });
 
@@ -482,7 +1018,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;
   }
 
@@ -492,8 +1066,9 @@ async function handleToolsCall(opts) {
 
 function handleToolsList(opts) {
   const payload = {
+    discovery: 'built_in_registry',
     tools: KNOWN_TOOLS,
-    note: 'Tool discovery is disabled in the OSS CLI. Refer to official docs for supported tool names.',
+    note: 'This registry is shipped with the CLI for stable discovery. It is not live backend enumeration.',
   };
 
   if (opts.json) {
@@ -501,8 +1076,19 @@ function handleToolsList(opts) {
     return;
   }
 
-  process.stdout.write('[socialseal] Tool discovery is disabled in the OSS CLI.\n');
+  process.stdout.write('[socialseal] Built-in tool registry\n');
   process.stdout.write(`[socialseal] ${payload.note}\n`);
+
+  let currentCategory = null;
+  for (const tool of KNOWN_TOOLS) {
+    if (tool.category !== currentCategory) {
+      currentCategory = tool.category;
+      process.stdout.write(`\n${currentCategory}\n`);
+    }
+    process.stdout.write(`- ${tool.name}: ${tool.description}\n`);
+  }
+
+  process.stdout.write('\n[socialseal] Call a tool with: socialseal tools call --function <name> --body @payload.json\n');
 }
 
 async function handleDataExportTracking(opts) {
@@ -512,6 +1098,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.', {
@@ -532,7 +1119,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,
   });
 
@@ -540,6 +1127,13 @@ async function handleDataExportTracking(opts) {
     throw await buildHttpError(res, { label: 'Tracking export' });
   }
 
+  if (!res.body) {
+    throw new CliError('Export response contained no body.', {
+      code: 'EMPTY_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+    });
+  }
+
   const outPath = opts.stdout ? null : (opts.out || 'tracking_export.csv');
   if (outPath) {
     await pipeline(res.body, fs.createWriteStream(outPath));
@@ -556,6 +1150,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');
 
@@ -569,7 +1164,7 @@ async function handleDataExportReport(opts) {
       format: opts.format,
       payload,
     },
-    workspaceId: opts.workspaceId,
+    workspaceId: resolvedWorkspaceId,
     timeoutMs,
   });
 
@@ -611,11 +1206,155 @@ 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')
   .description('SocialSeal CLI (non-interactive)')
-  .version('0.1.0');
+  .version('0.1.1');
 
 if (typeof program.showHelpAfterError === 'function') {
   program.showHelpAfterError(true);
@@ -623,7 +1362,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')
@@ -634,18 +1373,63 @@ 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')
   .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--idle-timeout <ms>', 'WebSocket inactivity timeout in milliseconds')
   .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
   .command('list')
-  .description('List tools (discovery disabled in OSS build)')
+  .description('List built-in tool registry entries')
   .option('--json', 'Emit machine-readable output')
   .option('--pretty', 'Pretty-print JSON')
   .option('--verbose', 'Show error details')
@@ -656,6 +1440,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)')