@xuda.io/ai_module 1.1.5610 → 1.1.5612

package/index.mjs

@@ -232,6 +232,7 @@ const email_ms = await import(`${module_path}/email_module/index_ms.mjs`);
 const ws_dashboard_msa = await import(`${module_path}/ws_dashboard_module/index_msa.mjs`);
 const account_msa = await import(`${module_path}/account_module/index_msa.mjs`);
 const drive_msa = await import(`${module_path}/drive_module/index_msa.mjs`);
+const misc_msa = await import(`${module_path}/misc_module/index_msa.mjs`);
 
 var open_ai_status = {};
 const report_ai_status = function (model, err) {
@@ -2150,7 +2151,7 @@ const get_studio_doc = async function (req) {
 };
 
 export const get_ai_agent_info = async function (uid, job_id, headers, doc, from_marketplace) {
-  const account_profile_info = await get_active_account_profile_info(uid);
+  const account_profile_info = await get_active_account_profile_info(uid, from_marketplace ? doc?.studio_meta?.account_profiles?.[0] : undefined);
 
   const get_contact_border = function (doc) {
     const disable_color = `#1a3557`;
@@ -2671,6 +2672,10 @@ export const delete_ai_agent = async function (req) {
       agent_doc.ts = Date.now();
       const save_ret = await db_module.save_app_couch_doc_native(account_profile_info.app_id, agent_doc);
 
+      if (agent_doc?.agentConfig?.npm_package_name) {
+        misc_msa.sync_agent_npm_state({ app_id: account_profile_info.app_id, prog_id: agent_id, event: 'deleted' });
+      }
+
       for (const [key, val] of Object.entries(agent_doc?.agentConfig?.agent_tools || [])) {
         const file_id = val?.youtube?.file_id || val?.file?.file_id;
         const vector_store_id = val?.youtube?.vector_store_id || val?.file?.vector_store_id;
@@ -2883,10 +2888,46 @@ export const delete_mini_app = async function (req) {
   }
 };
 
+export const start_cli_agent_conversation = async function (req) {
+  const { uid, agent_id } = req;
+  if (!uid) return { code: -1, data: 'uid required' };
+  if (!agent_id) return { code: -1, data: 'agent_id required' };
+  try {
+    const account_profile_info = await get_active_account_profile_info(uid);
+    const profile_id = account_profile_info.account_profile_id;
+    const conversation_obj = await create_openai_conversation();
+    const conversation_id = await _common.xuda_get_uuid('chat_conversation');
+    const now = Date.now();
+    const doc = {
+      _id: conversation_id,
+      docType: 'chat_conversation',
+      title: 'CLI session',
+      date_created_ts: now,
+      ts: now,
+      stat: 1,
+      uid,
+      messages: [],
+      reference_type: 'ai_agents',
+      reference_id: agent_id,
+      conversation_obj,
+      reference_conversation_id: conversation_obj.id,
+      conversation_type: 'ai_chat',
+      initiator_uid: uid,
+      account_profiles: [profile_id],
+      source: 'cli',
+    };
+    const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, doc);
+    if (save_ret.code < 0) return save_ret;
+    return { code: 1, data: { conversation_id, profile_id, app_id: account_profile_info.app_id } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
 export const update_ai_agent = async function (req, job_id, headers) {
-  let { agent_id, agentConfig, uid } = req;
+  let { agent_id, agentConfig, uid, profile_id } = req;
 
-  const account_profile_info = await get_active_account_profile_info(uid);
+  const account_profile_info = await get_active_account_profile_info(uid, profile_id);
 
   try {
     let agent_doc = await await db_module.get_app_couch_doc_native(account_profile_info.app_id, agent_id);
@@ -3292,11 +3333,11 @@ const save_agent_status = async function (uid, agent_id, stat, agentConfig) {
 };
 
 export const create_ai_agent = async function (req, job_id, headers) {
-  const { agentConfig, uid } = req;
+  const { agentConfig, uid, profile_id } = req;
 
   const { account_project_id: app_id, account_info } = await account_ms.get_default_project_account_doc(uid);
 
-  const account_profile_info = await get_active_account_profile_info(uid);
+  const account_profile_info = await get_active_account_profile_info(uid, profile_id);
   const { account_profile_obj } = account_profile_info;
   try {
     const param = { uid, properties: { menuName: agentConfig.agent_name, menuTitle: agentConfig.agent_name, menuType: 'ai_agent' }, checkedInUserName: account_info.first_name + ' ' + account_info.last_name, app_id: account_profile_info.app_id, parentId: 'ai_agents' };
@@ -3574,7 +3615,7 @@ export const update_thumbnail = async function (type, doc, app_id, uid, job_id,
 
     switch (type) {
       case 'ai_agent': {
-        const images_arr = await create_ai_agent_image({ app_id, uid, ai_agent_id: doc._id, tags }, job_id, headers);
+        const images_arr = await create_ai_agent_image({ app_id, uid, ai_agent_id: doc._id, tags, account_profile_info }, job_id, headers);
         db_doc = await get_db_doc();
         db_doc.studio_meta.thumbnail_request_ts = Date.now();
         db_doc.studio_meta.agent_image = [images_arr.data];
@@ -5113,8 +5154,99 @@ ${conversation_history || `User (studio): ${prompt}`}
   }
 };
 
+// Clarifying-questions protocol shared by the vibe/codex path AND the dashboard
+// CPI agent path. Both emit plain prose by default, so to get a structured
+// "ask the user" payload (Claude-Code-style options stepper) we instruct them
+// to emit a JSON block at the end of the response when they would otherwise
+// ask follow-up questions in prose. The block is parsed off, prose is shipped
+// as the normal text, and the structured questions ride alongside on the
+// stream_end event + the persisted chat_conversation_item.
+const CLARIFYING_QUESTIONS_INSTRUCTION = `
+If you need clarifying input from the user before proceeding, do NOT ask in prose. Instead, emit a structured questions block at the END of your response:
+
+<xuda-questions>
+[
+  {
+    "question": "<full question text>",
+    "options": [
+      { "label": "<short option label>", "description": "<one-sentence explanation of what this option means>" },
+      { "label": "<short option label>", "description": "<one-sentence explanation of what this option means>" },
+      { "label": "<short option label>", "description": "<one-sentence explanation of what this option means>" }
+    ]
+  }
+]
+</xuda-questions>
+
+Rules:
+- 2 to 3 options per question. The UI automatically adds an "Other (tell me what you meant)" free-text option, so do NOT include it yourself.
+- You may include multiple questions in the array; the UI will step through them one at a time.
+- Put the block at the very end, after any explanatory prose. The prose before the block will be shown to the user as your message.
+- If you do not need clarification, do not emit the block. Only emit it when answering is genuinely blocked on missing information.
+`.trim();
+
+const extract_xuda_questions = function (text) {
+  if (typeof text !== 'string') return { prose: text, questions: null };
+  const match = text.match(/<xuda-questions>\s*([\s\S]+?)\s*<\/xuda-questions>\s*$/);
+  if (!match) return { prose: text, questions: null };
+  let parsed;
+  try {
+    parsed = JSON.parse(match[1]);
+  } catch (e) {
+    return { prose: text, questions: null };
+  }
+  if (!Array.isArray(parsed) || !parsed.length) return { prose: text, questions: null };
+  const validated = parsed
+    .map((q) => {
+      if (!q || typeof q.question !== 'string') return null;
+      const options = Array.isArray(q.options)
+        ? q.options
+            .map((opt) => (opt && typeof opt.label === 'string' ? { label: opt.label.trim(), description: typeof opt.description === 'string' ? opt.description.trim() : '' } : null))
+            .filter(Boolean)
+            .slice(0, 3)
+        : [];
+      if (options.length < 2) return null;
+      return { question: q.question.trim(), options };
+    })
+    .filter(Boolean);
+  if (!validated.length) return { prose: text, questions: null };
+  return {
+    prose: text.slice(0, match.index).trim(),
+    questions: validated,
+  };
+};
+
+// Resolve the structured context object passed by newer clients (ProjectAiPanel
+// sends { project_id, tab, view, vibe_mode }) or fall back to the legacy string
+// shape that older callsites still send. Returns an object — string-shaped legacy
+// inputs are wrapped as { tab: <string> } so downstream readers have one shape.
+const get_dashboard_context_obj = function (req, conversation_doc) {
+  const candidate = req.context || req.metadata?.context || conversation_doc.context || conversation_doc.metadata?.context;
+  if (candidate && typeof candidate === 'object') return candidate;
+  const legacy_str = (candidate || req.dashboard_context || conversation_doc.dashboard_context || '').toString().trim().toLowerCase();
+  return legacy_str ? { tab: legacy_str } : {};
+};
+
+// Primary routing signal: replaces the legacy `dashboard_context === 'console'`
+// check. Newer clients set `context.vibe_mode = true` when the user is in vibe
+// mode (full-screen VPS preview) — that's the canonical "send this through the
+// codex/console runner" flag. dashboard_context is being deprecated as a
+// routing concept; it remains only as a hint string (context.tab) used by the
+// CPI tools agent for keyword-based tool selection in the non-vibe branch.
+const is_vibe_mode_request = function (req, conversation_doc) {
+  const ctx = get_dashboard_context_obj(req, conversation_doc);
+  if (ctx.vibe_mode === true) return true;
+  // Backwards compat: explicit legacy `context: 'console'` still triggers the
+  // codex path. Remove once no callsites pass the string form.
+  if (ctx.tab === 'console') return true;
+  return false;
+};
+
 const get_dashboard_chat_context = function (req, conversation_doc) {
-  return (req.context || req.dashboard_context || req.metadata?.context || conversation_doc.context || conversation_doc.dashboard_context || conversation_doc.metadata?.context || '').toString().trim().toLowerCase();
+  const ctx = get_dashboard_context_obj(req, conversation_doc);
+  // The legacy "dashboard_context" string was an ad-hoc tab identifier; the new
+  // object's `tab` field is the same concept. Returning '' here lets the CPI
+  // tools agent still do prompt-only keyword matching.
+  return (ctx.tab || '').toString().trim().toLowerCase();
 };
 
 const get_dashboard_cpi_keywords = function (context, prompt = '') {
@@ -5277,6 +5409,7 @@ const dashboard_chat = async function (req, job_id, headers) {
 
   const conversation_id = conversation_doc._id;
   const dashboard_context = get_dashboard_chat_context(req, conversation_doc);
+  const vibe_mode = is_vibe_mode_request(req, conversation_doc);
   const target_app_id = (await _common.get_project_app_id(req.app_id || conversation_doc.reference_id || account_profile_info.app_id, true)) || account_profile_info.app_id;
   const prompt_conversation_item_id = await _common.xuda_get_uuid('chat_conversation_item');
   const response_conversation_item_id = await _common.xuda_get_uuid('chat_conversation_item');
@@ -5304,7 +5437,19 @@ const dashboard_chat = async function (req, job_id, headers) {
           ? {
               stream_id: response_conversation_item_id,
               final_seq: stream_delta_seq,
-              text: stream_delta_text,
+              // params.text override exists for the clarifying-questions flow:
+              // when the agent embedded an <xuda-questions> block in its
+              // streamed output, the live stream_delta events already
+              // shipped the block to the client. The caller passes the
+              // cleaned prose here so handleStreamEnd can reconcile the
+              // visible bubble against the block-free version (uses the
+              // existing missed-deltas reconciliation path on the client).
+              text: typeof params?.text === 'string' ? params.text : stream_delta_text,
+              // Structured clarifying-questions payload — when the agent
+              // emits an <xuda-questions> block, we parse it, strip it
+              // from the prose, and ship it here so the client can render
+              // the stepper artifact alongside the message.
+              ...(params?.questions ? { questions: params.questions } : {}),
             }
           : {}),
         prompt_conversation_item_id,
@@ -5418,7 +5563,7 @@ ${conversation_history || `User (dashboard): ${prompt}`}
 
   try {
     emitToDashboard('stream_start');
-    emitToDashboard('stream_phase', dashboard_context === 'console' ? 'Starting console request' : 'Starting dashboard request');
+    emitToDashboard('stream_phase', vibe_mode ? 'Starting vibe request' : 'Starting dashboard request');
 
     await saveUserItem();
 
@@ -5432,19 +5577,68 @@ ${conversation_history || `User (dashboard): ${prompt}`}
     conversation_doc.stat = 2;
     conversation_doc.request_started_at = request_started_at;
     conversation_doc.job_id = job_id;
-    conversation_doc.context = dashboard_context;
+    // Persist the structured context (object shape) so multi-turn requests
+    // inherit vibe_mode even when the client doesn't resend it. The legacy
+    // string-form `context = dashboard_context` is dropped — vibe_mode is now
+    // the routing signal and `tab` lives inside the object.
+    conversation_doc.context = { ...get_dashboard_context_obj(req, conversation_doc), vibe_mode };
     conversation_doc.target_app_id = target_app_id;
     await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
 
-    if (dashboard_context === 'console') {
-      const codex_ret = await execute_codex_request({ ...req, conversation_id, conversation_doc, prompt, attachments, stream: false }, job_id, headers);
+    if (vibe_mode) {
+      // Resolve the project's VPS IP — codex SSHes into that host to run
+      // commands. Without this, execute_codex_request was pulling `ip` from
+      // `req.ip` (the user's browser IP), which never matches a real VPS
+      // and either fails the SSH or hangs codex against an unreachable host.
+      let vibe_app_obj = null;
+      try {
+        vibe_app_obj = await get_app_obj(target_app_id);
+      } catch (e) {
+        // get_app_obj throws on missing doc — treat as "no project found"
+        // and fall through to the missing-VPS error path below.
+      }
+      const vps_ip = vibe_app_obj?.app_hosting_server?.ip;
+      const project_name = vibe_app_obj?.menuName || vibe_app_obj?.app_name || vibe_app_obj?.name || '';
+
+      if (!vps_ip) {
+        // No deployed VPS for this project — surface a clear, actionable
+        // message instead of letting codex fail silently or SSH to the user.
+        const missing_vps_msg = `This project does not have a deployed VPS yet, so I can't run vibe-mode commands. Open the project's Instances tab and deploy a VPS first, then try again.`;
+        emitToDashboard('response_start');
+        streamText(missing_vps_msg);
+        emitToDashboard('stream_end');
+        conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
+        conversation_doc.ts = Date.now();
+        conversation_doc.stat = 3;
+        conversation_doc.process_stat = 'partial';
+        await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+        return await saveAssistantItem(missing_vps_msg, { vibe_missing_vps: true });
+      }
+
+      // System block: questions protocol + project/VPS context so codex's
+      // response doesn't drift to a generic answer. Codex sees one prompt
+      // string; the [System]/[User request] framing keeps the boundary
+      // visible to it.
+      const project_context_block = `You are operating in vibe mode for Xuda project "${project_name || target_app_id}" (app_id: ${target_app_id}).\nThe deployed VPS for this project is at ${vps_ip}; all shell commands run there over SSH.\nWhen the user asks you to build, change, or inspect something on "this VPS", that means ${vps_ip}.`;
+      const codex_prompt = `[System]\n${project_context_block}\n\n${CLARIFYING_QUESTIONS_INSTRUCTION}\n\n[User request]\n${prompt}`;
+
+      // Override ip explicitly so the `...req` spread can't smuggle in
+      // req.ip (browser IP). conversation_id / conversation_doc / prompt /
+      // attachments / stream stay after the spread for the same reason.
+      const codex_ret = await execute_codex_request({ ...req, ip: vps_ip, conversation_id, conversation_doc, prompt: codex_prompt, attachments, stream: false }, job_id, headers);
       const codex_events = codex_ret?.data?.events || [];
       const last_message = [...codex_events].reverse().find((event) => event?.item?.type === 'agent_message' && event.item.text)?.item?.text;
-      const response_text = codex_ret.code < 0 ? `Console request failed: ${get_error_message(codex_ret.data, 'Codex request failed')}` : last_message || 'Console request completed.';
+      const raw_response_text = codex_ret.code < 0 ? `Vibe request failed: ${get_error_message(codex_ret.data, 'Codex request failed')}` : last_message || 'Vibe request completed.';
+
+      // Pull the structured questions block (if any) off the tail of the
+      // response. response_text is just the prose; questions ride alongside
+      // on the stream_end event + the persisted assistant item.
+      const { prose, questions } = extract_xuda_questions(raw_response_text);
+      const response_text = prose || raw_response_text;
 
       emitToDashboard('response_start');
       streamText(response_text);
-      emitToDashboard('stream_end');
+      emitToDashboard('stream_end', undefined, questions ? { questions } : undefined);
 
       conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
       conversation_doc.ts = Date.now();
@@ -5452,7 +5646,7 @@ ${conversation_history || `User (dashboard): ${prompt}`}
       conversation_doc.process_stat = codex_ret.code < 0 ? 'partial' : 'full';
       await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
 
-      return await saveAssistantItem(response_text, { codex_result: codex_ret });
+      return await saveAssistantItem(response_text, { codex_result: codex_ret, ...(questions ? { questions } : {}) });
     }
 
     const dashboard_prompt = await getDashboardContextPrompt();
@@ -5476,6 +5670,8 @@ If the screenshot or prompt implies the tab/context, infer the relevant dashboar
 For data/database requests, use the database/table CPI methods and keep app_id/reference_id anchored to "${target_app_id}".
 Summarize the action and important CPI result fields clearly. Do not invent successful changes; report tool errors as errors.
 Available CPI methods: ${cpi_tools_ret.selected_methods.join(', ')}
+
+${CLARIFYING_QUESTIONS_INSTRUCTION}
 `.trim(),
       model: ai_model,
       tools: cpi_tools_ret.tools,
@@ -5506,7 +5702,16 @@ Available CPI methods: ${cpi_tools_ret.selected_methods.join(', ')}
     }
 
     response_text = response_text || output?.state?._currentStep?.output || output?.finalOutput || output?.output || 'Dashboard request completed.';
-    emitToDashboard('stream_end');
+
+    // Pull off the structured clarifying-questions block (if the agent emitted
+    // one) before persistence + stream_end. The block was streamed live to the
+    // client during stream_delta, so the client's handleStreamEnd will use the
+    // `text` field on stream_end to overwrite the visible bubble with the
+    // cleaned prose (see AiChat.vue handleStreamEnd reconciliation).
+    const { prose: dashboard_prose, questions: dashboard_questions } = extract_xuda_questions(response_text);
+    const final_response_text = dashboard_prose || response_text;
+
+    emitToDashboard('stream_end', undefined, dashboard_questions ? { questions: dashboard_questions, text: final_response_text } : undefined);
 
     conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
     conversation_doc.ts = Date.now();
@@ -5514,9 +5719,10 @@ Available CPI methods: ${cpi_tools_ret.selected_methods.join(', ')}
     conversation_doc.process_stat = 'full';
     await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
 
-    return await saveAssistantItem(response_text, {
+    return await saveAssistantItem(final_response_text, {
       cpi_methods: cpi_tools_ret.selected_methods,
       ai_agent_id: 'dashboard_cpi_agent',
+      ...(dashboard_questions ? { questions: dashboard_questions } : {}),
     });
   } catch (err) {
     const error_message = get_error_message(err, 'dashboard request failed');
@@ -5540,9 +5746,337 @@ const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_t
   let tool_resources = {};
   let eligible_agent = true;
 
+  const add_internal_codex_tool = function ({ name, description, system_prompt }) {
+    if (reference_type !== 'ai_agents' && !prompt_suggestion_activated && !chat_suggestion_activated) {
+      eligible_agent = false;
+      return;
+    }
+
+    tools.push(
+      tool({
+        name: name.substring(0, 60),
+        description,
+        parameters: z.object({
+          question: z.string().describe('The support question to investigate.'),
+        }),
+        async execute(e) {
+          const question = String(e?.question || '').trim();
+          if (!question) {
+            return 'question is required';
+          }
+
+          const dev_host = _conf?.internal_ai_agents?.dev_server_host || 'dev.xuda.ai';
+          const codex_ret = await execute_codex_request(
+            {
+              ip: dev_host,
+              uid,
+              account_profile_info,
+              job_id,
+              stream: false,
+              prompt: `${system_prompt}
+
+User question:
+${question}
+
+Return a concise answer. Include only non-sensitive findings and mention when the requested information is outside the allowed scope.`,
+            },
+            job_id,
+            headers,
+          );
+
+          if (codex_ret.code < 0) {
+            return `Codex readonly lookup failed: ${get_error_message(codex_ret.data, 'unknown error')}`;
+          }
+
+          const events = codex_ret?.data?.events || [];
+          const final_message = [...events].reverse().find((event) => event?.item?.type === 'agent_message' && event.item.text)?.item?.text;
+          return final_message || 'Codex readonly lookup completed without a final answer.';
+        },
+      }),
+    );
+  };
+
+  const add_xuda_public_website_tool = function ({ name, description }) {
+    if (reference_type !== 'ai_agents' && !prompt_suggestion_activated && !chat_suggestion_activated) {
+      eligible_agent = false;
+      return;
+    }
+
+    const website_origin = _conf?.internal_ai_agents?.public_website_url || 'https://xuda.ai';
+    const dump_dir = path.join(os.tmpdir(), 'xuda_public_website_dump', new URL(website_origin).hostname.replace(/[^a-z0-9.-]/gi, '_'));
+    const manifest_path = path.join(dump_dir, 'manifest.json');
+    const ttl_ms = Number(_conf?.internal_ai_agents?.public_website_dump_ttl_ms || 10 * 60 * 1000);
+    const cache_version = 2;
+    const website_base = website_origin.replace(/\/$/, '');
+
+    const decode_html = function (value = '') {
+      return String(value)
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/g, "'");
+    };
+
+    const strip_html = function (html = '') {
+      return decode_html(
+        String(html)
+          .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+          .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+          .replace(/<noscript[\s\S]*?<\/noscript>/gi, ' ')
+          .replace(/<svg[\s\S]*?<\/svg>/gi, ' ')
+          .replace(/<[^>]+>/g, ' ')
+          .replace(/\s+/g, ' ')
+          .trim(),
+      );
+    };
+
+    const extract_title = function (html = '') {
+      const match = String(html).match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+      return match ? decode_html(match[1]).replace(/\s+/g, ' ').trim() : '';
+    };
+
+    const get_terms = function (question) {
+      const terms = String(question)
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .split(/\s+/)
+        .filter((term) => term.length > 2 && !['the', 'and', 'for', 'about', 'tell', 'with', 'from', 'what', 'who', 'how', 'xuda'].includes(term));
+      if (/\baddress|where|location|located|office|contact\b/i.test(question)) {
+        terms.push('address', 'contact', 'llc', 'boca', 'raton', 'florida');
+      }
+      return [...new Set(terms)];
+    };
+
+    const score_page = function (page, terms, question) {
+      const haystack = `${page.url} ${page.title} ${page.text}`.toLowerCase();
+      let score = 0;
+      for (const term of terms) {
+        if (haystack.includes(term)) score += term.length > 4 ? 3 : 1;
+      }
+      if (/\b(company|about|xuda)\b/i.test(question) && new URL(page.url).pathname === '/') score += 20;
+      if (/\bdocs?|guide|how|cli|dashboard|deploy|agent|app|vps|database|couchdb\b/i.test(question) && page.url.includes('/docs')) score += 8;
+      if (/\bnetwork|ambassador|mentor|city|region\b/i.test(question) && page.url.includes('network')) score += 8;
+      if (/\baddress|where|location|located|office|contact\b/i.test(question) && /\/legal\/privacy-policy/i.test(page.url)) score += 100;
+      if (/\baddress|where|location|located|office|contact\b/i.test(question) && /\/legal\/terms|contact/i.test(page.url)) score += 30;
+      return score;
+    };
+
+    const make_snippet = function (text = '', terms = [], max_length = 3000) {
+      const lower = text.toLowerCase();
+      const anchors = ['address', 'contact us', 'xuda llc', 'boca raton', 'florida', ...terms];
+      let index = -1;
+      for (const anchor of anchors) {
+        index = lower.indexOf(String(anchor).toLowerCase());
+        if (index > -1) break;
+      }
+      if (index < 0) return text.slice(0, max_length);
+      const start = Math.max(0, index - Math.floor(max_length / 3));
+      const end = Math.min(text.length, start + max_length);
+      return `${start > 0 ? '...' : ''}${text.slice(start, end)}${end < text.length ? '...' : ''}`;
+    };
+
+    const extract_public_facts = function (page, question) {
+      const facts = [];
+      if (/\baddress|where|location|located|office|contact\b/i.test(question)) {
+        const address_match = String(page.text || '').match(/Address:\s*([^|]+?)(?=\s+By using|\s+Privacy Policy|\s+Terms|\s*$)/i);
+        if (address_match?.[1]) {
+          facts.push({
+            label: 'Address',
+            value: address_match[1].replace(/\s+/g, ' ').trim(),
+            url: page.url,
+          });
+        }
+      }
+      return facts;
+    };
+
+    const fetch_text = async function (url, timeout_ms = 8000) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout_ms);
+      try {
+        const res = await fetch(url, {
+          signal: controller.signal,
+          headers: { 'User-Agent': 'Xuda Ambassador Support Readonly Website Indexer' },
+        });
+        if (!res.ok) throw new Error(`${url} returned ${res.status}`);
+        return await res.text();
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+
+    const load_dump = async function () {
+      try {
+        const manifest = JSON.parse(await fs.promises.readFile(manifest_path, 'utf8'));
+        if (Number(manifest.cache_version || 0) === cache_version && Date.now() - Number(manifest.created_ts || 0) < ttl_ms && Array.isArray(manifest.pages) && manifest.pages.length) {
+          const pages = [];
+          for (const page of manifest.pages) {
+            try {
+              pages.push(JSON.parse(await fs.promises.readFile(path.join(dump_dir, page.file), 'utf8')));
+            } catch (_) {
+              /* ignore corrupt cache item */
+            }
+          }
+          if (pages.length) return { pages, from_cache: true };
+        }
+      } catch (_) {
+        /* build cache below */
+      }
+
+      await fs.promises.mkdir(dump_dir, { recursive: true });
+      const sitemap_xml = await fetch_text(`${website_base}/sitemap.xml`, 8000);
+      const priority_urls = [
+        `${website_base}/`,
+        `${website_base}/about`,
+        `${website_base}/legal/privacy-policy`,
+        `${website_base}/legal/terms`,
+        `${website_base}/contact`,
+      ];
+      const sitemap_urls = [...sitemap_xml.matchAll(/<loc>([\s\S]*?)<\/loc>/gi)]
+        .map((match) => decode_html(match[1]).trim())
+        .filter((url) => {
+          try {
+            const parsed = new URL(url);
+            return parsed.origin === website_base && !/\.(png|jpe?g|gif|webp|svg|pdf|zip)$/i.test(parsed.pathname);
+          } catch (_) {
+            return false;
+          }
+        })
+        .slice(0, 120);
+      const urls = [...new Set([...priority_urls, ...sitemap_urls])];
+
+      const pages = [];
+      for (const url of urls) {
+        try {
+          const html = await fetch_text(url, 8000);
+          const page = {
+            url,
+            title: extract_title(html),
+            text: strip_html(html).slice(0, 80000),
+            fetched_ts: Date.now(),
+          };
+          if (page.text.length < 80) continue;
+          const file = `${crypto.createHash('sha1').update(url).digest('hex')}.json`;
+          await fs.promises.writeFile(path.join(dump_dir, file), JSON.stringify(page, null, 2));
+          pages.push({ ...page, file });
+        } catch (err) {
+          pages.push({ url, title: '', text: `Fetch failed: ${err.message || String(err)}`, fetch_error: true });
+        }
+      }
+
+      await fs.promises.writeFile(
+        manifest_path,
+        JSON.stringify(
+          {
+            source: website_origin,
+            cache_version,
+            created_ts: Date.now(),
+            pages: pages.filter((page) => !page.fetch_error).map((page) => ({ url: page.url, file: page.file, title: page.title })),
+          },
+          null,
+          2,
+        ),
+      );
+      return { pages, from_cache: false };
+    };
+
+    tools.push(
+      tool({
+        name: (name || 'Xuda Ambassador Public Website Readonly').substring(0, 60),
+        description: description || 'Readonly lookup against public xuda.ai website pages for ambassador support answers.',
+        parameters: z.object({
+          question: z.string().describe('The support question to answer from public xuda.ai website pages.'),
+        }),
+        async execute(e) {
+          const question = String(e?.question || '').trim();
+          if (!question) {
+            return 'question is required';
+          }
+
+          const run_lookup = async function () {
+            const { pages } = await load_dump();
+            const terms = get_terms(question);
+            const ranked = pages
+              .filter((page) => !page.fetch_error)
+              .map((page) => ({ page, score: score_page(page, terms, question) }))
+              .filter((item) => item.score > 0)
+              .sort((a, b) => b.score - a.score)
+              .slice(0, 5)
+              .map((item) => ({
+                score: item.score,
+                url: item.page.url,
+                title: item.page.title,
+                snippet: make_snippet(item.page.text, terms),
+              }));
+            const facts = pages
+              .filter((page) => !page.fetch_error)
+              .flatMap((page) => extract_public_facts(page, question))
+              .slice(0, 5);
+
+            return {
+              source: website_origin,
+              readonly: true,
+              question,
+              facts,
+              result_count: ranked.length,
+              results: ranked,
+              instruction: ranked.length
+                ? 'Answer only from these public xuda.ai website facts and snippets. If facts are present, use them as the primary source. Cite page URLs inline when useful. Do not mention internal cache, dump folders, or implementation details.'
+                : 'No relevant public xuda.ai pages were found. Say that the public xuda.ai website did not contain enough information and ask for a narrower page or topic. Do not mention internal cache, dump folders, or implementation details.',
+            };
+          };
+
+          try {
+            const data = await Promise.race([
+              run_lookup(),
+              new Promise((_, reject) => setTimeout(() => reject(new Error('xuda.ai website lookup timed out')), 20000)),
+            ]);
+            return JSON.stringify(data, null, 2);
+          } catch (err) {
+            return `xuda.ai website lookup failed: ${err.message || String(err)}`;
+          }
+        },
+      }),
+    );
+  };
+
   for (const [key, val] of Object.entries(ai_agent_doc?.agentConfig?.agent_tools || [])) {
     const { name = '', description = '' } = val;
     switch (val.type) {
+      case 'xuda_network_ambassador_dev_couchdb_readonly': {
+        add_xuda_public_website_tool({
+          name: name || 'Xuda Ambassador Public Website Readonly',
+          description: description || 'Readonly lookup against public xuda.ai website pages for ambassador support answers.',
+        });
+        break;
+      }
+
+      case 'xuda_network_mentor_dev_server_readonly': {
+        add_internal_codex_tool({
+          name: name || 'Xuda Mentor Dev Server Readonly',
+          description: description || 'Readonly Codex lookup on /var/xuda of the dev server for technical mentor answers.',
+          system_prompt: `You are Codex helping a Xuda Network mentor answer technical questions about the Xuda codebase.
+
+Scope:
+- You may inspect only the dev server ${_conf?.internal_ai_agents?.dev_server_host || 'dev.xuda.ai'}.
+- You may use SSH only for readonly inspection.
+- You may read only under /var/xuda.
+- Prefer safe inspection commands such as pwd, ls, find, rg, sed -n, head, tail, wc, git status, git diff --stat, git log --oneline, and git show.
+
+Hard restrictions:
+- Never access config, config_dev, .env files, secret folders, SSH keys, certificates, credential files, database dumps, backups, logs likely to contain credentials, or any path outside /var/xuda.
+- Never query CouchDB or any database.
+- Never use network commands to call internal services.
+- Never run commands that write, mutate, install, delete, restart, deploy, publish, chmod/chown, kill processes, or change system state.
+- Never reveal passwords, tokens, API keys, private keys, names of private people, private emails, personal information, customer data, security details, or anything that could harm Xuda, its team, customers, or product security.
+- If the answer requires forbidden access, say it is outside the readonly mentor scope.
+- If sensitive data appears accidentally, do not quote it. State that sensitive output was omitted.`,
+        });
+        break;
+      }
+
       case 'web_search': {
         tools.push(webSearchTool());
         break;
@@ -5831,8 +6365,8 @@ const load_ai_agent_doc = async function (app_id, agent_id) {
       ai_agent_doc.reference_doc = reference_doc;
     } else if (ai_agent_doc.studio_meta.installed_from_app_uid) {
       const reference_doc = _.cloneDeep(ai_agent_doc);
-      await get_account_default_project_id(ai_agent_doc.studio_meta.installed_from_app_uid);
-      ai_agent_doc = await db_module.get_app_couch_doc_native(app_id, ai_agent_doc.studio_meta.share_item_id);
+      const source_app_id = ai_agent_doc.studio_meta.installed_from_app_id || (await get_account_default_project_id(ai_agent_doc.studio_meta.installed_from_app_uid));
+      ai_agent_doc = await db_module.get_app_couch_doc_native(source_app_id, ai_agent_doc.studio_meta.share_item_id || ai_agent_doc._id);
       ai_agent_doc.reference_doc = reference_doc;
     }
 
@@ -6642,18 +7176,14 @@ const auto_response = async function (uid, profile_id, contact_id, conversation_
     // const conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
 
     let auto_respond_agents = account_profile_doc.auto_respond_agents;
-    if (auto_respond_agents === null || typeof auto_respond_agents === 'undefined') return;
-
-    if (!Array.isArray(auto_respond_agents)) {
-      auto_respond_agents = [];
-    }
+    if (!Array.isArray(auto_respond_agents)) auto_respond_agents = [];
 
     if (!auto_respond_agents.length) {
       const ai_agents_ret = await get_user_ai_agents(uid);
       auto_respond_agents = ai_agents_ret.docs.map((doc) => doc._id).filter(Boolean);
     }
 
-    if (!auto_respond_agents.length) return;
+    const use_default_agent = auto_respond_agents.length === 0;
 
     const runner = new Runner();
     const app_obj = await get_app_obj(account_profile_info.app_id);
@@ -6681,6 +7211,24 @@ const auto_response = async function (uid, profile_id, contact_id, conversation_
     let agents = [];
     let model = _conf.default_ai_model;
 
+    if (use_default_agent) {
+      agents.push(
+        new Agent({
+          name: 'Auto Reply',
+          instructions: `You are ${account_profile_doc.profile_name || userName}'s automatic ${conversation_type === 'chat' ? 'chat' : 'email'} assistant.
+Reply to the latest incoming message from ${contact_doc.name || contact_doc.email} in a friendly, helpful, and concise way.
+Use the conversation history for context.
+Match the language the contact wrote in.
+Do not mention that the reply is automated.
+${conversation_type === 'chat' ? 'Return only the chat message text, ready to send.' : 'Return only the email body, ready to send.'}
+If a signature is available, append it at the end:
+${account_profile_doc.profile_signature || ''}`.trim(),
+          model,
+          metadata: { auto_response: true, default: true, ts: Date.now() },
+        }),
+      );
+    }
+
     for (const agent_id of auto_respond_agents) {
       try {
         const ai_agent_doc = await load_ai_agent_doc(account_profile_info.app_id, agent_id);
@@ -6773,7 +7321,36 @@ Return only the email body.`;
     const response_text = output?.state?._currentStep?.output?.trim();
     if (!response_text) return;
 
-    if (conversation_type === 'chat') {
+    const is_widget_reply = contact_doc.source === 'widget';
+
+    if (conversation_type === 'chat' && is_widget_reply) {
+      // Widget visitor has no project — write the reply directly on the rep's app only.
+      let conv_item_ref_id;
+      try {
+        conv_item_ref_id = await add_conversation_item(uid, profile_id, conversation_doc._id, response_text, 'chat', contact_id, { direction: 'out' });
+      } catch (err) {}
+      const now = Date.now();
+      const reply_item = {
+        _id: await _common.xuda_get_uuid('chat_conversation_item'),
+        stat: 3,
+        docType: 'chat_conversation_item',
+        uid,
+        conversation_type: 'chat',
+        type: 'chat',
+        date_created_ts: now,
+        ts: now,
+        conversation_id: conversation_doc._id,
+        text: response_text,
+        reference_id: contact_id,
+        conversation_item_reference_id: conv_item_ref_id,
+        direction: 'out',
+        role: 'user',
+        auto_response: true,
+        widget_source: true,
+        rtl: _common.detectRTL(response_text),
+      };
+      await db_module.save_app_couch_doc(account_profile_info.app_id, reply_item);
+    } else if (conversation_type === 'chat') {
       await contact_chat_conversation(
         {
           profile_id,
@@ -7161,10 +7738,10 @@ const get_plugin_tool = async function (app_id, uid, plugin_name, method, prop_d
   }
 };
 
-const create_and_upload_image_to_drive = async function (drive_type, file_path, file_name, prompt, numGenerations, uid, app_id, job_id, headers = {}, is_system, tags = [], account_profile_info) {
+const create_and_upload_image_to_drive = async function (drive_type, file_path, file_name, prompt, numGenerations, uid, app_id, job_id, headers = {}, is_system, tags = [], account_profile_info, width = 256, height = 256) {
   try {
     // 1. Generate the images
-    let result = await create_image(uid, prompt, undefined, undefined, numGenerations, undefined, undefined, { drive_type, file_path, file_name }, account_profile_info);
+    let result = await create_image(uid, prompt, undefined, undefined, numGenerations, width, height, { drive_type, file_path, file_name }, account_profile_info);
 
     // Normalize to array
     const images = Array.isArray(result) ? result : [result];
@@ -8005,12 +8582,12 @@ const create_ai_agent_image = async function (req, job_id, headers) {
   const tempOutputPath = path.join(tempDir, `output_${uniqueId}.png`);
 
   const { app_id, uid, ai_agent_id, tags } = req;
-  const account_profile_info = await get_active_account_profile_info(uid);
+  const account_profile_info = req.account_profile_info || (await get_active_account_profile_info(uid));
   const ai_agent_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, ai_agent_id);
   const account_doc = await db_module.get_couch_doc_native('xuda_accounts', uid);
 
   // faceless humanoid for business
-  if (account_doc.account_info.account_type === 'business') {
+  if (account_doc.account_info.account_type === 'business' || ai_agent_doc.studio_meta?.force_faceless_agent_image) {
     const prompt = `
       Create a futuristic, faceless humanoid profile portrait with a transparent background.
 
@@ -8045,7 +8622,7 @@ const create_ai_agent_image = async function (req, job_id, headers) {
 
         `;
 
-    const images_arr = await create_and_upload_image_to_drive('studio', 'Progs Thumbnails', ai_agent_id, prompt, 1, uid, app_id, job_id, headers, false, tags, account_profile_info);
+    const images_arr = await create_and_upload_image_to_drive('studio', 'Progs Thumbnails', ai_agent_id, prompt, 1, uid, app_id, job_id, headers, false, tags, account_profile_info, 1024, 1024);
     return { code: 1, data: images_arr[0] };
   }
 
@@ -13293,8 +13870,8 @@ export const get_chat_suggestions = async function (req) {
               ai_agent_doc.reference_doc = reference_doc;
             } else if (ai_agent_doc.studio_meta.installed_from_app_uid) {
               const reference_doc = _.cloneDeep(ai_agent_doc);
-              await get_account_default_project_id(ai_agent_doc.studio_meta.installed_from_app_uid);
-              ai_agent_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, ai_agent_doc.studio_meta.share_item_id);
+              const source_app_id = ai_agent_doc.studio_meta.installed_from_app_id || (await get_account_default_project_id(ai_agent_doc.studio_meta.installed_from_app_uid));
+              ai_agent_doc = await db_module.get_app_couch_doc_native(source_app_id, ai_agent_doc.studio_meta.share_item_id || ai_agent_doc._id);
               ai_agent_doc.reference_doc = reference_doc;
             }
 
@@ -13453,3 +14030,513 @@ export const validate_credits_limit = async function (uid, profile_id) {
     return err;
   }
 };
+
+////////////////////////////// CHAT WIDGET (embed) //////////////////////////////
+
+const WIDGET_EMAIL_RE = /^[\w\.\-+]+@[a-zA-Z\d\.\-]+\.[a-zA-Z]{2,}$/;
+const WIDGET_SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const WIDGET_DEFAULT_GREETING = 'Hi! How can we help?';
+
+const _widget_split_name = function (name) {
+  const parts = String(name || '')
+    .trim()
+    .split(/\s+/);
+  return { first_name: parts[0] || name || '', last_name: parts.slice(1).join(' ') || '' };
+};
+
+const _widget_verify_google_id_token = async function (id_token) {
+  // Use Google's tokeninfo endpoint — validates signature, expiration, and returns the payload.
+  // Cheaper than carrying google-auth-library; one extra HTTPS round-trip per signup is fine.
+  const r = await fetch(`https://oauth2.googleapis.com/tokeninfo?id_token=${encodeURIComponent(id_token)}`);
+  if (!r.ok) throw new Error('google_token_invalid');
+  const payload = await r.json();
+  if (!payload || !payload.email) throw new Error('google_token_no_email');
+  if (payload.email_verified !== 'true' && payload.email_verified !== true) throw new Error('google_email_unverified');
+  const expected_aud = _conf?.gmail?.clientId;
+  if (expected_aud && payload.aud !== expected_aud) throw new Error('google_token_wrong_aud');
+  return payload;
+};
+
+const _widget_find_or_create_visitor = async function (email, name, google_sub) {
+  const ret = await db_module.find_couch_query('xuda_accounts', {
+    selector: { 'account_info.email': email },
+    fields: ['_id'],
+    limit: 1,
+  });
+  if (ret.docs && ret.docs.length) {
+    // If we have a google_sub and the existing account lacks one, attach it.
+    if (google_sub) {
+      try {
+        const acct_ret = await db_module.get_couch_doc('xuda_accounts', ret.docs[0]._id);
+        if (acct_ret.code > -1) {
+          const acct = acct_ret.data;
+          if (!acct.google_sub) {
+            acct.google_sub = google_sub;
+            acct.google_linked = true;
+            acct.ts = Date.now();
+            await db_module.save_couch_doc('xuda_accounts', acct);
+          }
+        }
+      } catch (err) {}
+    }
+    return ret.docs[0]._id;
+  }
+
+  const _utils = await import(path.join(process.env.XUDA_HOME, 'common', 'xuda-cpi-utils.mjs'));
+  const secret = _utils.get_id('tmp_pass', 5);
+  const hash = _utils.hash(secret);
+  const { first_name, last_name } = _widget_split_name(name);
+  const doc = {
+    _id: await _common.xuda_get_uuid('account'),
+    stat: 1,
+    docType: 'account',
+    source: 'widget',
+    password: hash,
+    email,
+    account_info: { email, username: _utils.get_id('xu'), first_name, last_name, full_name: name },
+  };
+  if (google_sub) {
+    doc.google_sub = google_sub;
+    doc.google_linked = true;
+  }
+  const save_ret = await db_module.save_couch_doc('xuda_accounts', doc);
+  if (save_ret.code < 0) throw new Error(save_ret.data || 'visitor_create_failed');
+  return doc._id;
+};
+
+const _widget_find_existing_team_req = async function (visitor_uid, canonical_profile_id) {
+  const ret = await db_module.find_couch_query('xuda_team', {
+    selector: {
+      docType: 'team_request',
+      access_type: 'contact_connection',
+      team_req_from_uid: visitor_uid,
+      share_item_id: canonical_profile_id,
+      contact_source: 'widget',
+    },
+    limit: 1,
+  });
+  return ret?.docs?.[0] || null;
+};
+
+const _widget_pick_assignee = async function (canonical_owner_uid, canonical_profile_id) {
+  const member_uids = await account_ms.get_account_profile_group_member_uids(canonical_owner_uid, canonical_profile_id);
+  const candidates = [canonical_owner_uid, ...(member_uids || [])].filter(Boolean);
+  return candidates[Math.floor(Math.random() * candidates.length)];
+};
+
+const _widget_auto_accept = async function (team_req_doc, assigned_uid, visitor_email, visitor_name) {
+  // Add contact first (creates the contact on the rep's side). The team_req on disk
+  // is still stat=2 at this point, which is fine because add_contact only stores a
+  // reference (team_req_id) on the contact doc and does not read the team_req body.
+  const add_ret = await account_ms.add_contact({
+    uid: assigned_uid,
+    name: visitor_name,
+    email: visitor_email,
+    contact_uid: team_req_doc.team_req_from_uid,
+    source: 'widget',
+    team_req_id: team_req_doc._id,
+  });
+  let contact_id;
+  if (add_ret.code > -1) {
+    contact_id = add_ret.data?.id;
+  } else if (add_ret.contact_id) {
+    contact_id = add_ret.contact_id;
+  }
+  if (!contact_id) throw new Error('add_contact_failed');
+
+  // Refresh _rev and write the final accepted state in one update.
+  const fresh_ret = await db_module.get_couch_doc('xuda_team', team_req_doc._id);
+  if (fresh_ret.code < 0) throw new Error(fresh_ret.data || 'team_req_missing');
+  const fresh = fresh_ret.data;
+  fresh.team_req_stat = 3;
+  fresh.team_req_stat_desc = 'widget auto-accepted';
+  fresh.team_req_status_date = Date.now();
+  fresh.team_req_to_contact_id = contact_id;
+  const save_ret = await db_module.save_couch_doc('xuda_team', fresh);
+  if (save_ret.code < 0) throw new Error(save_ret.data || 'team_req_save_failed');
+
+  team_req_doc.team_req_stat = 3;
+  team_req_doc.team_req_to_contact_id = contact_id;
+  return contact_id;
+};
+
+const _widget_ensure_conversation = async function (assigned_uid, canonical_profile_id, contact_id, job_id, headers) {
+  const rep_app_id = await account_ms.get_account_default_project_id(assigned_uid);
+  const conv_ret = await db_module.find_app_couch_query(rep_app_id, {
+    selector: {
+      docType: 'chat_conversation',
+      conversation_type: 'chat',
+      reference_type: 'contacts',
+      reference_id: contact_id,
+      stat: { $lt: 4 },
+    },
+    limit: 1,
+    sort: [{ ts: 'desc' }],
+  });
+  if (conv_ret?.docs?.length) return conv_ret.docs[0]._id;
+
+  const save_ret = await create_conversation(
+    {
+      uid: assigned_uid,
+      profile_id: canonical_profile_id,
+      conversation_type: 'chat',
+      reference_type: 'contacts',
+      reference_id: contact_id,
+      prompt: '',
+      direction: 'in',
+      perform_ai_execution: false,
+    },
+    job_id,
+    headers,
+  );
+  return save_ret?.data?.id;
+};
+
+const _widget_load_session = async function (widget_token) {
+  if (!widget_token) return null;
+  const ret = await db_module.get_couch_doc('xuda_sessions', widget_token);
+  if (ret.code < 0) return null;
+  const session = ret.data;
+  if (session.docType !== 'widget_session') return null;
+  if (session.stat !== 2) return null;
+  if (session.ttl_ts && session.ttl_ts < Date.now()) return null;
+  return session;
+};
+
+const _widget_refresh_state = async function (session, job_id, headers) {
+  if (session.state === 'open' || session.state === 'declined') return session;
+  const tr_ret = await db_module.get_couch_doc('xuda_team', session.team_req_id);
+  if (tr_ret.code < 0) return session;
+  const tr = tr_ret.data;
+  if (tr.team_req_stat === 3) {
+    session.state = 'open';
+    session.contact_id = tr.team_req_to_contact_id || session.contact_id;
+    if (!session.conversation_id && session.contact_id) {
+      try {
+        session.conversation_id = await _widget_ensure_conversation(session.assigned_uid, session.profile_id, session.contact_id, job_id, headers);
+      } catch (err) {}
+    }
+    session.ts = Date.now();
+    await db_module.save_couch_doc('xuda_sessions', session);
+  } else if (tr.team_req_stat === 4) {
+    session.state = 'declined';
+    session.ts = Date.now();
+    await db_module.save_couch_doc('xuda_sessions', session);
+  }
+  return session;
+};
+
+export const get_widget_embed_snippet = async function (req, job_id, headers) {
+  try {
+    const { uid, profile_id, config } = req;
+    const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+    const canonical_owner_uid = account_profile_info.uid;
+    const canonical_profile_id = account_profile_info.account_profile_id;
+
+    // Persist widget config + enable only when caller is canonical owner
+    if (canonical_owner_uid === uid) {
+      const doc = account_profile_info.account_profile_obj || { _id: canonical_profile_id };
+      doc.widget_enabled = true;
+      doc.widget_config = { ...(doc.widget_config || {}), ...(config || {}) };
+      doc.ts = Date.now();
+      await db_module.save_app_couch_doc_native(account_profile_info.app_id, doc);
+    }
+
+    const widget_profile_id = `${canonical_owner_uid}.${canonical_profile_id}`;
+    const domain = _conf.domain || 'xuda.io';
+    const iframe_url = `https://${domain}/chat-widget/${widget_profile_id}`;
+    const snippet = `<script>(function(){var d=document,s=d.createElement('script');s.src='https://${domain}/dist/runtime/js/chat-widget-loader.js';s.async=1;s.setAttribute('data-profile','${widget_profile_id}');d.head.appendChild(s);})();</script>`;
+
+    return { code: 1, data: { widget_profile_id, snippet, iframe_url } };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+const _widget_signup_core = async function (req, job_id, headers, opts) {
+  const { profile_id, email, name, widget_origin, google_sub, signup_method } = req;
+  const [owner_uid_part, pid_part] = String(profile_id || '').split('.');
+  if (!owner_uid_part || !pid_part) return { code: -404, data: 'invalid_profile' };
+
+  const account_profile_info = await get_active_account_profile_info(owner_uid_part, pid_part);
+  const canonical_owner_uid = account_profile_info.uid;
+  const canonical_profile_id = account_profile_info.account_profile_id;
+
+  const ap_doc = account_profile_info.account_profile_obj || {};
+  if (ap_doc.widget_enabled === false) return { code: -404, data: 'widget_disabled' };
+
+  const visitor_uid = await _widget_find_or_create_visitor(email, name, google_sub);
+  return await _widget_signup_finalize(visitor_uid, email, name, widget_origin, signup_method, account_profile_info, canonical_owner_uid, canonical_profile_id, ap_doc, job_id, headers);
+};
+
+export const widget_signup = async function (req, job_id, headers) {
+  try {
+    let { profile_id, email, name, widget_origin } = req;
+    if (typeof email !== 'string' || typeof name !== 'string') return { code: -1, data: 'invalid_input' };
+    email = email.toLowerCase().trim();
+    name = name.trim();
+    if (!email || !name) return { code: -1, data: 'invalid_input' };
+    if (!WIDGET_EMAIL_RE.test(email)) return { code: -1, data: 'invalid_email' };
+
+    return await _widget_signup_core({ profile_id, email, name, widget_origin, signup_method: 'email' }, job_id, headers);
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+export const widget_signup_google = async function (req, job_id, headers) {
+  try {
+    const { profile_id, id_token, widget_origin } = req;
+    if (!id_token || typeof id_token !== 'string') return { code: -1, data: 'missing_id_token' };
+
+    let payload;
+    try {
+      payload = await _widget_verify_google_id_token(id_token);
+    } catch (err) {
+      return { code: -401, data: err.message || 'google_token_invalid' };
+    }
+
+    const email = String(payload.email || '')
+      .toLowerCase()
+      .trim();
+    const name = String(payload.name || payload.email?.split('@')[0] || 'Friend').trim();
+    if (!email) return { code: -1, data: 'no_email_in_token' };
+
+    return await _widget_signup_core({ profile_id, email, name, widget_origin, google_sub: payload.sub, signup_method: 'google' }, job_id, headers);
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+const _widget_signup_finalize = async function (visitor_uid, email, name, widget_origin, signup_method, account_profile_info, canonical_owner_uid, canonical_profile_id, ap_doc, job_id, headers) {
+  try {
+    let team_req_doc = await _widget_find_existing_team_req(visitor_uid, canonical_profile_id);
+    let assigned_uid;
+
+    if (team_req_doc) {
+      assigned_uid = team_req_doc.team_req_to_uid;
+    } else {
+      assigned_uid = await _widget_pick_assignee(canonical_owner_uid, canonical_profile_id);
+      if (!assigned_uid) return { code: -1, data: 'no_assignee' };
+
+      const assigned_acct_ret = await db_module.get_couch_doc('xuda_accounts', assigned_uid);
+      const assigned_email = assigned_acct_ret?.data?.account_info?.email || assigned_acct_ret?.data?.email || '';
+
+      const { first_name, last_name } = _widget_split_name(name);
+      const team_req_id = await _common.xuda_get_uuid('team_req');
+      team_req_doc = {
+        _id: team_req_id,
+        team_req_id,
+        team_req_date: Date.now(),
+        team_req_status_date: null,
+        team_req_to_email: assigned_email,
+        team_req_to_uid: assigned_uid,
+        team_req_stat: 2,
+        team_req_stat_desc: 'widget signup',
+        team_req_from_uid: visitor_uid,
+        docType: 'team_request',
+        team_req_app_id: null,
+        access_type: 'contact_connection',
+        uid: visitor_uid,
+        contact_source: 'widget',
+        share_item_id: canonical_profile_id,
+        widget_origin: widget_origin || '',
+        sender_account_info: { email, first_name, last_name, full_name: name },
+      };
+      const tr_save = await db_module.save_couch_doc('xuda_team', team_req_doc);
+      if (tr_save.code < 0) return { code: -1, data: tr_save.data || 'team_request_create_failed' };
+
+      // fire and forget — sending the invitation email shouldn't block the visitor's response
+      team_ms.send_access_invitation({ team_req_id: team_req_doc._id }).catch(() => {});
+    }
+
+    let state = team_req_doc.team_req_stat === 3 ? 'open' : team_req_doc.team_req_stat === 4 ? 'declined' : 'pending';
+    let contact_id = team_req_doc.team_req_to_contact_id;
+    let conversation_id;
+
+    const auto_accept = !!ap_doc?.auto_respond;
+    if (state === 'pending' && auto_accept) {
+      try {
+        contact_id = await _widget_auto_accept(team_req_doc, assigned_uid, email, name);
+        state = 'open';
+      } catch (err) {
+        state = 'pending';
+      }
+    }
+
+    if (state === 'open' && contact_id) {
+      try {
+        conversation_id = await _widget_ensure_conversation(assigned_uid, canonical_profile_id, contact_id, job_id, headers);
+      } catch (err) {}
+    }
+
+    const widget_token = `wds_${crypto.randomUUID().replace(/-/g, '')}`;
+    const now = Date.now();
+    const session_doc = {
+      _id: widget_token,
+      docType: 'widget_session',
+      stat: 2,
+      state,
+      visitor_uid,
+      team_req_id: team_req_doc._id,
+      assigned_uid,
+      owner_uid: canonical_owner_uid,
+      profile_id: canonical_profile_id,
+      contact_id,
+      conversation_id,
+      widget_origin: widget_origin || '',
+      date_created_ts: now,
+      ts: now,
+      ttl_ts: now + WIDGET_SESSION_TTL_MS,
+    };
+    await db_module.save_couch_doc('xuda_sessions', session_doc);
+
+    const assigned_info_ret = await account_ms.get_account_name({ uid_query: assigned_uid });
+    const assigned_name = assigned_info_ret?.data?.full_name || assigned_info_ret?.data?.first_name || '';
+    const assigned_avatar = assigned_info_ret?.data?.profile_picture || assigned_info_ret?.data?.profile_avatar || '';
+    const greeting = ap_doc?.widget_config?.greeting || WIDGET_DEFAULT_GREETING;
+
+    return {
+      code: 1,
+      data: {
+        widget_token,
+        state,
+        assigned_name,
+        assigned_avatar,
+        greeting,
+        conversation_id,
+        signup_method: signup_method || 'email',
+        account_active: signup_method === 'google',
+        signin_url: signup_method === 'google' ? `https://${_conf.domain || 'xuda.ai'}/dashboard/login` : undefined,
+      },
+    };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+export const widget_send_message = async function (req, job_id, headers) {
+  try {
+    const { widget_token, prompt = '', attachments = [] } = req;
+    const text = typeof prompt === 'string' ? prompt : '';
+    if (!text.trim() && (!Array.isArray(attachments) || !attachments.length)) {
+      return { code: -1, data: 'invalid_prompt' };
+    }
+
+    // Validate + sanitize image attachments. Inline base64 images only, max 5, ~2.5MB each.
+    const safe_attachments = [];
+    for (const att of (Array.isArray(attachments) ? attachments : []).slice(0, 5)) {
+      if (!att || typeof att.data_uri !== 'string') continue;
+      if (!/^data:image\/(png|jpeg|jpg|gif|webp);base64,/i.test(att.data_uri)) continue;
+      if (att.data_uri.length > 3_500_000) continue;
+      safe_attachments.push({
+        data_uri: att.data_uri,
+        filename: String(att.filename || 'image').slice(0, 200),
+        size: Number(att.size) || 0,
+        type: String(att.type || 'image/png').slice(0, 60),
+      });
+    }
+
+    let session = await _widget_load_session(widget_token);
+    if (!session) return { code: -401, data: 'invalid_token' };
+
+    session = await _widget_refresh_state(session, job_id, headers);
+    if (session.state !== 'open') return { code: -409, data: 'pending_approval' };
+
+    const { assigned_uid, profile_id, conversation_id, contact_id, widget_origin } = session;
+    if (!conversation_id || !contact_id) return { code: -409, data: 'not_ready' };
+
+    const rep_app_id = await account_ms.get_account_default_project_id(assigned_uid);
+
+    // Compose the prompt text to include attachment notice (visible to the agent + history)
+    let prompt_for_history = text.trim();
+    if (safe_attachments.length) {
+      const att_note = `[Attached ${safe_attachments.length} image${safe_attachments.length > 1 ? 's' : ''}: ${safe_attachments.map((a) => a.filename).join(', ')}]`;
+      prompt_for_history = prompt_for_history ? `${prompt_for_history}\n\n${att_note}` : att_note;
+    }
+
+    let conversation_item_reference_id;
+    try {
+      conversation_item_reference_id = await add_conversation_item(assigned_uid, profile_id, conversation_id, prompt_for_history, 'chat', contact_id, { direction: 'in' });
+      report_ai_status('conversations');
+    } catch (err) {
+      report_ai_status('conversations', err);
+    }
+
+    const now = Date.now();
+    const item_doc = {
+      _id: await _common.xuda_get_uuid('chat_conversation_item'),
+      stat: 3,
+      docType: 'chat_conversation_item',
+      uid: assigned_uid,
+      conversation_type: 'chat',
+      type: 'chat',
+      date_created_ts: now,
+      ts: now,
+      conversation_id,
+      text: text.trim(),
+      reference_id: contact_id,
+      conversation_item_reference_id,
+      direction: 'in',
+      role: 'user',
+      widget_source: true,
+      widget_origin: widget_origin || '',
+      rtl: _common.detectRTL(text),
+      attachments: safe_attachments,
+    };
+    const save_ret = await db_module.save_app_couch_doc(rep_app_id, item_doc);
+
+    session.ts = now;
+    await db_module.save_couch_doc('xuda_sessions', session);
+
+    try {
+      auto_response(assigned_uid, profile_id, contact_id, 'chat');
+    } catch (err) {}
+
+    return { code: 15, data: save_ret };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+export const widget_get_messages = async function (req, job_id, headers) {
+  try {
+    const { widget_token, since_ts = 0, limit = 100 } = req;
+    let session = await _widget_load_session(widget_token);
+    if (!session) return { code: -401, data: 'invalid_token' };
+
+    session = await _widget_refresh_state(session, job_id, headers);
+
+    const server_ts = Date.now();
+    if (session.state !== 'open' || !session.conversation_id) {
+      return { code: 15, data: { state: session.state, items: [], conversation_id: session.conversation_id || null, server_ts } };
+    }
+
+    const rep_app_id = await account_ms.get_account_default_project_id(session.assigned_uid);
+    const ret = await db_module.find_app_couch_query(rep_app_id, {
+      selector: {
+        docType: 'chat_conversation_item',
+        conversation_id: session.conversation_id,
+        stat: 3,
+        date_created_ts: { $gt: Number(since_ts) || 0 },
+      },
+      sort: [{ date_created_ts: 'asc' }],
+      limit: Math.min(Number(limit) || 100, 500),
+    });
+
+    const items = (ret?.docs || []).map((d) => ({
+      _id: d._id,
+      text: d.text,
+      direction: d.direction,
+      role: d.role,
+      date_created_ts: d.date_created_ts,
+      conversation_type: d.conversation_type,
+      attachments: d.attachments,
+      rtl: d.rtl,
+    }));
+
+    return { code: 15, data: { state: 'open', items, conversation_id: session.conversation_id, server_ts } };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};