@xuda.io/ai_module 1.1.5653 → 1.1.5655

package/index.mjs

@@ -435,11 +435,24 @@ const misc_msa = await import(`${module_path}/misc_module/index_msa.mjs`);
 // stat that could not change, and Stop did nothing but leave the response
 // streaming. Read the flag itself, and keep the stat + "job vanished" cases so
 // non-chat runs (which do go through update_job) behave exactly as before.
+// Only an EXPLICIT stop counts. `abort_job` (jobs_module) records a Stop by writing
+// `abort: true` onto the job, and stat 4 is the cancelled state, so those two are the whole
+// signal. "I could not read the job" is not one of them, and it used to be: a `code < 0` from
+// get_job_info was read as aborted and killed the run on the spot.
+//
+// That is reachable, not theoretical. jobs_module stores a job in memcached under a 600s TTL
+// refreshed only by a progress write, and the chat path's update_job calls are commented out
+// in favour of stream_phase, so a run stops being findable after ten minutes. Everything past
+// that point (a long tool chain, a slow generation, a retry) was cut off mid-answer and
+// reported to the user as "Stopped." as though they had pressed the button themselves. An
+// unreadable job now simply means "no stop was requested": the worst case is a run that
+// finishes work nobody is waiting for any more, which is a great deal better than silently
+// truncating one somebody is.
 const is_job_aborted = async function (job_id) {
   if (!job_id) return false;
   try {
     const job_info = await jobs_ms.get_job_info({ job_id });
-    return job_info.code < 0 || job_info?.data?.abort === true || job_info?.data?.stat === 4;
+    return job_info?.data?.abort === true || job_info?.data?.stat === 4;
   } catch (err) {
     return false;
   }
@@ -510,6 +523,64 @@ try {
 }
 const model = _conf.default_ai_model;
 
+// A run that dies between the model asking for a tool and that tool's output being written
+// leaves a `function_call` in the OpenAI conversation with no `function_call_output` against
+// it, and the Responses API then rejects the WHOLE conversation, for ever:
+// "400 No tool output found for function call call_...". The thread is not degraded, it is
+// finished. Every later turn fails identically, Retry included, and there is nothing the user
+// can do from the chat to recover it. Boaz hit this on a Shorts Maker thread whose
+// modify_short call was cut off: three sends in a row came back as error cards.
+//
+// Interruptions are not rare (Stop, a pm2 restart mid-run, a tool that throws, a job whose
+// record expired), so repair on the way IN rather than waiting for the failure: drop any
+// function_call that never got its output and the thread carries on from the last consistent
+// point, with the model simply deciding again what to call. Deleting the call rather than
+// inventing an output for it is deliberate, an invented output is a lie the model then reasons
+// from, while a dropped call is simply a decision it never made.
+//
+// `items` is passed in by callers that were already listing them (ai_chat_conversation fetches
+// the page anyway for its `after` cursor, so there it costs nothing) and fetched here for
+// callers that were not. Sound on a partial page either way: an output is always NEWER than its
+// call and the page is in `desc` order, so any function_call visible in the window has its
+// output visible as well if it ever had one.
+//
+// Never throws. A thread that cannot be repaired still gets its turn, and just fails the way it
+// already did. Returns the items that survived, so a caller reading a cursor off them cannot
+// end up pointing at something this just deleted.
+const drop_orphaned_tool_calls = async function (conversation_reference_id, items) {
+  if (!conversation_reference_id) return items || [];
+
+  let list = items;
+  if (!list) {
+    try {
+      const ret = await client.conversations.items.list(conversation_reference_id, { order: 'desc' });
+      list = ret?.data || [];
+    } catch (err) {
+      console.error(`[drop_orphaned_tool_calls] could not read ${conversation_reference_id}: ${err?.message || err}`);
+      return [];
+    }
+  }
+
+  const answered = new Set();
+  for (const item of list) {
+    if (item?.type === 'function_call_output' && item.call_id) answered.add(item.call_id);
+  }
+  const orphans = list.filter((item) => item?.type === 'function_call' && item.call_id && !answered.has(item.call_id));
+  if (!orphans.length) return list;
+
+  const dropped = new Set();
+  for (const orphan of orphans) {
+    try {
+      await client.conversations.items.delete(orphan.id, { conversation_id: conversation_reference_id });
+      dropped.add(orphan.id);
+      console.log(`[drop_orphaned_tool_calls] dropped orphaned tool call ${orphan.name || ''} ${orphan.call_id} from ${conversation_reference_id}`);
+    } catch (err) {
+      console.error(`[drop_orphaned_tool_calls] could not drop ${orphan.call_id}: ${err?.message || err}`);
+    }
+  }
+  return list.filter((item) => !dropped.has(item.id));
+};
+
 // UI-138: the catalog code to draw a TRANSPARENT-background image edit with.
 //
 // These edits used to name 'chatgpt-image-latest' directly, but ai_model_aliases maps
@@ -523,9 +594,17 @@ const transparent_image_model = function () {
   return _conf?.transparent_image_model || 'img-1';
 };
 
+// UI-210: read the status and the param off whichever shape the error arrives in. The
+// first pass only looked at `err.status` and `err.param`, which is the openai-node
+// BadRequestError shape; the same refusal wrapped by a retry helper or an http client
+// surfaces as `err.response.status` / `err.error.param` and slipped straight past the
+// guard, so the call that was supposed to degrade threw instead. The message test is the
+// backstop for anything that carries neither.
 const _is_transparent_background_rejected = function (err) {
-  if (err?.status !== 400) return false;
-  return err?.param === 'background' || /transparent background is not supported/i.test(err?.message || '');
+  const status = err?.status ?? err?.statusCode ?? err?.response?.status;
+  if (status !== 400) return false;
+  const param = err?.param ?? err?.error?.param ?? err?.response?.data?.error?.param;
+  return param === 'background' || /transparent background is not supported/i.test(err?.message || err?.error?.message || '');
 };
 
 // images.edit asking for a transparent background, degrading to an opaque render if the
@@ -1538,17 +1617,28 @@ const check_studio_doc_tool = tool({
 // only when ws_dashboard says this user is NOT watching that conversation.
 const CHAT_PRESENCE_TIMEOUT_MS = 4000;
 
-// The dashboard route is /dashboard/<tab>/<referenceId>. An ai_chat is keyed by the
-// conversation itself; every other tab is keyed by whatever the conversation hangs
-// off (the contact, the agent, the app).
+// The dashboard route is /dashboard/<tab>/<referenceId>, and a CONVERSATION is addressed at
+// /dashboard/ai_chats/<conversation_id> whatever it hangs off: that is the route the
+// dashboard itself navigates to after the first send inside an agent (AiChat.vue), so it
+// opens an agent's or a contact's thread just as well as a plain ai_chat.
+//
+// UI-187: it used to send anything with a reference to /dashboard/<reference_type>/<id>
+// instead, so an agent's alert opened the AGENT (its detail view, listing every past chat)
+// and a contact's opened the CONTACT. The alert says an answer is ready and then landed you
+// somewhere you still had to go looking for it. Boaz: "clicking on the toast/fcm should open
+// the conversation".
+//
+// Two exceptions keep their entity route because the conversation has no standalone page
+// there: an app's thread lives inside the app panel, and a `dashboard` conversation is the
+// home composer itself.
 const chat_finished_link = function (conversation_doc, conversation_id) {
   const base = embed_origin();
   const reference_type = conversation_doc?.reference_type;
   const reference_id = conversation_doc?.reference_id;
-  if (!reference_type || reference_type === 'ai_chats') return `${base}/dashboard/ai_chats/${conversation_id}`;
   if (reference_type === 'dashboard') return `${base}/dashboard`;
   if (reference_type === 'studio') return reference_id ? `${base}/dashboard/apps/${reference_id}` : `${base}/dashboard/apps`;
-  if (!reference_id) return `${base}/dashboard`;
+  if (conversation_id) return `${base}/dashboard/ai_chats/${conversation_id}`;
+  if (!reference_type || !reference_id) return `${base}/dashboard`;
   return `${base}/dashboard/${reference_type}/${reference_id}`;
 };
 
@@ -1644,8 +1734,15 @@ const notify_chat_finished = async function ({ uid, conversation_id, conversatio
     notification_msa.submit_notification?.({
       type: 'ai',
       uid_arr: [uid],
-      subject: title ? `Ready: ${title}` : 'Your chat is ready',
+      // UI-193: the NAME, and nothing else. Boaz, on a finished pitch-deck run: "keep only
+      // the name in the fcm/toast". It used to lead with "Ready:" and then spend the body
+      // on the first 160 characters of the answer, which on a lock screen is a paragraph of
+      // half-sentences and a truncated URL. The picture says who it is from and the name
+      // says which chat, so the text the notification shows is exactly the name.
+      subject: title || 'Your chat is ready',
+      // Kept for the bell, which is a list you read rather than a line you glance at.
       body: chat_finished_summary(text),
+      push_body: '',
       // The chat's own picture, on the push and on the toast that stands in for it.
       ...(image ? { icon: image } : {}),
       delivery_method: ['push'],
@@ -1662,6 +1759,98 @@ const notify_chat_finished = async function ({ uid, conversation_id, conversatio
   }
 };
 
+// ─── Message from a person ────────────────────────────────────────────────────
+// UI-193. A person-to-person chat only ever reached the recipient over the socket, as a
+// conversation_doc_updated the Chats screen redraws off. So a message arrived silently
+// unless that exact screen happened to be open: nothing on a phone, nothing on another
+// tab, nothing on any other screen in the dashboard. Same three roads as the chat-finished
+// alert (system notification, foreground toast, socket toast when there is no live token),
+// and the same rule about what it says: the sender's NAME and the sender's FACE, with the
+// message itself kept for the notification center.
+//
+// The picture is the one the RECIPIENT has of the sender, not the sender's own copy of
+// themselves: `connection_contact_id` is the mirror contact in the recipient's book, which
+// is what their Chats list and contact card already draw, so the alert and the thread it
+// opens show the same person.
+//
+// Who the sender IS, resolved the way the recipient would recognise them. Three roads,
+// because the first two can both come up empty:
+//  1. the mirror contact the connection request recorded (`connection_contact_id`),
+//  2. failing that, the recipient's own contact carrying the sender's uid. The mirror id
+//     is only written for a `contact_connection` request, so a pair connected any other
+//     way (an ai_agent share, for one) has a perfectly good contact on both sides and no
+//     pointer between them. Without this the alert read "New message" with no face,
+//  3. failing that, the sender's account itself, so a message from someone not yet in
+//     your book still says who it is from instead of going anonymous.
+const chat_message_sender = async function (to_uid, from_uid, from_contact_id) {
+  let contact_id = from_contact_id;
+  if (!contact_id && from_uid) {
+    try {
+      const to_app_id = await get_account_default_project_id(to_uid);
+      const q = await db_module.find_app_couch_query(to_app_id, {
+        selector: { docType: 'contact', contact_uid: from_uid },
+        fields: ['_id'],
+        limit: 1,
+      });
+      contact_id = q?.docs?.[0]?._id;
+    } catch (err) {
+      /* fall through to the account */
+    }
+  }
+
+  if (contact_id) {
+    const contact = await get_contact_info(to_uid, null, contact_id).catch(() => null);
+    const name = String(contact?.name || '').trim();
+    const image = contact?.profile_picture || contact?.profile_avatar || undefined;
+    if (name || image) return { name, image };
+  }
+
+  if (from_uid) {
+    const acc = await get_account_name({ uid_query: from_uid }).catch(() => null);
+    const d = acc?.data;
+    if (d) {
+      const name = (d.account_type === 'business' ? d.business_name : `${d.first_name || ''} ${d.last_name || ''}`.trim()) || '';
+      return { name: String(name).trim(), image: d.profile_picture || d.profile_avatar || undefined };
+    }
+  }
+
+  return { name: '', image: undefined };
+};
+
+const notify_chat_message = async function ({ to_uid, from_uid, from_contact_id, conversation_id, conversation_doc, text }) {
+  try {
+    if (!to_uid || !conversation_id) return;
+
+    // Not while they are looking at it. Same presence gate, and the same reading of a
+    // non-answer: if ws_dashboard cannot say, stay quiet rather than interrupt someone
+    // who is already reading the message.
+    const presence = await Promise.race([
+      ws_dashboard_ms.is_chat_open({ uid: to_uid, conversation_id }),
+      new Promise((resolve) => setTimeout(() => resolve(null), CHAT_PRESENCE_TIMEOUT_MS)),
+    ]);
+    if (!presence || presence.code < 0 || presence.data !== false) return;
+
+    const { name: from_name, image } = await chat_message_sender(to_uid, from_uid, from_contact_id);
+
+    notification_msa.submit_notification?.({
+      type: 'chat',
+      uid_arr: [to_uid],
+      subject: from_name || 'New message',
+      // The message, for the bell. `push_body` empties it on the alert itself.
+      body: chat_finished_summary(text),
+      push_body: '',
+      ...(image ? { icon: image } : {}),
+      delivery_method: ['push'],
+      display_type: 'info',
+      ref: conversation_id,
+      params: { kind: 'chat_message', conversation_id, reference_type: 'contacts' },
+      link: chat_finished_link(conversation_doc, conversation_id),
+    });
+  } catch (err) {
+    console.error(`[notify_chat_message] failed: ${err?.message || err}`);
+  }
+};
+
 export const execute_codex_request = async function (req_or_ip, prompt_arg, attachments_arg = []) {
   let emitToDashboard = function () {};
   let streamText = function () {};
@@ -2649,6 +2838,10 @@ export const delete_ai_chat = async function (req) {
       }
     }
 
+    // UI-202: the last row this chat gets. A shared chat is given back rather than deleted,
+    // so the row says which of the two happened.
+    log_chat_activity(uid, conversation_id, 'deleted', { by: 'user', note: conversation_doc.shared_from_uid ? 'the share was given back, so the chat left this account with it' : 'the messages, attachments and picture went with it' }, account_profile_info.app_id);
+
     return save_ret;
   } catch (err) {
     return { code: -3, data: err.message };
@@ -2673,6 +2866,9 @@ export const archive_ai_chat = async function (req) {
     const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, conversation_doc);
     await update_conversation_items_stat(account_profile_info.app_id, 5, conversation_id);
 
+    // UI-202
+    log_chat_activity(uid, conversation_id, 'archived', { by: 'user' }, account_profile_info.app_id);
+
     return save_ret;
   } catch (err) {
     return { code: -3, data: err.message };
@@ -2696,6 +2892,9 @@ export const delete_conversation_item = async function (req) {
     conversation_item_doc.stat = 4;
     conversation_item_doc.ts = Date.now();
     save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, conversation_item_doc);
+    // UI-202: a message leaving a thread is the one edit to a chat that cannot be seen by
+    // reading the thread afterwards, which makes it the row most worth having.
+    log_chat_activity(uid, conversation_item_doc.conversation_id, 'message_deleted', { by: 'user', role: conversation_item_doc.role, preview: String(conversation_item_doc.text || '').replace(/\s+/g, ' ').slice(0, 80) }, account_profile_info.app_id);
     const reference_conversation_id = conversation_doc?.reference_conversation_id || conversation_doc?.conversation_obj?.id;
     const reference_item_id = conversation_item_doc?.conversation_item_reference_id;
     const looksLikeConversationItemId = typeof reference_item_id === 'string' && /^(msg|item)_/.test(reference_item_id);
@@ -2735,6 +2934,9 @@ export const unarchive_ai_chat = async function (req) {
     const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, conversation_doc);
     await update_conversation_items_stat(account_profile_info.app_id, 3, conversation_id);
 
+    // UI-202
+    log_chat_activity(uid, conversation_id, 'unarchived', { by: 'user' }, account_profile_info.app_id);
+
     return save_ret;
   } catch (err) {
     return { code: -3, data: err.message };
@@ -3225,6 +3427,46 @@ const get_user_ai_agents = async function (uid) {
   return await db_module.find_app_couch_query(account_profile_info.app_id, opt);
 };
 
+// UI-187: agent id -> the run currently in flight for it, as {conversation_id, stat, ts}.
+// A conversation is created at stat 1 (initiating), moves to 2 while the answer streams and
+// lands on 3 when it is done, so `stat < 3` IS "this agent is working". When an agent has
+// more than one live run (a chat and a scheduled job, say) the newest wins: the pill says
+// the agent is busy, not how many things it is doing.
+// Never throws. A card without its pill is a smaller failure than an agents list that 500s.
+// A run that never reached stat 3 is not necessarily still going: a conversation abandoned
+// mid-flight, or one whose process died, sits at stat 1 or 2 forever. dev has one that has
+// been "initiating" since 2026-08-02, and without this cap its agent would wear the pill for
+// the rest of time. Two hours is far past any real answer, including the long research runs.
+const LIVE_AGENT_CHAT_MAX_AGE_MS = 2 * 60 * 60 * 1000;
+
+const get_live_agent_conversations = async function (app_id, uid) {
+  const live = new Map();
+  try {
+    const ret = await db_module.find_app_couch_query(app_id, {
+      selector: {
+        docType: 'chat_conversation',
+        uid,
+        reference_type: 'ai_agents',
+        stat: { $lt: 3 },
+      },
+      fields: ['_id', 'reference_id', 'stat', 'ts'],
+      limit: 200,
+    });
+
+    const now = Date.now();
+    for (const doc of ret?.docs || []) {
+      if (!doc.reference_id) continue;
+      if (!doc.ts || now - doc.ts > LIVE_AGENT_CHAT_MAX_AGE_MS) continue;
+      const prev = live.get(doc.reference_id);
+      if (prev && (prev.ts || 0) >= (doc.ts || 0)) continue;
+      live.set(doc.reference_id, { conversation_id: doc._id, stat: doc.stat, ts: doc.ts || 0 });
+    }
+  } catch (err) {
+    console.error(`[get_live_agent_conversations] ${err?.message || err}`);
+  }
+  return live;
+};
+
 export const get_ai_agents = async function (req, job_id, headers) {
   let { uid, _id, search, filter_type = 'all', limit, skip, agent_id, profile_id } = req;
   const account_profile_info = await get_active_account_profile_info(uid, profile_id);
@@ -3404,6 +3646,19 @@ export const get_ai_agents = async function (req, job_id, headers) {
       docs.push(info_doc);
     }
 
+    // UI-187: which of these agents is answering RIGHT NOW, so the card carries the same
+    // Initiating / Streaming pill the chat card does. The dashboard keeps the pill live off
+    // `conversation_doc_updated` once the tab is open; this is what a page LOADED mid-run
+    // needs, otherwise a reload silently drops the pill until the next stat change.
+    // One query rather than one per agent: `stat < 3` is only ever true of a run in flight,
+    // so the result set is a handful of docs even for a busy account, and it runs against the
+    // account's own project db.
+    const live_by_agent = await get_live_agent_conversations(account_profile_info.app_id, uid);
+    for (const doc of docs) {
+      const live = live_by_agent.get(doc._id);
+      if (live) doc.live_chat = live;
+    }
+
     return { code: 8, data: { docs: [...requests_from.docs, ...docs], total_docs: user_agents.total_docs + requests_from.total_docs } };
   } catch (err) {
     return { code: -8, data: err.message };
@@ -3451,6 +3706,17 @@ export const delete_ai_agent = async function (req) {
       }
       delete_depended_chats(uid, agent_id);
     }
+
+    // UI-78: the last row this agent gets. A share is given back rather than deleted, so
+    // the row says which of the two happened.
+    log_agent_activity(
+      uid,
+      agent_id,
+      'deleted',
+      { by: 'user', note: prog_doc.studio_meta.shared_from_uid ? 'the share was given back, so the agent left this account with it' : 'conversations attached to this agent were deleted with it' },
+      account_profile_info.app_id
+    );
+
     return save_ret;
   } catch (err) {
     return { code: -9, data: err.message };
@@ -3473,6 +3739,9 @@ export const uninstall_ai_agent = async function (req) {
 
     const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, agent_doc);
 
+    // UI-78
+    log_agent_activity(uid, agent_id, 'uninstalled', { by: 'user', marketplace_id: agent_doc.studio_meta.installed_marketplace_id }, account_profile_info.app_id);
+
     return save_ret;
   } catch (err) {
     return { code: -9, data: err.message };
@@ -3496,6 +3765,9 @@ export const unarchive_ai_agent = async function (req) {
     const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, agent_doc);
     const updated_conversation_items = await update_conversation_stat(account_profile_info.app_id, agent_id, 3, conversation_id);
 
+    // UI-78
+    log_agent_activity(uid, agent_id, 'unarchived', { by: 'user' }, account_profile_info.app_id);
+
     return { code: 1, data: { save_ret, updated_conversation_items } };
   } catch (err) {
     return { code: -9, data: err.message };
@@ -3583,9 +3855,24 @@ export const generate_ai_agent_image = async function (req, job_id, headers) {
     const agent_doc = await db_module.get_app_couch_doc_native(app_id, agent_id);
     if (!agent_doc || !agent_doc._id) return { code: -404, data: 'agent not found' };
 
-    update_thumbnail('ai_agent', agent_doc, app_id, uid, job_id, headers, null, null, account_profile_info).catch((err) => {
-      console.error('[generate_ai_agent_image]', agent_id, err?.message || err);
-    });
+    // UI-189: generation takes tens of seconds, so it reports through the same
+    // studio_meta.prep state the create/update runner uses and the card shows the same
+    // "Making a picture" progress instead of nothing happening until the picture appears.
+    // UI-78
+    log_agent_activity(uid, agent_id, 'image_requested', { by: 'user' }, app_id);
+
+    (async () => {
+      await set_agent_prep(app_id, agent_id, { stat: 2, step: AGENT_PREP_STEPS.image, done: 0, total: 1, started_ts: Date.now() });
+      try {
+        await update_thumbnail('ai_agent', agent_doc, app_id, uid, job_id, headers, null, null, account_profile_info);
+        log_agent_activity(uid, agent_id, 'image_ready', { by: 'ai', source: 'generated' }, app_id);
+      } catch (err) {
+        console.error('[generate_ai_agent_image]', agent_id, err?.message || err);
+        await set_agent_prep(app_id, agent_id, { failed_step: 'image', failed_reason: String(err?.message || err).slice(0, 200) });
+        log_agent_activity(uid, agent_id, 'image_failed', { by: 'ai', error: String(err?.message || err).slice(0, 200) }, app_id);
+      }
+      await set_agent_prep(app_id, agent_id, { stat: 3, step: null, done: 1, total: 1 });
+    })();
 
     return { code: 1, data: { agent_id, started: true } };
   } catch (err) {
@@ -3610,6 +3897,9 @@ export const archive_ai_agent = async function (req) {
     const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, agent_doc);
     const updated_conversation_items = await update_conversation_stat(account_profile_info.app_id, agent_id, 5, conversation_id);
 
+    // UI-78
+    log_agent_activity(uid, agent_id, 'archived', { by: 'user', conversations: updated_conversation_items ? 'the agent conversations were archived with it' : undefined }, account_profile_info.app_id);
+
     return { code: 1, data: { save_ret, updated_conversation_items } };
   } catch (err) {
     return { code: -9, data: err.message };
@@ -3735,6 +4025,10 @@ export const update_ai_agent = async function (req, job_id, headers) {
   try {
     let agent_doc = await await db_module.get_app_couch_doc_native(account_profile_info.app_id, agent_id);
 
+    // UI-78: taken BEFORE the config is overwritten, so the trail can say what the edit
+    // actually changed rather than "the agent was updated".
+    const config_before = _.cloneDeep(agent_doc.agentConfig || {});
+
     agent_doc.ts = Date.now();
     agent_doc.agentConfig = agentConfig;
 
@@ -3755,14 +4049,30 @@ export const update_ai_agent = async function (req, job_id, headers) {
 
     const data = await db_module.save_app_couch_doc_native(account_profile_info.app_id, agent_doc);
 
-    setTimeout(async () => {
-      await update_ai_agent_properties(agent_doc, account_profile_info.app_id, uid, { name_changed, agent_user_guide_changed, agent_category_changed, agent_subcategory_changed, agent_instructions_changed });
-      if (name_changed) {
-        await update_thumbnail('ai_agent', agent_doc, account_profile_info.app_id, uid, job_id, headers, null, null, account_profile_info);
-      }
-    }, 500);
+    // UI-78: one row per edit, naming the fields that moved and their new values (long
+    // free text travels as a length, see diff_agent_config). An edit that changed nothing,
+    // which is what saving an untouched form is, records nothing: a trail of empty
+    // "updated" rows is exactly what made the doc's own ts useless to read.
+    const { changed, values } = diff_agent_config(config_before, agentConfig);
+    if (changed.length) {
+      log_agent_activity(uid, agent_id, 'updated', { by: 'user', changed, values, previous_name: name_changed ? config_before.agent_name : undefined }, account_profile_info.app_id);
+    }
+
+    // UI-189: an edit does the same work a create does, minus whatever it did not change:
+    // the picture is only regenerated on a rename, and attachments are only read when new
+    // ones were added. Same detached, sequenced runner, same progress on the card.
+    run_agent_preparation({
+      agent_doc,
+      app_id: account_profile_info.app_id,
+      uid,
+      job_id,
+      headers,
+      account_profile_info,
+      agentConfig,
+      with_image: name_changed,
+      fields_changed: { name_changed, agent_user_guide_changed, agent_category_changed, agent_subcategory_changed, agent_instructions_changed },
+    });
 
-    upload_agent_files(uid, agent_doc);
     return { code: 10, data };
   } catch (err) {
     return { code: -10, data: err.message };
@@ -4126,17 +4436,490 @@ const upload_agent_files = async function (uid, agent_doc) {
 //   //         }
 // };
 
+// UI-189: creating an agent is not finished when the save returns. Behind it run the
+// property pass, the picture generation (tens of seconds, and it costs credits) and, when
+// the agent was given attachments, a transcribe-and-upload pass per file. Until all of that
+// lands the agent exists but cannot answer properly: its knowledge is not in its vector
+// store yet and it has no picture. Boaz: "show progress indication and limit the
+// use/selections if it still proceesing".
+//
+// `studio_meta.prep` is that state, and it is deliberately NOT the doc's `stat`: the
+// programs checker already writes stat 2 to mean "this agent has check errors"
+// (controller_module), so overloading it would make the two indistinguishable.
+//   { stat: 2 running | 3 done, step, done, total, started_ts, ts }
+// Every write goes through a fresh read of the doc so it cannot clobber whatever the
+// preparation task itself just saved, and any save puts the doc on the changes feed, which
+// is what pushes `ai_agent_updated` to the dashboard. Never throws: preparation state that
+// fails to record must not take the preparation down with it.
+// Short on purpose. These are rendered inside the card's footer strip, which is ~100px wide
+// on the narrowest agent card, so anything longer truncates to nothing useful ("Reading
+// att..."). The card's tooltip carries the step and its position in the run.
+const AGENT_PREP_STEPS = {
+  properties: 'Setting up',
+  files: 'Reading files',
+  image: 'Making picture',
+};
+
+const set_agent_prep = async function (app_id, agent_id, patch) {
+  try {
+    const doc = await db_module.get_app_couch_doc_native(app_id, agent_id);
+    if (!doc?._id) return;
+    doc.studio_meta = doc.studio_meta || {};
+    doc.studio_meta.prep = { ...(doc.studio_meta.prep || {}), ...patch, ts: Date.now() };
+    doc.ts = Date.now();
+    await db_module.save_app_couch_doc_native(app_id, doc);
+  } catch (err) {
+    console.error(`[set_agent_prep] ${agent_id}: ${err?.message || err}`);
+  }
+};
+
+// Does this agent have attachments still to be read? A tool whose file already carries a
+// file_id was uploaded on an earlier save, so re-saving an agent nobody changed the files of
+// must not claim to be reading them again.
+const agent_has_pending_files = function (agentConfig) {
+  return (agentConfig?.agent_tools || []).some((tool) => {
+    if (tool?.type !== 'file_search') return false;
+    if (!_.isEmpty(tool.file) && !tool.file.file_id) return true;
+    if (!_.isEmpty(tool.youtube) && !tool.youtube.file_id) return true;
+    return false;
+  });
+};
+
+// The one place the post-save work runs, for both create and update. Sequenced rather than
+// fired off in parallel the way it used to be: two chains each doing get-modify-save on the
+// same doc raced (the picture could land on a revision that predated the uploaded file ids
+// and drop them), and a progress indicator can only be honest if it knows what is running.
+// Detached on purpose, the caller returns as soon as the agent exists.
+const run_agent_preparation = async function ({ agent_doc, app_id, uid, job_id, headers, account_profile_info, agentConfig, with_image, fields_changed }) {
+  const tasks = ['properties'];
+  if (agent_has_pending_files(agentConfig)) tasks.push('files');
+  if (with_image) tasks.push('image');
+
+  let done = 0;
+  await set_agent_prep(app_id, agent_doc._id, { stat: 2, step: AGENT_PREP_STEPS[tasks[0]], done, total: tasks.length, started_ts: Date.now() });
+
+  for (const task of tasks) {
+    await set_agent_prep(app_id, agent_doc._id, { stat: 2, step: AGENT_PREP_STEPS[task], done, total: tasks.length });
+    try {
+      // The properties pass records its own row (it is the only place that knows WHICH
+      // fields the AI actually filled in), see update_ai_agent_properties.
+      if (task === 'properties') await update_ai_agent_properties(agent_doc, app_id, uid, fields_changed || {});
+      if (task === 'files') {
+        await upload_agent_files(uid, agent_doc);
+        log_agent_activity(uid, agent_doc._id, 'files_read', { by: 'ai', count: (agentConfig?.agent_tools || []).filter((t) => t?.type === 'file_search').length }, app_id);
+      }
+      if (task === 'image') {
+        await update_thumbnail('ai_agent', agent_doc, app_id, uid, job_id, headers, null, null, account_profile_info);
+        log_agent_activity(uid, agent_doc._id, 'image_ready', { by: 'ai', source: 'generated' }, app_id);
+      }
+    } catch (err) {
+      // One step failing does not strand the agent in "preparing" forever. The rest still
+      // run and the agent opens for use; what failed is recorded on the doc.
+      console.error(`[run_agent_preparation] ${agent_doc._id} ${task}: ${err?.message || err}`);
+      await set_agent_prep(app_id, agent_doc._id, { failed_step: task, failed_reason: String(err?.message || err).slice(0, 200) });
+      // UI-78: and on the trail, which is the only place it survives the next successful
+      // run (set_agent_prep is overwritten, the trail is appended to).
+      log_agent_activity(uid, agent_doc._id, 'preparation_failed', { step: AGENT_PREP_STEPS[task] || task, error: String(err?.message || err).slice(0, 200) }, app_id);
+    }
+    done += 1;
+  }
+
+  await set_agent_prep(app_id, agent_doc._id, { stat: 3, step: null, done, total: tasks.length });
+};
+
+// ─── UI-78: the AI agent activity trail ──────────────────────────────────────────────
+// Same idea as the contact trail (UI-134, account_module) and deliberately the same shape,
+// because it is read by the same panel: the agent doc keeps the CURRENT answer to every
+// question and nothing about how it got there, so "who changed the instructions", "when did
+// this get its picture", "why is this agent public" had no trace to read back.
+//
+// One `agent_activity` doc per event, in the same app db as the agent, keyed on agent_id.
+// Append-only and deliberately silent: failing to WRITE the trail must never fail the action
+// being recorded, so every call is wrapped and logged to the console instead of thrown, and
+// callers do not await it unless they were already awaiting something else on the same line.
+//
+// A SHARED or INSTALLED agent is a copy in the receiver's own app db, so each owner gets
+// their own trail. That is the honest reading: what the sender did to their agent before it
+// was shared is the sender's history, not the receiver's.
+const log_agent_activity = async function (uid, agent_id, event, detail = {}, app_id) {
+  try {
+    if (!uid || !agent_id || !event) return null;
+    const app = app_id || (await get_active_account_profile_info(uid))?.app_id;
+    if (!app) return null;
+
+    return await db_module.save_app_couch_doc_native(app, {
+      _id: await _common.xuda_get_uuid('agent_activity'),
+      docType: 'agent_activity',
+      agent_id,
+      uid,
+      event,
+      // Values the UI prints back verbatim, so keep them short and human. Never put a full
+      // instruction set or a tool payload here: the trail is a summary, not a backup.
+      detail,
+      ts: Date.now(),
+      stat: 3,
+    });
+  } catch (err) {
+    console.error('[ai_module] agent activity not recorded:', event, agent_id, err?.message || err);
+    return null;
+  }
+};
+
+// The cross-module door onto the same helper, for the places that act on an agent from
+// outside ai_module (team_module shares one, marketplace_module installs one). Fire and
+// forget through index_msa, never awaited by those callers.
+export const log_ai_agent_activity = async function (req) {
+  const { uid, agent_id, event, detail, app_id } = req || {};
+  const ret = await log_agent_activity(uid, agent_id, event, detail || {}, app_id);
+  return { code: ret ? 1 : 0, data: ret ? { agent_id, event } : 'not recorded' };
+};
+
+// What an edit actually changed, as a list of field names the UI can print. agentConfig is
+// the whole form the editor posts back, so a naive "the config changed" row says nothing:
+// this compares it field by field against what was stored and keeps the ones that moved.
+// Instructions and the user guide are long free text, so only their LENGTH travels; the
+// point of the row is that they changed and by roughly how much, not to mirror them.
+const AGENT_CONFIG_FIELD_LABELS = {
+  agent_name: 'name',
+  agent_instructions: 'instructions',
+  agent_user_guide: 'user guide',
+  agent_category: 'category',
+  agent_subcategory: 'subcategory',
+  agent_industry: 'industry',
+  agent_tags: 'tags',
+  agent_ai_model: 'model',
+  agent_visibility: 'visibility',
+  agent_price: 'price',
+  agent_tools: 'tools',
+  agent_marketplace_image: 'marketplace image',
+};
+
+const diff_agent_config = function (before = {}, after = {}) {
+  const changed = [];
+  const values = {};
+
+  for (const key of Object.keys(AGENT_CONFIG_FIELD_LABELS)) {
+    const a = before?.[key];
+    const b = after?.[key];
+    if (_.isEqual(a ?? null, b ?? null)) continue;
+    changed.push(AGENT_CONFIG_FIELD_LABELS[key]);
+
+    switch (key) {
+      case 'agent_instructions':
+      case 'agent_user_guide':
+        values[AGENT_CONFIG_FIELD_LABELS[key]] = `${String(a || '').length} to ${String(b || '').length} characters`;
+        break;
+      case 'agent_tools':
+        values.tools = `${(a || []).length} to ${(b || []).length}`;
+        break;
+      case 'agent_tags':
+        values.tags = (b || []).join(', ').slice(0, 120);
+        break;
+      default:
+        values[AGENT_CONFIG_FIELD_LABELS[key]] = String(b ?? '').slice(0, 120);
+        break;
+    }
+  }
+
+  return { changed, values };
+};
+
+// UI-208: an agent edited in STUDIO, which is the one writer that never reaches this module.
+// The Studio client saves its docs straight into CouchDB with no CPI hop, so the only
+// server-side witness is controller_module's changes reader, which sees every revision of
+// every studio doc whoever wrote it. That is also why this cannot simply log what it sees:
+// the same reader watches the revisions ai_module itself produces (the preparation runner
+// alone saves several times per create), and a row per revision would bury the real edits.
+//
+// Two gates, in cost order. First, did the AGENT actually change? Compared against the
+// previous revision out of the version history the same reader captured a line earlier, so
+// a save that only moved preparation state, a picture or a stat writes nothing. Second, did
+// a server path already narrate this edit? Any activity row within the quiet window means
+// yes (update_ai_agent logs before the reader gets there), so only a write that came from
+// outside this module survives to be recorded.
+const STUDIO_EDIT_QUIET_MS = 30 * 1000;
+
+export const record_studio_agent_edit = async function (req) {
+  const { app_id, doc } = req || {};
+  try {
+    if (!app_id || !doc?._id) return { code: 0, data: 'nothing to record' };
+    if (doc.docType !== 'studio' || doc?.properties?.menuType !== 'ai_agent') return { code: 0, data: 'not an agent' };
+    const uid = doc?.studio_meta?.createdByUid || doc.uid;
+    if (!uid) return { code: 0, data: 'no owner on the doc' };
+
+    const prev_ret = await db_module.get_studio_doc_previous_version(app_id, doc._id, doc.ts || Date.now());
+    const prev = prev_ret?.code > 0 ? prev_ret.data : null;
+    // No earlier snapshot means this is the first revision history ever saw, and there is
+    // nothing honest to say about what changed.
+    if (!prev) return { code: 0, data: 'no previous revision to compare' };
+
+    const { changed, values } = diff_agent_config(prev.agentConfig || {}, doc.agentConfig || {});
+    // The name lives on properties, not agentConfig, and renaming in Studio is exactly the
+    // kind of edit somebody later goes looking for.
+    const prev_name = prev?.properties?.menuName;
+    const next_name = doc?.properties?.menuName;
+    if (prev_name !== next_name) {
+      changed.unshift('name');
+      values.name = String(next_name ?? '').slice(0, 120);
+    }
+    if (!changed.length) return { code: 0, data: 'the agent itself did not change' };
+
+    const recent = await db_module.find_app_couch_query(app_id, {
+      selector: { docType: 'agent_activity', agent_id: doc._id },
+      limit: 200,
+    });
+    const cutoff = (doc.ts || Date.now()) - STUDIO_EDIT_QUIET_MS;
+    if ((recent?.docs || []).some((row) => (row.ts || 0) >= cutoff)) return { code: 0, data: 'already recorded by the path that made the change' };
+
+    await log_agent_activity(uid, doc._id, 'updated', { changed, values, previous_name: prev_name !== next_name ? prev_name : undefined, source: 'edited outside the dashboard' }, app_id);
+    return { code: 1, data: { agent_id: doc._id, changed } };
+  } catch (err) {
+    console.error('[record_studio_agent_edit]', doc?._id, err?.message || err);
+    return { code: -1, data: err?.message || String(err) };
+  }
+};
+
+// Reads the trail for one agent, newest first, exactly the way get_contact_activity does:
+// rows the server RECORDED, plus rows reconstructed from the agent doc for everything that
+// happened before the trail existed (which is every agent that already exists today). A
+// derived row carries the closest honest timestamp the doc has, not the real one, and says
+// so, so the panel can mark it as reconstructed rather than observed.
+export const get_ai_agent_activity = async function (req) {
+  const { uid, agent_id, profile_id } = req;
+  try {
+    if (!agent_id) throw new Error('agent_id is missing');
+    const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+
+    // get_app_couch_doc_native throws a bare couch 'missing' for an id that is not in this
+    // account's app db, which is how an id from another account arrives here. Catch it and
+    // answer the question that was actually asked.
+    let agent_doc;
+    try {
+      agent_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, agent_id);
+    } catch (_) {
+      agent_doc = null;
+    }
+    if (!agent_doc || agent_doc.docType !== 'studio' || agent_doc?.properties?.menuType !== 'ai_agent') throw new Error(`agent ${agent_id} not found`);
+
+    const recorded_ret = await db_module.find_app_couch_query(account_profile_info.app_id, {
+      selector: { docType: 'agent_activity', agent_id },
+      limit: 500,
+    });
+    const recorded = (recorded_ret?.docs || []).map((d) => ({ event: d.event, detail: d.detail || {}, ts: d.ts, derived: false }));
+
+    const derived = [];
+    const add = (event, ts, detail) => {
+      if (!ts) return;
+      // A recorded row always wins: it has the real timestamp and the real inputs.
+      if (recorded.some((r) => r.event === event)) return;
+      derived.push({ event, detail, ts, derived: true });
+    };
+
+    const meta = agent_doc.studio_meta || {};
+    const config = agent_doc.agentConfig || {};
+    const created_ts = agent_doc.date_created_ts || meta.date_created_ts || agent_doc.ts;
+
+    add('created', created_ts, { name: agent_doc?.properties?.menuName, model: config.agent_ai_model, tools: (config.agent_tools || []).length, visibility: config.agent_visibility });
+    if (meta.shared_from_uid) add('shared_with_you', meta.shared_ts || created_ts, { from_uid: meta.shared_from_uid, access_type: meta.shared_access_type });
+    if (meta.installed_from_app_id) add('installed', meta.installed_ts || created_ts, { marketplace_id: meta.installed_marketplace_id });
+    if (meta.agent_assistant_name || config.agent_category || config.agent_industry) {
+      add('properties_filled', meta.thumbnail_request_ts || created_ts, { assistant_name: meta.agent_assistant_name, category: config.agent_category, industry: config.agent_industry });
+    }
+    if (meta.agent_image?.length) add('image_ready', meta.thumbnail_request_ts || created_ts, { source: 'generated' });
+    if (meta.prep?.failed_step) add('preparation_failed', meta.prep?.ts || created_ts, { step: meta.prep.failed_step, error: meta.prep.failed_reason });
+    if (meta.pinned) add('pinned', agent_doc.ts || created_ts, {});
+    // stat carries only the LAST transition, which is exactly what the recorded trail adds
+    // from here on: an archive / unarchive history the doc itself cannot hold.
+    if (agent_doc.stat === 5) add('archived', agent_doc.ts, {});
+    if (agent_doc.stat === 4) add('deleted', agent_doc.ts, {});
+
+    // The marketplace listing is the one part of an agent's story that does NOT live in the
+    // app db: publishing writes a marketplace_ai_agent doc in xuda_marketplace, and the
+    // publish gate's verdict lands there too. It carries a real publish_stat_ts, so unlike
+    // most reconstructed rows this one has an honest time. Never fatal: an agent that was
+    // never published has no listing, and a marketplace read that fails is a missing row,
+    // not a failed trail.
+    //
+    // Only for an agent this account actually OWNS. A marketplace install keeps the source
+    // agent's _id, so the listing would be found from the installed copy as well and every
+    // installer would be told they published it. The installed copy already says where it
+    // came from, which is the true thing to say about it.
+    let listing = null;
+    if (!meta.installed_from_app_id && !meta.shared_from_uid) {
+      try {
+        const listing_ret = await db_module.find_couch_query('xuda_marketplace', {
+          selector: { docType: 'marketplace_ai_agent', prog_id: agent_id },
+          limit: 1,
+        });
+        const found = listing_ret?.docs?.[0] || null;
+        // Second guard for the same reason: the listing belongs to whoever published it.
+        if (found && (!found.app_uid || found.app_uid === uid)) listing = found;
+      } catch (err) {
+        console.error('[get_ai_agent_activity] marketplace listing not read:', agent_id, err?.message || err);
+      }
+    }
+    if (listing) {
+      const listing_ts = listing.publish_stat_ts || listing.stat_ts || listing.ts;
+      if (listing.stat === 3) add('published', listing_ts, { category: listing.agent_category, price: listing.price, approved_by: listing.approval?.reviewed_by });
+      if (listing.stat === 6) add('publish_rejected', listing_ts, { reason: listing.publish_reason || (listing.approval?.reasons || []).join('; ') });
+      if (listing.stat === 1 && listing.approval?.status === 'pending') add('publish_review', listing_ts, { reason: listing.publish_reason || (listing.approval?.reasons || []).join('; ') });
+    }
+
+    const rows = [...recorded, ...derived].sort((a, b) => (b.ts || 0) - (a.ts || 0));
+
+    return {
+      code: 1,
+      data: {
+        agent_id,
+        // What the card shows today, so the panel can head the trail with the outcome.
+        current: {
+          name: agent_doc?.properties?.menuName || null,
+          stat: agent_doc.stat,
+          pinned: !!meta.pinned,
+          visibility: config.agent_visibility || null,
+          model: config.agent_ai_model || null,
+          tools: (config.agent_tools || []).length,
+          shared: !!meta.shared_from_uid,
+          installed: !!meta.installed_from_app_id,
+          // null when the agent was never published, so the panel can tell "private" from
+          // "listed and live" from "held by the publish gate".
+          marketplace_stat: listing ? listing.stat : null,
+        },
+        rows,
+      },
+    };
+  } catch (err) {
+    return { code: -25, data: err.message };
+  }
+};
+
+// ─── UI-202: the chat activity trail ──────────────────────────────────────────────────
+// The third of the same family (contacts UI-134, agents UI-210), and deliberately identical
+// in shape because one panel renders all of them. A conversation doc keeps the CURRENT
+// title, category, picture and mood and nothing about when any of them were decided, so
+// "why is this chat called that", "when was it scored red" and "who archived it" had no
+// trace. Message-by-message content is NOT in here: the thread itself is that record. This
+// is what happened TO the chat.
+const log_chat_activity = async function (uid, conversation_id, event, detail = {}, app_id) {
+  try {
+    if (!uid || !conversation_id || !event) return null;
+    const app = app_id || (await get_active_account_profile_info(uid))?.app_id;
+    if (!app) return null;
+
+    return await db_module.save_app_couch_doc_native(app, {
+      _id: await _common.xuda_get_uuid('chat_activity'),
+      docType: 'chat_activity',
+      conversation_id,
+      uid,
+      event,
+      detail,
+      ts: Date.now(),
+      stat: 3,
+    });
+  } catch (err) {
+    console.error('[ai_module] chat activity not recorded:', event, conversation_id, err?.message || err);
+    return null;
+  }
+};
+
+// The cross-module door, for team_module when a chat is shared.
+export const log_ai_chat_activity = async function (req) {
+  const { uid, conversation_id, event, detail, app_id } = req || {};
+  const ret = await log_chat_activity(uid, conversation_id, event, detail || {}, app_id);
+  return { code: ret ? 1 : 0, data: ret ? { conversation_id, event } : 'not recorded' };
+};
+
+export const get_ai_chat_activity = async function (req) {
+  const { uid, conversation_id, profile_id } = req;
+  try {
+    if (!conversation_id) throw new Error('conversation_id is missing');
+    const account_profile_info = await get_active_account_profile_info(uid, profile_id);
+
+    let conversation_doc;
+    try {
+      conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
+    } catch (_) {
+      conversation_doc = null;
+    }
+    if (!conversation_doc || conversation_doc.docType !== 'chat_conversation') throw new Error(`chat ${conversation_id} not found`);
+    if (conversation_doc.uid !== uid && conversation_doc?.account_profile_info?.uid !== uid && conversation_doc?.initiator_uid !== uid) throw new Error('Operation not allowed');
+
+    const recorded_ret = await db_module.find_app_couch_query(account_profile_info.app_id, {
+      selector: { docType: 'chat_activity', conversation_id },
+      limit: 500,
+    });
+    const recorded = (recorded_ret?.docs || []).map((d) => ({ event: d.event, detail: d.detail || {}, ts: d.ts, derived: false }));
+
+    const derived = [];
+    const add = (event, ts, detail) => {
+      if (!ts) return;
+      if (recorded.some((r) => r.event === event)) return;
+      derived.push({ event, detail, ts, derived: true });
+    };
+
+    const created_ts = conversation_doc.date_created_ts || conversation_doc.ts;
+    add('created', created_ts, {
+      type: conversation_doc.conversation_type,
+      model: conversation_doc.model,
+      reference_type: conversation_doc.reference_type,
+      plan_mode: !!conversation_doc.plan_mode,
+      source: conversation_doc.source,
+    });
+    // The title only ever differs from the opening words when the AI named it, which is the
+    // whole reason the row is worth having.
+    if (conversation_doc.title && conversation_doc.prompt && conversation_doc.title !== getFirstNWords(conversation_doc.prompt, 10)) {
+      add('title_set', conversation_doc.ts || created_ts, { by: 'ai', title: conversation_doc.title });
+    }
+    if (conversation_doc?.category_info?.category) add('categorized', conversation_doc.ts || created_ts, { by: 'ai', category: conversation_doc.category_info.category });
+    if (conversation_doc?.chat_image?.length) add('image_ready', conversation_doc.thumbnail_request_ts || created_ts, { by: 'ai' });
+    if (typeof conversation_doc.mood_level === 'number') add('mood_scored', conversation_doc.ts || created_ts, { by: 'ai', mood_level: conversation_doc.mood_level });
+    if (conversation_doc.shared_from_uid) add('shared_with_you', conversation_doc.shared_ts || created_ts, { from_uid: conversation_doc.shared_from_uid });
+    if (conversation_doc.pinned) add('pinned', conversation_doc.ts || created_ts, {});
+    if (conversation_doc.stat === 5) add('archived', conversation_doc.ts, {});
+    if (conversation_doc.stat === 4) add('deleted', conversation_doc.ts, {});
+
+    const rows = [...recorded, ...derived].sort((a, b) => (b.ts || 0) - (a.ts || 0));
+
+    return {
+      code: 1,
+      data: {
+        conversation_id,
+        current: {
+          title: conversation_doc.title || null,
+          stat: conversation_doc.stat,
+          pinned: !!conversation_doc.pinned,
+          type: conversation_doc.conversation_type || null,
+          model: conversation_doc.model || null,
+          category: conversation_doc?.category_info?.category || null,
+          mood_level: typeof conversation_doc.mood_level === 'number' ? conversation_doc.mood_level : null,
+          shared: !!conversation_doc.shared_from_uid,
+        },
+        rows,
+      },
+    };
+  } catch (err) {
+    return { code: -25, data: err.message };
+  }
+};
+
 const save_agent_status = async function (uid, agent_id, stat, agentConfig) {
   // const project_db = await get_account_project_db(uid);
   const account_profile_info = await get_active_account_profile_info(uid);
 
   try {
     let agent_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, agent_id);
+    // UI-204: this rewrites the whole agentConfig from an AI build pass, so it is a real
+    // edit and the trail has to say so. Same diff as the dashboard's own edit, so an agent
+    // the AI rewrote reads exactly like one a person rewrote, minus who did it.
+    const config_before = _.cloneDeep(agent_doc.agentConfig || {});
     agent_doc.ts = Date.now();
     agent_doc.stat = stat;
     agent_doc.agentConfig = agentConfig;
     const data = await db_module.save_app_couch_doc_native(account_profile_info.app_id, agent_doc);
 
+    const { changed, values } = diff_agent_config(config_before, agentConfig);
+    if (changed.length) log_agent_activity(uid, agent_id, 'updated', { by: 'ai', changed, values, note: 'written by the agent builder' }, account_profile_info.app_id);
+
     return { code: 12, data };
   } catch (err) {
     return { code: -12, data: err.message };
@@ -4166,12 +4949,38 @@ export const create_ai_agent = async function (req, job_id, headers) {
     // const data = await db.insert(agent_doc);
 
     const data = await db_module.save_app_couch_doc_native(account_profile_info.app_id, agent_doc);
-    setTimeout(async () => {
-      await update_ai_agent_properties(agent_doc, account_profile_info.app_id, uid);
-      await update_thumbnail('ai_agent', agent_doc, account_profile_info.app_id, uid, job_id, headers, null, null, account_profile_info);
-    }, 500);
 
-    upload_agent_files(uid, agent_doc);
+    // UI-78: the first row of this agent's trail. What it was created AS, so a later
+    // "instructions changed" row has a starting point to be read against.
+    log_agent_activity(
+      uid,
+      agent_doc._id,
+      'created',
+      {
+        by: 'user',
+        name: agentConfig.agent_name,
+        model: agentConfig.agent_ai_model,
+        tools: (agentConfig.agent_tools || []).length,
+        visibility: agentConfig.agent_visibility,
+        instructions_length: String(agentConfig.agent_instructions || '').length,
+      },
+      account_profile_info.app_id
+    );
+
+    // UI-189: a new agent always has all three preparation steps ahead of it. Detached, so
+    // the create call still returns the moment the agent exists; the card shows what is
+    // running and stays un-openable until studio_meta.prep says it is done.
+    run_agent_preparation({
+      agent_doc,
+      app_id: account_profile_info.app_id,
+      uid,
+      job_id,
+      headers,
+      account_profile_info,
+      agentConfig,
+      with_image: true,
+    });
+
     return { code: 13, data };
   } catch (err) {
     return { code: -13, data: err.message };
@@ -4385,26 +5194,37 @@ export const update_ai_agent_properties = async function (doc, app_id, uid, fiel
 
     return ret.data;
   };
+  // UI-78: what this pass DECIDED, not that it ran. The assistant name, category and
+  // industry on the card are written here and nowhere else, so this row is the only answer
+  // to "who chose Fintech". Collected as it goes, because each of the three is conditional:
+  // a pass that only refreshed the assistant name must not claim it picked a category.
+  const filled = {};
+
   if (!db_doc.studio_meta.agent_assistant_name || fields_changed.name_changed || fields_changed.agent_instructions_changed || fields_changed.all) {
     db_doc.studio_meta.agent_assistant_name = await get_agent_assistant_name();
+    filled.assistant_name = db_doc.studio_meta.agent_assistant_name;
   }
   if (!db_doc.agentConfig.agent_category || fields_changed.name_changed || fields_changed.all) {
     db_doc.agentConfig.agent_category = await get_agent_category();
     db_doc.studio_meta.agent_category = db_doc.agentConfig.agent_category;
+    filled.category = db_doc.agentConfig.agent_category;
   }
 
   if (!db_doc.agentConfig.agent_industry || fields_changed.name_changed || fields_changed.all) {
     db_doc.agentConfig.agent_industry = await get_agent_industry();
     db_doc.studio_meta.agent_industry = db_doc.agentConfig.agent_industry;
+    filled.industry = db_doc.agentConfig.agent_industry;
   }
   if (db_doc.agentConfig.agent_user_guide && (fields_changed.agent_user_guide_changed || fields_changed.all)) {
     db_doc.agentConfig.agent_user_guide_fields = await get_agent_user_guide_fields();
     db_doc.studio_meta.agent_user_guide_fields = db_doc.agentConfig.agent_user_guide_fields;
     db_doc.agentConfig.agent_user_guide_steps = await get_agent_user_guide_steps(db_doc.studio_meta.agent_user_guide_fields);
     db_doc.studio_meta.agent_user_guide_steps = db_doc.agentConfig.agent_user_guide_steps;
+    filled.user_guide_form = 'rebuilt from the user guide';
   }
 
   const save_ret = await db_module.save_app_couch_doc_native(app_id, db_doc);
+  if (Object.keys(filled).length) log_agent_activity(uid, db_doc._id, 'properties_filled', { by: 'ai', ...filled }, app_id);
   return save_ret;
 };
 
@@ -5702,6 +6522,16 @@ export const create_conversation = async function (req, job_id, headers) {
     };
     const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, conversation_doc);
 
+    // UI-202: the first row of this chat's trail. What it was opened AS, so the AI's title
+    // and category rows that follow have something to be read against.
+    log_chat_activity(
+      uid,
+      conversation_doc._id,
+      'created',
+      { by: 'user', type: conversation_type, model: ai_model, reference_type, plan_mode: normalize_boolean(plan_mode), attachments: (req.attachments || []).length || undefined },
+      account_profile_info.app_id
+    );
+
     let contact_id, contact_doc, recipient_uid, recipient_contact_id;
 
     if (conversation_doc.reference_type === 'contacts' && conversation_type === 'chat') {
@@ -5791,6 +6621,9 @@ const process_conversation = async function (uid, conversation_id, account_profi
       conversation_doc.title = title.data;
 
       await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+      // UI-202: the chat is renamed from the opening words to whatever the model calls it,
+      // which is the one thing about a chat people ask "where did that come from" about.
+      log_chat_activity(uid, conversation_doc._id, 'title_set', { by: 'ai', title: conversation_doc.title }, account_profile_info.app_id);
     }
   }
   /// categorize prompt
@@ -5834,6 +6667,9 @@ const process_conversation = async function (uid, conversation_id, account_profi
   conversation_doc.category_info = category_info;
   conversation_doc.process_stat = 'full';
   await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+  // UI-202: the category decides which picture the card wears and how the chat is grouped,
+  // and nothing else records that the AI chose it.
+  if (category_info?.category) log_chat_activity(uid, conversation_doc._id, 'categorized', { by: 'ai', category: category_info.category }, account_profile_info.app_id);
 
   //enable_thumbnail_avatar_generation
   const { data: account_doc } = await db_module.get_couch_doc('xuda_accounts', account_profile_info.uid);
@@ -5846,6 +6682,9 @@ const process_conversation = async function (uid, conversation_id, account_profi
   }
 
   await update_thumbnail(thumbnail_type, conversation_doc, account_profile_info.app_id, uid, job_id, headers, null, null, account_profile_info);
+  // UI-202: which of the two pictures the chat got, since the card looks quite different
+  // for a generated title picture and a stock category one.
+  log_chat_activity(uid, conversation_doc._id, 'image_ready', { by: 'ai', source: thumbnail_type === 'conversation_title' ? 'generated from the title' : 'from the category' }, account_profile_info.app_id);
 
   // if ((conversation_type === 'chat' && enable_thumbnail_avatar_generation) || !category_info.category) {
   //   await update_thumbnail('conversation_title', conversation_doc, account_profile_info.app_id, uid, job_id, headers, null, null, account_profile_info);
@@ -6133,8 +6972,15 @@ const update_conversation_mood_level = async function (uid, target_contacts = []
     for await (const target of target_contacts) {
       const account_profile_info = await get_active_account_profile_info(target.uid);
       let conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
+      const previous_mood = conversation_doc.mood_level;
       conversation_doc.mood_level = mood_level_obj.mood_level;
       await db_module.save_app_couch_doc_native(account_profile_info.app_id, conversation_doc);
+      // UI-202: the score that tints the row green or red on the contact timeline, and the
+      // contact card with it. Recorded per SIDE of the exchange, in that side's own app db,
+      // and only when it moved: a run of identical scores says nothing.
+      if (previous_mood !== mood_level_obj.mood_level) {
+        log_chat_activity(target.uid, conversation_id, 'mood_scored', { by: 'ai', mood_level: mood_level_obj.mood_level, previous: typeof previous_mood === 'number' ? previous_mood : undefined }, account_profile_info.app_id);
+      }
 
       if (update_contact) {
         const account_profile_info = await get_active_account_profile_info(target.uid);
@@ -6191,7 +7037,12 @@ const contact_chat_conversation = async function (req, job_id, headers) {
     date_created_ts: Date.now(),
     ts: Date.now(),
     conversation_id,
-    text: body,
+    // `body` does not exist in this scope (the request field is `prompt`), so every
+    // person-to-person send died here with a ReferenceError, AFTER the conversation item
+    // had been written into the OpenAI thread and both conversation docs had been saved.
+    // Found while wiring the inbound-message alert below, which cannot fire from a
+    // function that throws before it reaches it.
+    text: prompt,
     reference_id: conversation_doc.reference_id,
     conversation_item_reference_id,
     direction: 'out',
@@ -6200,6 +7051,20 @@ const contact_chat_conversation = async function (req, job_id, headers) {
 
   const save_ret = await db_module.save_app_couch_doc(sender_app_id, out_conversation_item_obj);
 
+  // UI-193: tell the person on the other end. Fire and forget: an alert that fails must
+  // not fail the message, which is already delivered by this point.
+  notify_chat_message({
+    to_uid: receiver_contact_doc.contact_uid,
+    from_uid: uid,
+    // The recipient's own contact for the SENDER, so the alert wears the face and the name
+    // their address book has for me. Often absent (only a contact_connection request
+    // records it), and chat_message_sender falls back from there.
+    from_contact_id: receiver_contact_doc.connection_contact_id,
+    conversation_id,
+    conversation_doc: receiver_conversation_doc,
+    text: prompt,
+  });
+
   update_conversation_mood_level(uid, conversation_id, prompt, uid, receiver_contact_doc.contact_uid, conversation_doc.reference_type === 'contacts', account_profile_info);
 
   return { code: 15, data: save_ret }; ////item
@@ -8152,16 +9017,18 @@ Available CPI methods: ${cpi_tools_ret.selected_methods.join(', ')}${dashboard_s
       tools: cpi_tools_ret.tools,
     });
 
+    // Running, not Starting: the label stands for the whole call, which for a deck or a video
+    // is a minute and a half. See the matching handler on the chat agent (UI-197).
     agent.on('agent_tool_start', (context, tool) => {
-      emitToDashboard('stream_phase', `Starting ${tool?.name?.replaceAll('_', ' ')} tool`, { update: true });
+      emitToDashboard('stream_phase', `Running ${tool?.name?.replaceAll('_', ' ')}`, { update: true });
     });
 
-    // Without this the phase keeps shimmering "Starting <tool> tool" after the tool has
+    // Without this the phase keeps shimmering "Running <tool>" after the tool has
     // already returned, so a finished deck reads as still being built. done:true settles
     // the line to a checkmark, and it also means the NEXT tool opens its own line instead
     // of overwriting this one, which is how a multi-tool run becomes a readable trail.
     agent.on('agent_tool_end', (context, tool) => {
-      emitToDashboard('stream_phase', `Finished ${tool?.name?.replaceAll('_', ' ')} tool`, { update: true, done: true });
+      emitToDashboard('stream_phase', `Finished ${tool?.name?.replaceAll('_', ' ')}`, { update: true, done: true });
     });
 
     emitToDashboard('stream_phase', 'Submitting dashboard request', { update: true });
@@ -8404,7 +9271,23 @@ export const set_agent_tool_consent = async (req) => {
   }
 };
 
-const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_type, prompt_suggestion_activated, chat_suggestion_activated, gtp_token, uid, account_profile_info, job_id, headers, context, app_id }) {
+const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_type, prompt_suggestion_activated, chat_suggestion_activated, agent_explicitly_selected, gtp_token, uid, account_profile_info, job_id, headers, context, app_id }) {
+  // Does this run get the agent's REAL tools, or only the read-only ones?
+  //
+  // The gate below exists so a plain chat cannot fire an agent's write-capable tools at an
+  // account the user never pointed it at. Three cases always qualified: talking to the agent
+  // directly, a prompt suggestion, a clicked suggestion card. The gap was the fourth, and it
+  // is the one people actually use: turning Agent Mode on and PICKING agents. Every tool the
+  // useful agents own is `plugin` (Presentation Builder is create_pptx + modify_pptx +
+  // read_pptx, all plugin), so a picked agent was marked ineligible, dropped from the handoff
+  // list, and the triage router answered alone with no tools. That is why "Update
+  // /Presentations/deck.pptx: make it fancy" came back as a confident paragraph describing an
+  // edit that never happened: nothing could edit anything.
+  //
+  // Explicitly named agents are the user choosing, exactly like opening the agent's own chat.
+  // Auto mode (an EMPTY ai_agents array, meaning "consider all of them") is NOT a choice and
+  // stays gated, so the safety property the gate was written for survives.
+  const agent_tools_allowed = reference_type === 'ai_agents' || prompt_suggestion_activated || chat_suggestion_activated || agent_explicitly_selected;
   let tools = [];
   let tool_resources = {};
   let eligible_agent = true;
@@ -8414,7 +9297,7 @@ const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_t
   const consent_required = [];
 
   const add_xuda_public_website_tool = function ({ name, description, origin, path_prefix }) {
-    if (reference_type !== 'ai_agents' && !prompt_suggestion_activated && !chat_suggestion_activated) {
+    if (!agent_tools_allowed) {
       eligible_agent = false;
       return;
     }
@@ -8695,7 +9578,7 @@ const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_t
       }
 
       case 'mcp': {
-        if (reference_type !== 'ai_agents' && !prompt_suggestion_activated && !chat_suggestion_activated) {
+        if (!agent_tools_allowed) {
           eligible_agent = false;
           break;
         }
@@ -8716,7 +9599,7 @@ const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_t
       }
 
       case 'cpi': {
-        if (reference_type !== 'ai_agents' && !prompt_suggestion_activated && !chat_suggestion_activated) {
+        if (!agent_tools_allowed) {
           eligible_agent = false;
           break;
         }
@@ -8815,7 +9698,7 @@ const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_t
       }
 
       case 'full_stack_vps': {
-        if (reference_type !== 'ai_agents' && !prompt_suggestion_activated && !chat_suggestion_activated) {
+        if (!agent_tools_allowed) {
           eligible_agent = false;
           break;
         }
@@ -8867,7 +9750,7 @@ const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_t
       }
 
       case 'image_generate': {
-        if (reference_type !== 'ai_agents' && !prompt_suggestion_activated && !chat_suggestion_activated) {
+        if (!agent_tools_allowed) {
           eligible_agent = false;
           break;
         }
@@ -8942,7 +9825,7 @@ const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_t
       }
 
       case 'ai_agent': {
-        if (reference_type !== 'ai_agents' && !prompt_suggestion_activated && !chat_suggestion_activated) {
+        if (!agent_tools_allowed) {
           eligible_agent = false;
           break;
         }
@@ -8962,22 +9845,31 @@ const get_ai_agent_tools = async function ({ ai_agent_doc, agent_id, reference_t
 
         const user_agents = await db_module.find_app_couch_query(ai_agent_doc?.reference_doc?.studio_meta?.shared_from_app_id || ai_agent_doc?.reference_doc?.studio_meta?.installed_from_app_id || app_id, opt);
         for (const agent_doc of user_agents.docs) {
+          // These are studio docs: the name lives on properties.menuName and the prompt on
+          // agentConfig.agent_instructions. Reading the flat agent_name / agent_instructions
+          // off the doc gave undefined, and `undefined.substring(0, 60)` threw. get_agents
+          // catches per agent, so the throw took the WHOLE agent out of the run list and the
+          // turn died with agent_unavailable. Anything reached only from the agent /
+          // suggestion paths, which is the only place this case runs, failed that way.
+          const sub_name = agent_doc.agent_name || agent_doc?.agentConfig?.agent_name || agent_doc?.properties?.menuName || agent_doc._id;
+          const sub_instructions = agent_doc.agent_instructions || agent_doc?.agentConfig?.agent_instructions || '';
+          if (!sub_name) continue;
           const agent = new Agent({
-            name: agent_doc.agent_name.substring(0, 60),
-            instructions: agent_doc.agent_instructions,
+            name: String(sub_name).substring(0, 60),
+            instructions: sub_instructions,
           });
 
           tools.push(
             agent.asTool({
-              toolName: agent_doc.agent_name,
-              toolDescription: agent_doc.agent_instructions,
+              toolName: String(sub_name),
+              toolDescription: sub_instructions,
             }),
           );
         }
         break;
       }
       case 'plugin': {
-        if (reference_type !== 'ai_agents' && !prompt_suggestion_activated && !chat_suggestion_activated) {
+        if (!agent_tools_allowed) {
           eligible_agent = false;
           break;
         }
@@ -9087,6 +9979,12 @@ const ai_chat_conversation = async function (req, job_id, headers) {
   const reference_id = conversation_doc.reference_id;
 
   const activate_prompt_suggestions = _.isArray(local_ai_agents) && conversation_doc.reference_type !== 'ai_agents' && !conversation_item_id;
+  // Did the caller NAME the agents, or just switch Agent Mode on? An empty array means
+  // "consider all of them" (auto), which is not a choice; a populated one is the user picking
+  // specific agents in the composer, and that is what earns those agents their real tools in
+  // an ordinary chat. Read off the raw request value: local_ai_agents is about to be filled
+  // with every agent on the account in the auto case, which would erase the difference.
+  const agent_explicitly_selected = _.isArray(ai_agents) && ai_agents.length > 0;
   let prompt_suggestion_activated;
   let chat_suggestion_activated;
   let model = ai_model;
@@ -9097,8 +9995,14 @@ const ai_chat_conversation = async function (req, job_id, headers) {
   // await _utils.delay(1000);
   const conversation_id = conversation_doc._id;
 
+  // Repair an interrupted turn before reusing the thread. See drop_orphaned_tool_calls: a
+  // function_call left without its output kills the whole conversation permanently. The page is
+  // handed over rather than re-fetched, since it was already being read here for the cursor.
   const prev_conversation_items = await client.conversations.items.list(conversation_doc.reference_conversation_id, { order: 'desc' });
-  const last_conversation_item = prev_conversation_items?.data?.[0]?.id;
+  const surviving_conversation_items = await drop_orphaned_tool_calls(conversation_doc.reference_conversation_id, prev_conversation_items?.data || []);
+  // Read off the SURVIVING items. This id is the `after` cursor for "what did this turn add",
+  // and a cursor pointing at an item we just deleted is not one.
+  const last_conversation_item = surviving_conversation_items?.[0]?.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');
@@ -9297,8 +10201,14 @@ const ai_chat_conversation = async function (req, job_id, headers) {
     emitToDashboard('stream_phase', 'Analyzing request', { update: true });
 
     const init_agent_hooks = function (agent) {
+      // UI-197: the request is away, so stop claiming to be submitting it. Between the submit
+      // and the first token a reasoning model can sit silent for twenty seconds or more, and
+      // for the whole of it the trail used to read "Submitting chat", which describes work
+      // that finished long ago. The next event (a tool starting, or the first chunk) relabels
+      // this same line, so this costs one extra phase and never a stray trail entry.
       agent.on('agent_start', (context, agent) => {
         // emitToDashboard('stream_start');
+        emitToDashboard('stream_phase', 'Thinking', { update: true });
       });
 
       agent.on('agent_end', (context, output) => {
@@ -9310,15 +10220,19 @@ const ai_chat_conversation = async function (req, job_id, headers) {
         emitToDashboard('agent_handoff', nextAgent.name);
       });
 
+      // "Running", not "Starting": this label is what the user looks at for the WHOLE tool
+      // call, and a plugin that generates a video or builds a deck holds it for a minute and a
+      // half. "Starting ..." shimmering for ninety seconds reads as a request that never got
+      // going. The chat now prints how long the step has been running next to it (UI-197).
       agent.on('agent_tool_start', (context, tool, details) => {
         // emitToDashboard('agent_tool_start', tool.name);
-        emitToDashboard('stream_phase', `Starting ${tool?.name?.replaceAll('_', ' ')} tool`, { update: true });
+        emitToDashboard('stream_phase', `Running ${tool?.name?.replaceAll('_', ' ')}`, { update: true });
       });
 
       // See the matching handler on the dashboard agent above: a tool that finished has to
-      // say so, or the phase shimmers "Starting ..." for the rest of the response.
+      // say so, or the phase shimmers "Running ..." for the rest of the response.
       agent.on('agent_tool_end', (context, tool, result, details) => {
-        emitToDashboard('stream_phase', `Finished ${tool?.name?.replaceAll('_', ' ')} tool`, { update: true, done: true });
+        emitToDashboard('stream_phase', `Finished ${tool?.name?.replaceAll('_', ' ')}`, { update: true, done: true });
       });
     };
     const get_agent_instructions = function (is_agent) {
@@ -9345,11 +10259,18 @@ const ai_chat_conversation = async function (req, job_id, headers) {
 
       const triage_assistant = `
     
-    You are Nissim AI Xuda assistant — a smart triage router. 
+    You are Nissim AI Xuda assistant, a smart triage router.
     Your job is to instantly decide who should handle the user's request:
-    - If the question is general or can be answered directly, respond yourself.
-    - If it requires a specific specialist, route it to them.
-    Only fall back to web search as an absolute last resort — never use it unless strictly necessary. 
+    - If a specialist can do it, hand off to them. Do it silently and immediately: transferring
+      IS the answer, so never reply describing the handoff, offering to route, or listing scope
+      options first. The specialist asks its own questions if it needs to.
+    - Only answer yourself when no specialist covers the request and you can settle it from
+      what you already know.
+    - You hold no tools of your own. Anything that has to READ or CHANGE a real thing, a file,
+      a deck, a document, a spreadsheet, a record, or that needs current information from the
+      web, can only be done by a specialist. Saying you have done it is a lie: hand off.
+    - Take the request at face value. If the user asks for a web search, that is not a last
+      resort, it is the request.
 
       ${ai_agents ? 'Never offer suggestions at the end of response' : ''}
 
@@ -9385,8 +10306,18 @@ const ai_chat_conversation = async function (req, job_id, headers) {
             "Hi Sarah! You're Sarah Cohen, our VIP client from Tel Aviv, account #89231. You've been with us since 2022 and usually reach out about trading or portfolio updates. How can I help you today?"
            `.trim();
 
-      return is_agent ? identity : triage_assistant + identity;
+      // UI-196: teach this path the clarifying-questions protocol. The dashboard CPI agent and
+      // the vibe path have spoken it for a while; the chat agents never did, so a Shorts Maker
+      // that needed to know which voice to use printed its five options as a markdown list and
+      // waited for the user to type one back. Appended for the routed agent and the triage
+      // agent alike, since either can be the one that ends up needing to ask.
+      return (is_agent ? identity : triage_assistant + identity) + '\n\n' + CLARIFYING_QUESTIONS_INSTRUCTION;
     };
+    // Display name -> agent DOC id, for the run's own agents. The SDK's Agent keeps only the
+    // fields it declares (name, instructions, handoffs, tools, ...), so the `metadata` we pass
+    // is dropped and `_currentAgent` comes back carrying nothing but the name. This is how the
+    // saved conversation item still records which agent answered by id.
+    const agent_id_by_name = {};
     const get_agents = async function () {
       if (reference_type === 'ai_agents') {
         local_ai_agents = [reference_id];
@@ -9405,9 +10336,13 @@ const ai_chat_conversation = async function (req, job_id, headers) {
       const list = [];
 
       let modelSettings = {};
-      let eligible_agent = true;
 
       for (const agent_id of local_ai_agents) {
+        // Per agent, NOT once for the loop. This used to be declared outside and AND-ed with
+        // each agent's result, so it could only ever go false: the first ineligible agent
+        // dropped every agent after it too, however eligible those were. On an account with a
+        // few agents that silently emptied the handoff list.
+        let eligible_agent = true;
         try {
           let ai_agent_doc = await load_ai_agent_doc(account_profile_info.app_id, agent_id);
 
@@ -9427,6 +10362,7 @@ const ai_chat_conversation = async function (req, job_id, headers) {
             reference_type,
             prompt_suggestion_activated,
             chat_suggestion_activated,
+            agent_explicitly_selected,
             gtp_token,
             uid,
             account_profile_info,
@@ -9440,10 +10376,20 @@ const ai_chat_conversation = async function (req, job_id, headers) {
           eligible_agent = eligible_agent && tools_ret.eligible_agent;
           // if (!tools.length) continue;
           // console.log('tool', tools);
-          // const agent_name = `${ai_agent_doc._id} ${ai_agent_doc?.properties?.menuName || ''}`;
-          const agent_name = `${ai_agent_doc._id}`;
+          // The name is what the ROUTER sees. The SDK builds the handoff tool from it:
+          // `transfer_to_<name>`, described as "Handoff to the <name> agent to handle the
+          // request. <handoffDescription>". Naming it after the doc id gave the router
+          // `transfer_to_agn_102e783c859d` with an empty description, so it had no way to know
+          // one of those ids writes PowerPoint and another searches the web, and it answered
+          // everything itself. Use the agent's own name, and give the SDK the description it
+          // has been appending to nothing. Tool names allow [a-zA-Z0-9_-], so anything else in
+          // a user-chosen name becomes an underscore before the SDK sees it.
+          const agent_display_name = ai_agent_doc?.agentConfig?.agent_name || ai_agent_doc?.reference_doc?.properties?.menuName || ai_agent_doc?.properties?.menuName || '';
+          const agent_name = (agent_display_name.replace(/[^a-zA-Z0-9_-]+/g, '_').replace(/^_+|_+$/g, '') || `${ai_agent_doc._id}`).substring(0, 55);
+          agent_id_by_name[agent_name] = ai_agent_doc?.reference_doc?._id || ai_agent_doc._id;
           const agent = new Agent({
-            name: agent_name.substring(0, 55),
+            name: agent_name,
+            handoffDescription: (ai_agent_doc?.agentConfig?.agent_description || ai_agent_doc?.agentConfig?.agent_instructions || '').slice(0, 300),
             instructions:
               ai_agent_doc.agentConfig.agent_instructions +
               (reference_type === 'ai_agents' ? get_agent_instructions() : '') +
@@ -9599,14 +10545,24 @@ const ai_chat_conversation = async function (req, job_id, headers) {
     }
     ///////////
 
-    if (reference_type === 'ai_agents' || prompt_suggestion_activated || chat_suggestion_activated) {
+    // Picking exactly ONE agent in the composer is the same instruction as opening that
+    // agent's own chat: run it. It used to build a triage router over a list of one, and the
+    // router answered the request itself instead of handing off, so a deliberate
+    // "Update /Presentations/deck.pptx: make it fancy" addressed at Presentation Builder came
+    // back as a paragraph offering to route it, from an agent holding none of the pptx tools.
+    // Several named agents still get a router, because then there IS a routing decision.
+    const run_single_named_agent = agent_explicitly_selected && local_ai_agents.length === 1;
+
+    if (reference_type === 'ai_agents' || prompt_suggestion_activated || chat_suggestion_activated || run_single_named_agent) {
       _agent = agents[0];
       // get_agents() can come back empty (the agent doc failed to load, or every tool it needs
       // is unavailable in this scope). Running with no agent used to throw deep inside the
       // runner and freeze the chat, so fail here with something the user can read.
       if (!_agent) throw 'agent_unavailable';
 
-      set_ts_to_agent();
+      // Only meaningful when the thread IS the agent (it stamps reference_id); on a plain
+      // chat there is no agent doc at reference_id to stamp.
+      if (reference_type === 'ai_agents') set_ts_to_agent();
     } else {
       // 3. Build triage agent that can hand off
       _agent = new Agent({
@@ -9619,13 +10575,25 @@ const ai_chat_conversation = async function (req, job_id, headers) {
       });
     }
 
+    // A clicked suggestion runs ON the thread, so it gets the thread. This used to pass ''
+    // ("no context needed"), which cost it the conversation the user was looking at: picking
+    // "Craft pitch slide" under a Xuda pitch deck produced a generic "Introduction to
+    // PowerPoint Basics" deck because the agent could not see a single earlier message.
+    //
+    // `conversation` and `previous_response_id` are mutually exclusive at the API, and the
+    // SDK only drops previous_response_id when conversationId is TRUTHY while forwarding
+    // `conversation` unconditionally, so the '' also went out ALONGSIDE previous_response_id
+    // and every click came back 400 "Mutually exclusive parameters: ''", surfaced as
+    // "I couldn't complete that just now". Sending the thread fixes both: the response the
+    // suggestion hangs off is already in it. The response id stays only as the fallback for
+    // a thread with no conversation object yet.
     let opt = {
-      conversationId: chat_suggestion_activated ? '' : conversation_doc.reference_conversation_id, // no context needed chat_suggestion_activated
+      conversationId: conversation_doc.reference_conversation_id,
       context,
       stream,
     };
 
-    if (chat_suggestion_activated) {
+    if (chat_suggestion_activated && !opt.conversationId) {
       opt.previousResponseId = conversation_item_doc.conversation_item_reference_id;
     }
 
@@ -9634,6 +10602,30 @@ const ai_chat_conversation = async function (req, job_id, headers) {
     init_agent_hooks(_agent);
     // const output = await runner.run(_agent, prompt, opt);
     const output = await run_agent(_agent, prompt, opt);
+
+    // UI-196: pull the structured clarifying-questions block off the answer, the same protocol
+    // the dashboard CPI agent and the vibe path already use. Until now only those two spoke
+    // it, so an AGENT that needed to ask something wrote its options as a markdown bullet
+    // list ("Available voices you can switch to: alloy, echo, fable...") and the user had to
+    // type one back by hand. The chat already knows how to render a picker for this; the
+    // agent just was never told the protocol. Boaz: "refer to how the questions are prompted
+    // in the aiChat component, so whenever u have a question render it like that".
+    //
+    // Resolved through a function rather than inline here because with `stream: true` the
+    // runner returns as soon as the stream is OPEN: `_currentStep.output` is not the finished
+    // answer until the read loop below has drained it. Called once the text is whole, which
+    // is after that loop, and stream_end then carries the CLEANED prose in `text`:
+    // handleStreamEnd overwrites the visible bubble with it, so the block that was streamed
+    // out chunk by chunk never stays on screen as raw JSON.
+    let final_output_text = '';
+    let chat_questions = null;
+    const resolve_answer = function () {
+      const raw_output_text = output?.state?._currentStep?.output ?? '';
+      const parsed = extract_xuda_questions(raw_output_text);
+      chat_questions = parsed.questions;
+      final_output_text = chat_questions ? parsed.prose || raw_output_text : raw_output_text;
+    };
+
     const done = async function (output) {
       try {
         // const obj = { id: output.state._lastTurnResponse.responseId, ts: Date.now(), ai_agent_id: output.state._currentAgent.name, attachments, conversation_type: 'ai_chat' };
@@ -9663,16 +10655,24 @@ const ai_chat_conversation = async function (req, job_id, headers) {
           date_created_ts: Date.now(),
           ts: Date.now(),
           conversation_id,
-          text: output.state._currentStep.output,
+          // The prose only. The questions ride alongside in their own field so a reload
+          // rebuilds the picker instead of printing the JSON block back into the bubble.
+          text: final_output_text,
           reference_id: conversation_doc.reference_id,
           conversation_item_reference_id: output.state._lastTurnResponse.responseId,
           direction: 'in',
           role: 'assistant',
-          ai_agent_id: output.state._currentAgent.name,
+          // The agent's DOC id, off the metadata stamped when it was built, not its display
+          // name. get_chat_suggestions compares this against agent ids to leave the agent that
+          // just answered out of the next suggestions, and that comparison only worked while
+          // the name happened to BE the id. Falls back to the name for the triage agent, which
+          // has no doc behind it.
+          ai_agent_id: agent_id_by_name[output.state._currentAgent?.name] || output.state._currentAgent.name,
           job_id,
           prompt_conversation_item_id,
           prompt_suggestions,
           prompt_selected_suggestion,
+          ...(chat_questions ? { questions: chat_questions } : {}),
         };
 
         //  if (activate_prompt_suggestions) {
@@ -9747,11 +10747,16 @@ const ai_chat_conversation = async function (req, job_id, headers) {
         stop_abort_watch();
       }
       // console.log('string_debug', string_debug);
-      emitToDashboard('stream_end');
+      resolve_answer();
+      emitToDashboard('stream_end', undefined, chat_questions ? { questions: chat_questions, text: final_output_text } : undefined);
     }
     // else {
     // await update_job('finalizing');
 
+    // Non-streaming runs never reached the resolve above, and `done` persists whatever it
+    // finds in final_output_text, so an empty one would save an empty answer.
+    if (!stream) resolve_answer();
+
     const save_ret = await done(output);
 
     return {
@@ -9773,6 +10778,17 @@ const ai_chat_conversation = async function (req, job_id, headers) {
     const reason = typeof err === 'string' ? err : err?.message || String(err);
     const aborted = reason === 'aborted';
 
+    // The AI PROVIDER's account is out of credit or quota. Worth telling apart from every other
+    // failure, for two reasons. First, "Please try again in a moment" is untrue: a moment will
+    // not fix it, and the card hands the user a Try again button that cannot ever succeed, so
+    // they sit there pressing it. Second, it is not the same thing as the customer running out
+    // of THEIR Xuda credits (validate_credits_limit, checked before the run, with its own
+    // "top up" message), so it must not send them to a billing page that is not the problem.
+    // This is our bill, and the only person who can act on it is whoever owns the platform
+    // account. dev sat on this for an entire session: every chat came back as the generic card
+    // while the log underneath said "You have no credits remaining" 59 times.
+    const provider_out_of_credit = /no credits remaining|insufficient[_ ]quota|exceeded your current quota|billing_hard_limit/i.test(reason);
+
     // A bare stream_end is dropped by the client: handleStreamDelta ignores deltas with no
     // streaming bubble, and handleStreamEnd returns early when that bubble has no text, so the
     // chat keeps ticking on its last phase forever. Open the bubble, say what happened, then
@@ -9787,14 +10803,64 @@ const ai_chat_conversation = async function (req, job_id, headers) {
           response_started
           ? '\n\nStopped.'
           : 'Stopped.'
-        : reason === 'agent_unavailable'
-          ? "This agent isn't available right now. Please try again in a moment."
-          : "I couldn't complete that just now. Please try again in a moment.",
+        : provider_out_of_credit
+          ? // Never the provider's own sentence: it names the vendor and links their billing
+            // page, neither of which is the customer's business or any use to them.
+            'The AI service is unavailable right now. This is a problem on our side, not with your account, and retrying will not help until it is fixed.'
+          : reason === 'agent_unavailable'
+            ? "This agent isn't available right now. Please try again in a moment."
+            : "I couldn't complete that just now. Please try again in a moment.",
     );
     // `aborted` is flagged rather than left undefined so the chat-finished alert can tell
     // a stopped run from a finished one. The client only reads specific keys off params,
-    // so the extra flag changes nothing it renders.
-    emitToDashboard('stream_end', undefined, aborted ? { aborted: true } : { error: true });
+    // so the extra flag changes nothing it renders. `unretryable` is what drops the Try again
+    // button on the error card: offering it for a failure that cannot succeed is worse than
+    // offering nothing, because the user reads the button as "this might work".
+    emitToDashboard('stream_end', undefined, aborted ? { aborted: true } : { error: true, ...(provider_out_of_credit ? { unretryable: true } : {}) });
+
+    // PERSIST the outcome, do not leave it living only on the socket. Everything above is a
+    // websocket push and nothing else: the failure was never written to the thread. So a user
+    // whose socket had dropped, who was on another tab, or who simply reloaded, was left with
+    // their own message and NOTHING under it, which is indistinguishable from a request that
+    // is still thinking. That is exactly what Boaz saw: two prompts, no reply, no error, on a
+    // conversation the server had already closed 4 seconds in.
+    //
+    // Same id the stream used (response_conversation_item_id, already announced on every
+    // emit), so the client's live bubble and the reloaded item are the same message rather
+    // than two. `is_request_error` is what the chat reads to render the error card; a STOPPED
+    // run is not an error, so it keeps the partial answer as an ordinary message, matching
+    // what handleStreamEnd does with the same flags live.
+    //
+    // Its own try/catch: a thread that fails to record a failure must still return the
+    // failure, never a save error thrown from inside the error path.
+    try {
+      await db_module.save_app_couch_doc_native(account_profile_info.app_id, {
+        _id: response_conversation_item_id,
+        stat: 3,
+        docType: 'chat_conversation_item',
+        uid,
+        conversation_type: 'ai_chat',
+        type: 'ai_chat',
+        date_created_ts: Date.now(),
+        ts: Date.now(),
+        conversation_id,
+        // Whatever actually reached the user: on an abort that is the partial answer plus
+        // "Stopped.", on a failure the sentence emitted just above. Built by emitToDashboard
+        // itself, so the stored message cannot drift from the streamed one.
+        text: stream_delta_text,
+        reference_id: conversation_doc.reference_id,
+        direction: 'in',
+        role: 'assistant',
+        job_id,
+        prompt_conversation_item_id,
+        ...(aborted ? { aborted: true } : { is_request_error: true }),
+        // Survives a reload, so a thread reopened tomorrow still shows the card without the
+        // dead button rather than growing one back.
+        ...(provider_out_of_credit ? { unretryable: true } : {}),
+      });
+    } catch (save_err) {
+      console.error('[ai_chat_conversation] failed to persist failure item:', save_err?.message || save_err);
+    }
 
     // Same rule for the HTTP body as for the stream. The raw reason is not safe to hand back:
     // a failed couch call reports the connection string, and that string carries the admin
@@ -10118,6 +11184,15 @@ Do not mention that the reply is automated.
 Use the conversation history for context.
 Return only the email body.`;
 
+    // Same repair the chat path does, for the same reason: this thread is reused on every
+    // incoming message, so one interrupted tool call permanently kills automatic replies to
+    // that contact and nothing here would ever say why. Worse than in the chat, in fact: there
+    // is no person watching to notice it stopped answering and no Retry to press, the replies
+    // just quietly stop. Unlike the chat path there is no item list already in hand, so this
+    // one costs a list call. An auto reply happens once per incoming message, and the price of
+    // skipping it is a contact who never hears back again.
+    await drop_orphaned_tool_calls(contact_doc.contact_reference_conversation_id);
+
     const output = await runner.run(active_agent, prompt, {
       conversationId: contact_doc.contact_reference_conversation_id,
       context,
@@ -10607,7 +11682,11 @@ 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, width = 256, height = 256) {
+// UI-210: `opts.pad` (a 0-1 share, or true for the default) puts the generated subject on a
+// transparent canvas with a margin around it before upload, for callers whose picture is
+// drawn full-bleed and therefore needs the room to be in the artwork. Additive and last, so
+// every existing positional call is untouched.
+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, opts = {}) {
   try {
     // 1. Generate the images
     let result = await create_image(uid, prompt, undefined, undefined, numGenerations, width, height, { drive_type, file_path, file_name }, account_profile_info);
@@ -10627,6 +11706,12 @@ const create_and_upload_image_to_drive = async function (drive_type, file_path,
         data = matches[2];
       }
 
+      // UI-210: opt-in margin around the subject, for pictures drawn full-bleed.
+      if (opts.pad) {
+        data = await pad_transparent_subject(data, typeof opts.pad === 'number' ? { scale: opts.pad } : {});
+        ext = 'png';
+      }
+
       // B. Write to temp file
       const buffer = Buffer.from(data, 'base64');
       const originalname = file_name ? `${file_name}.${ext}` : `generated_${Date.now()}_${index}.${ext}`;
@@ -10772,49 +11857,34 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
   const tempOutputPath = path.join(tempDir, `output_${uniqueId}.png`);
   const { is_user } = metadata;
   let filename = email || _id || name;
-  const inspect_person_in_image = async function (base64) {
-    const ret = await submit_chat_gpt_prompt({
-      uid,
-      model: _conf.default_ai_model,
-      prompt: [
-        {
-          role: 'user',
-          content: [
-            {
-              type: 'input_text',
-              text: `Inspect this profile image. Return whether it contains a real human portrait suitable for an authentic account avatar. Mark it unsuitable if the face is not visible, side-facing, heavily cropped, very blurry, tiny, or not a real person.`,
-            },
-            {
-              type: 'input_image',
-              image_url: `data:image/png;base64,${base64}`,
-            },
-          ],
-        },
-      ],
-      response_format: z.object({
-        is_real_person_in_picture: z.boolean().describe('true if a real human portrait is visible'),
-        is_front_facing: z.boolean().describe('true if the face is mostly front-facing or only slightly angled'),
-        is_face_too_cropped: z.boolean().describe('true if important face/head parts are cut off'),
-        is_too_blurry: z.boolean().describe('true if the face is too blurry for an authentic avatar'),
-        is_too_small: z.boolean().describe('true if the portrait is too small or low-detail'),
-        needs_restoration: z.boolean().describe('true if the photo is old, scanned, scratched, faded, grainy, low-detail, or otherwise degraded such that face-restoration would noticeably improve it'),
-      }),
-      metadata: { _id, func: 'detect_real_person_in_image' },
-      account_profile_info,
-    });
-
-    const res = JSON5.parse(ret.data);
-    return {
-      is_real_person_in_picture: Boolean(res?.is_real_person_in_picture),
-      is_front_facing: Boolean(res?.is_front_facing),
-      is_face_too_cropped: Boolean(res?.is_face_too_cropped),
-      is_too_blurry: Boolean(res?.is_too_blurry),
-      is_too_small: Boolean(res?.is_too_small),
-      needs_restoration: Boolean(res?.needs_restoration),
-    };
+  // inspect_profile_picture tests ret.code before reading it; this one did not.
+  // submit_chat_gpt_prompt reports a FAILED call as
+  // { code: -5, data: err.message }, putting prose in the very field the success
+  // path fills with JSON, so a rate limit or a model hiccup arrived here as a
+  // sentence and JSON5 threw on a word of it. The throw escaped all the way to
+  // get_profile_avatar's outer catch, which turned a transient AI failure into a
+  // dead avatar job reading "JSON5: invalid character 'Y' at 1:5".
+  //
+  // Which way to fail matters more than the guard. The caller sends anything it
+  // reads as not-a-person down the FICTIONAL path, so an all-false default would
+  // answer an AI outage by inventing a face and putting it on a Level 2 account
+  // that has just proved whose face it should be. Not knowing must never mean
+  // "not a person": the photo that reaches here has already passed
+  // inspect_profile_picture in the picture window, which is what establishes
+  // that it IS a photograph of a person. So an unknown verdict falls towards
+  // their own photo, and the worst case becomes a plain cut-out of it.
+  const PERSON_INSPECTION_UNKNOWN = {
+    is_real_person_in_picture: true,
+    is_front_facing: true,
+    is_face_too_cropped: false,
+    is_too_blurry: false,
+    is_too_small: false,
+    // No restoration on a guess: it costs a second image round trip and is only
+    // worth spending on evidence.
+    needs_restoration: false,
   };
 
-  const detect_face_box = async function (base64) {
+  const inspect_person_in_image = async function (base64) {
     try {
       const ret = await submit_chat_gpt_prompt({
         uid,
@@ -10825,32 +11895,44 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
             content: [
               {
                 type: 'input_text',
-                text: `Return the bounding box of the visible face in this portrait, from the top of the head (including hair) to just below the chin, ear to ear. Use normalized coordinates in [0,1] where (0,0) is the top-left corner and (1,1) is the bottom-right corner of the image.`,
+                text: `Inspect this profile image. Return whether it contains a real human portrait suitable for an authentic account avatar. Mark it unsuitable if the face is not visible, side-facing, heavily cropped, very blurry, tiny, or not a real person.`,
+              },
+              {
+                type: 'input_image',
+                image_url: `data:image/png;base64,${base64}`,
               },
-              { type: 'input_image', image_url: `data:image/png;base64,${base64}` },
             ],
           },
         ],
         response_format: z.object({
-          face_top: z.number().min(0).max(1).describe('Top edge of face bbox, normalized'),
-          face_left: z.number().min(0).max(1).describe('Left edge of face bbox, normalized'),
-          face_width: z.number().min(0).max(1).describe('Width of face bbox, normalized'),
-          face_height: z.number().min(0).max(1).describe('Height of face bbox, normalized'),
+          is_real_person_in_picture: z.boolean().describe('true if a real human portrait is visible'),
+          is_front_facing: z.boolean().describe('true if the face is mostly front-facing or only slightly angled'),
+          is_face_too_cropped: z.boolean().describe('true if important face/head parts are cut off'),
+          is_too_blurry: z.boolean().describe('true if the face is too blurry for an authentic avatar'),
+          is_too_small: z.boolean().describe('true if the portrait is too small or low-detail'),
+          needs_restoration: z.boolean().describe('true if the photo is old, scanned, scratched, faded, grainy, low-detail, or otherwise degraded such that face-restoration would noticeably improve it'),
         }),
-        metadata: { _id, func: 'detect_face_box' },
+        metadata: { _id, func: 'detect_real_person_in_image' },
         account_profile_info,
       });
+
+      if (!ret || ret.code < 0) {
+        console.error('inspect_person_in_image failed:', ret?.data);
+        return PERSON_INSPECTION_UNKNOWN;
+      }
+
       const res = JSON5.parse(ret.data);
-      if (!res || typeof res.face_height !== 'number' || res.face_height <= 0) return null;
       return {
-        face_top: Number(res.face_top) || 0,
-        face_left: Number(res.face_left) || 0,
-        face_width: Number(res.face_width) || 0,
-        face_height: Number(res.face_height) || 0,
+        is_real_person_in_picture: Boolean(res?.is_real_person_in_picture),
+        is_front_facing: Boolean(res?.is_front_facing),
+        is_face_too_cropped: Boolean(res?.is_face_too_cropped),
+        is_too_blurry: Boolean(res?.is_too_blurry),
+        is_too_small: Boolean(res?.is_too_small),
+        needs_restoration: Boolean(res?.needs_restoration),
       };
     } catch (err) {
-      console.error('detect_face_box failed:', err.message);
-      return null;
+      console.error('inspect_person_in_image failed:', err.message);
+      return PERSON_INSPECTION_UNKNOWN;
     }
   };
 
@@ -11074,10 +12156,12 @@ export const get_profile_avatar = async function (profile_picture, uid, prompt,
         const can_create_authentic_avatar = source_quality.is_usable && person_inspection.is_real_person_in_picture && !person_inspection.is_too_blurry && !person_inspection.is_too_small;
 
         if (can_create_authentic_avatar) {
-          const face_box = await detect_face_box(imageBase64);
+          // No face box any more. The framing is measured off the cut-out
+          // itself (frameSubjectAsAvatar), so asking a vision model where the
+          // face is bought nothing but a round trip and a number that could be
+          // wrong — and being wrong is what cropped a real avatar's head off.
           imageBase64 = await normalizeAuthenticProfileAvatar(imageBase64, {
             remove_background: !image_blob_ret.is_transparent,
-            face_box,
           });
           avatar_source = 'authentic profile';
         } else {
@@ -11347,6 +12431,9 @@ export const conversation_actions = async function (req, job_id, headers) {
     switch (action) {
       case 'print':
       case 'download': {
+        // UI-202: an answer leaving the chat as a file. Same row for both, because print and
+        // download are the same pdf taking two roads out.
+        log_chat_activity(uid, conversation_id, 'answer_downloaded', { by: 'user', action }, account_profile_info.app_id);
         return {
           code: 20,
           data: '',
@@ -11370,6 +12457,9 @@ export const conversation_actions = async function (req, job_id, headers) {
 
         const drive_ret = await drive_ms.upload_drive_file_user({ uid, path: '/' }, job_id, headers, file_obj);
 
+        // UI-202
+        log_chat_activity(uid, conversation_id, 'answer_saved_to_drive', { by: 'user', filename: originalname }, account_profile_info.app_id);
+
         return {
           code: 20,
           data: drive_ret.data,
@@ -11556,7 +12646,9 @@ const create_ai_agent_image = async function (req, job_id, headers) {
         `;
 
   const generate_faceless = async () => {
-    const images_arr = await create_and_upload_image_to_drive('studio', 'Progs Thumbnails', ai_agent_id, faceless_prompt, 1, uid, app_id, job_id, headers, false, tags, account_profile_info, 1024, 1024);
+    // UI-210: pad, same as the owner-portrait path below. Both end up on the same card,
+    // drawn full-bleed, so both need the room to be in the artwork.
+    const images_arr = await create_and_upload_image_to_drive('studio', 'Progs Thumbnails', ai_agent_id, faceless_prompt, 1, uid, app_id, job_id, headers, false, tags, account_profile_info, 1024, 1024, { pad: true });
     return { code: 1, data: images_arr[0] };
   };
 
@@ -11632,7 +12724,8 @@ const create_ai_agent_image = async function (req, job_id, headers) {
         Use a consistent palette and emphasize intelligence, clarity, and sophistication.
         `;
 
-        const images_arr = await create_and_upload_image_to_drive('studio', 'Progs Thumbnails', ai_agent_id, fallback_prompt, 1, uid, app_id, job_id, headers, false, tags, account_profile_info);
+        // UI-210: the moderation fallback lands on the same card, so it gets the same margin.
+        const images_arr = await create_and_upload_image_to_drive('studio', 'Progs Thumbnails', ai_agent_id, fallback_prompt, 1, uid, app_id, job_id, headers, false, tags, account_profile_info, 1024, 1024, { pad: true });
         report_ai_status(model, err);
         return { code: 1, data: images_arr[0] };
       }
@@ -11641,13 +12734,10 @@ const create_ai_agent_image = async function (req, job_id, headers) {
     }
     imageBase64 = ai_avatar_response.data[0].b64_json;
     account_msa.record_ai_usage(uid, ai_avatar_response.usage.input_tokens, ai_avatar_response.usage.output_tokens, 'agent avatar', prompt, model, { ai_agent_id }, account_profile_info);
+    // UI-210: pad the figure onto its canvas instead of only normalizing the size, so the
+    // card draws it with room around it rather than edge to edge.
     console.log('Normalizing final avatar to 1024 with transparent padding...');
-    imageBase64 = await normalizeBase64To1024(imageBase64);
-
-    //  imageBase64 = await normalizeBase64To1024(imageBase64, {
-    //   fit: 'contain', // Preserve aspect ratio, fit within 211x211
-    //   background: { r: 0, g: 0, b: 0, alpha: 0 }, // Transparent background for padding
-    // });
+    imageBase64 = await pad_transparent_subject(await normalizeBase64To1024(imageBase64));
 
     const outputBuffer = Buffer.from(imageBase64, 'base64');
     const outputPath = tempOutputPath;
@@ -11791,6 +12881,9 @@ export const pin_ai_chat = async function (req) {
 
     const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, conversation_doc);
 
+    // UI-202
+    log_chat_activity(uid, conversation_id, 'pinned', { by: 'user' }, account_profile_info.app_id);
+
     ws_dashboard_msa.emit_message_to_dashboard({
       service: 'ai_chat_pinned',
       to: [uid],
@@ -11816,6 +12909,9 @@ export const unpin_ai_chat = async function (req) {
 
     const save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, conversation_doc);
 
+    // UI-202
+    log_chat_activity(uid, conversation_id, 'unpinned', { by: 'user' }, account_profile_info.app_id);
+
     ws_dashboard_msa.emit_message_to_dashboard({
       service: 'ai_chat_unpinned',
       to: [uid],
@@ -11893,6 +12989,9 @@ export const pin_ai_agent = async function (req, job_id, headers) {
 
     const save_ret = await db_module.save_app_couch_doc(app_id, ai_agent_doc);
 
+    // UI-78
+    log_agent_activity(uid, agent_id, 'pinned', { by: 'user' }, app_id);
+
     ws_dashboard_msa.emit_message_to_dashboard({
       service: 'ai_agent_pinned',
       to: [uid],
@@ -11917,6 +13016,9 @@ export const unpin_ai_agent = async function (req, job_id, headers) {
 
     const save_ret = await db_module.save_app_couch_doc(app_id, ai_agent_doc);
 
+    // UI-78
+    log_agent_activity(uid, agent_id, 'unpinned', { by: 'user' }, app_id);
+
     ws_dashboard_msa.emit_message_to_dashboard({
       service: 'ai_agent_unpinned',
       to: [uid],
@@ -12041,6 +13143,10 @@ export const add_transcript_conversation_item = async function (uid, profile_id,
   try {
     const conversation_item_reference_id = await add_conversation_item(uid, profile_id, conversation_id, `File name: ${filename} with content: ${transcript?.data || transcript || ''}`, conversation_type, reference_id, {});
 
+    // UI-202: a file read into the thread. The message that lands is the transcript, so the
+    // name of the file it came from is only recoverable from here.
+    log_chat_activity(uid, conversation_id, 'transcript_added', { by: 'ai', filename });
+
     report_ai_status('conversations');
     return conversation_item_reference_id;
   } catch (err) {
@@ -12341,81 +13447,78 @@ async function inspectAvatarSourceQuality(base64Image) {
   };
 }
 
+// The avatar spec, in the module's own words. get_profile_avatar states it in
+// the prompt it hands the image model on the fictional path: "person in the
+// center of the picture ... return only a centered head-and-shoulders portrait
+// facing the camera ... add top margin ... the person should cover the whole
+// picture", on a transparent background.
+//
+// That describes the PRODUCT, not one route to it, so this route — which reaches
+// the same result with sharp instead of a model — has to land in the same place.
+// It did not. It framed to a "passport" geometry of its own invention: the head
+// at 62% of the frame, sized and positioned from a vision model's face box, with
+// no margin guaranteed anywhere. Two of the four requirements were missed
+// outright, and when the face box came back short the crop took the crown off
+// the top of a real account's avatar.
+//
+// These two numbers are the "top margin" and a little air at the sides.
+// Everything else the spec asks for — centred, covering the picture,
+// transparent — falls out of the composition rather than being tuned.
+const AVATAR_SIZE = 1024;
+const AVATAR_TOP_MARGIN = 0.06;
+const AVATAR_SIDE_MARGIN = 0.02;
+
+// Frame a background-removed portrait to that spec.
+//
+// Measured from the SUBJECT, never from a face box. The background is already
+// gone by this point, so the cut-out's own bounds say exactly where the person
+// is — no model in the loop, and nothing that can under-report.
+async function frameSubjectAsAvatar(segmentedBuffer) {
+  const bounds = await measureOpaqueBounds(segmentedBuffer);
+  if (!bounds) return sharp(segmentedBuffer).png({ force: true }).toBuffer();
+
+  // The subject's own edges rather than every opaque pixel, on BOTH axes. A
+  // speck above the head shrinks the person to make room for a stray pixel; a
+  // speck beside them widens the frame and pushes them off centre, which breaks
+  // the one requirement that is hardest to notice going wrong.
+  const left = bounds.bodyMinX;
+  const top = bounds.crownY;
+  const subjectW = bounds.bodyMaxX - left + 1;
+  const subjectH = bounds.footY - top + 1;
+  if (subjectW < 2 || subjectH < 2) return sharp(segmentedBuffer).png({ force: true }).toBuffer();
+
+  const subject = await sharp(segmentedBuffer).ensureAlpha().extract({ left, top, width: subjectW, height: subjectH }).png({ force: true }).toBuffer();
+
+  // "cover the whole picture": scaled to fill the frame apart from the margins,
+  // so the person is as large as the spec allows instead of sitting at some
+  // fraction of it. Aspect ratio preserved — the smaller of the two fits wins.
+  const scale = Math.min((AVATAR_SIZE * (1 - AVATAR_SIDE_MARGIN * 2)) / subjectW, (AVATAR_SIZE * (1 - AVATAR_TOP_MARGIN)) / subjectH);
+  const w = Math.max(1, Math.round(subjectW * scale));
+  const h = Math.max(1, Math.round(subjectH * scale));
+  const resized = await sharp(subject).resize(w, h, { fit: 'fill' }).png({ force: true }).toBuffer();
+
+  // Centred left to right, the margin above the crown, the shoulders running to
+  // the bottom edge — which is what head-and-shoulders covering the frame looks
+  // like. The clamp only matters for a subject wider than it is tall.
+  return sharp({ create: { width: AVATAR_SIZE, height: AVATAR_SIZE, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } })
+    .composite([{ input: resized, left: Math.round((AVATAR_SIZE - w) / 2), top: Math.min(Math.round(AVATAR_SIZE * AVATAR_TOP_MARGIN), AVATAR_SIZE - h) }])
+    .png({ force: true })
+    .toBuffer();
+}
+
 async function normalizeAuthenticProfileAvatar(base64Image, options = {}) {
-  const { remove_background = true, face_box = null } = options;
+  const { remove_background = true } = options;
   const inputBuffer = Buffer.from(base64Image, 'base64');
   const orientedBuffer = await sharp(inputBuffer).rotate().png({ force: true }).toBuffer();
-  const orientedMeta = await sharp(orientedBuffer).metadata();
   const segmentedBuffer = remove_background ? await removePortraitBackground(orientedBuffer) : orientedBuffer;
 
-  const passportBuffer = face_box ? await cropToPassportFrame(segmentedBuffer, face_box, orientedMeta) : await cropToOpaqueBounds(segmentedBuffer);
+  const framedBuffer = await frameSubjectAsAvatar(segmentedBuffer);
 
-  const subjectBuffer = await sharp(passportBuffer).modulate({ brightness: 1.02, saturation: 1.04 }).sharpen({ sigma: 0.35, m1: 0.4, m2: 0.2 }).png({ quality: 98, compressionLevel: 8, force: true }).toBuffer();
+  const subjectBuffer = await sharp(framedBuffer).modulate({ brightness: 1.02, saturation: 1.04 }).sharpen({ sigma: 0.35, m1: 0.4, m2: 0.2 }).png({ quality: 98, compressionLevel: 8, force: true }).toBuffer();
 
   return subjectBuffer.toString('base64');
 }
 
-async function cropToPassportFrame(segmentedBuffer, face_box, sourceMeta) {
-  const segmentedMeta = await sharp(segmentedBuffer).metadata();
-  const sourceW = segmentedMeta.width || sourceMeta.width || 0;
-  const sourceH = segmentedMeta.height || sourceMeta.height || 0;
-  if (!sourceW || !sourceH) return cropToOpaqueBounds(segmentedBuffer);
-
-  const faceCenterX = (face_box.face_left + face_box.face_width / 2) * sourceW;
-  const faceCenterY = (face_box.face_top + face_box.face_height / 2) * sourceH;
-  const faceHeightPx = face_box.face_height * sourceH;
-  if (!(faceHeightPx > 4)) return cropToOpaqueBounds(segmentedBuffer);
-
-  const faceFraction = 0.62;
-  const frameSize = Math.max(8, Math.round(faceHeightPx / faceFraction));
-  const verticalAnchor = 0.42;
-  const cropLeft = Math.round(faceCenterX - frameSize / 2);
-  const cropTop = Math.round(faceCenterY - frameSize * verticalAnchor);
-
-  const padLeft = Math.max(0, -cropLeft);
-  const padTop = Math.max(0, -cropTop);
-  const padRight = Math.max(0, cropLeft + frameSize - sourceW);
-  const padBottom = Math.max(0, cropTop + frameSize - sourceH);
-
-  let workingBuffer = segmentedBuffer;
-  if (padLeft || padTop || padRight || padBottom) {
-    workingBuffer = await sharp(segmentedBuffer)
-      .ensureAlpha()
-      .extend({
-        left: padLeft,
-        top: padTop,
-        right: padRight,
-        bottom: padBottom,
-        background: { r: 0, g: 0, b: 0, alpha: 0 },
-      })
-      .png({ force: true })
-      .toBuffer();
-  }
-
-  const workingMeta = await sharp(workingBuffer).metadata();
-  const wW = workingMeta.width || 0;
-  const wH = workingMeta.height || 0;
-
-  const wantLeft = cropLeft + padLeft;
-  const wantTop = cropTop + padTop;
-  const extractLeft = Math.max(0, Math.min(Math.max(0, wW - 1), wantLeft));
-  const extractTop = Math.max(0, Math.min(Math.max(0, wH - 1), wantTop));
-  const extractWidth = Math.max(1, Math.min(wW - extractLeft, frameSize));
-  const extractHeight = Math.max(1, Math.min(wH - extractTop, frameSize));
-
-  if (extractWidth <= 0 || extractHeight <= 0) {
-    console.warn('cropToPassportFrame: degenerate extract region, falling back', { sourceW, sourceH, frameSize, cropLeft, cropTop, wW, wH });
-    return cropToOpaqueBounds(segmentedBuffer);
-  }
-
-  const framed = await sharp(workingBuffer).extract({ left: extractLeft, top: extractTop, width: extractWidth, height: extractHeight }).png({ force: true }).toBuffer();
-
-  return sharp(framed)
-    .resize(1024, 1024, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
-    .png({ force: true })
-    .toBuffer();
-}
-
 async function removePortraitBackground(inputBuffer) {
   const orientedBuffer = await sharp(inputBuffer).rotate().png({ force: true }).toBuffer();
   const inputBlob = new Blob([orientedBuffer], { type: 'image/png' });
@@ -12429,9 +13532,11 @@ async function removePortraitBackground(inputBuffer) {
   return Buffer.from(await outputBlob.arrayBuffer());
 }
 
-async function cropToOpaqueBounds(inputBuffer) {
-  const image = sharp(inputBuffer).ensureAlpha();
-  const { data, info } = await image.raw().toBuffer({ resolveWithObject: true });
+// Where the cut-out subject actually sits inside the frame. Shared by the two
+// framing routes: one crops to it, the other takes only its TOP edge, which on a
+// portrait whose background has been removed is the crown of the head.
+async function measureOpaqueBounds(inputBuffer) {
+  const { data, info } = await sharp(inputBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
   const { width, height, channels } = info;
   const alphaThreshold = 8;
 
@@ -12439,31 +13544,68 @@ async function cropToOpaqueBounds(inputBuffer) {
   let minY = height;
   let maxX = -1;
   let maxY = -1;
+  const rowCounts = new Int32Array(height);
+  const colCounts = new Int32Array(width);
 
   for (let y = 0; y < height; y++) {
+    let count = 0;
     for (let x = 0; x < width; x++) {
       const alpha = data[(y * width + x) * channels + (channels - 1)];
       if (alpha > alphaThreshold) {
+        count++;
+        colCounts[x]++;
         if (x < minX) minX = x;
         if (x > maxX) maxX = x;
         if (y < minY) minY = y;
         if (y > maxY) maxY = y;
       }
     }
+    rowCounts[y] = count;
   }
 
-  if (maxX < 0 || maxY < 0) {
-    return sharp(inputBuffer).png({ force: true }).toBuffer();
-  }
+  if (maxX < 0 || maxY < 0) return null;
+
+  // The PERSON, as distinct from every opaque pixel. Segmenters leave specks,
+  // and one stray pixel in a corner puts "the top of the head" in the sky, or
+  // widens the subject so the person sits off-centre inside their own frame.
+  // A body is substantial along a row and a column where a speck is not, so each
+  // edge is the first line carrying real extent — measured against the largest
+  // line of this same subject, which needs no outside estimate of how big the
+  // person is.
+  let widestRow = 0;
+  for (let y = minY; y <= maxY; y++) if (rowCounts[y] > widestRow) widestRow = rowCounts[y];
+  let tallestCol = 0;
+  for (let x = minX; x <= maxX; x++) if (colCounts[x] > tallestCol) tallestCol = colCounts[x];
+
+  const rowFloor = Math.max(4, Math.round(widestRow * 0.08));
+  // Looser on the vertical than on the horizontal, deliberately. The outermost
+  // COLUMNS of a real silhouette are genuinely short — the outer edge of a
+  // shoulder is a few dozen pixels tall — so the row threshold applied here
+  // would shave the person's shoulders off.
+  const colFloor = Math.max(4, Math.round(tallestCol * 0.02));
 
-  const padX = Math.round((maxX - minX + 1) * 0.04);
-  const padY = Math.round((maxY - minY + 1) * 0.04);
-  const cropLeft = Math.max(0, minX - padX);
-  const cropTop = Math.max(0, minY - padY);
-  const cropWidth = Math.min(width - cropLeft, maxX - minX + 1 + padX * 2);
-  const cropHeight = Math.min(height - cropTop, maxY - minY + 1 + padY * 2);
+  const firstIndex = (counts, from, to, floor) => {
+    for (let i = from; i <= to; i++) if (counts[i] >= floor) return i;
+    return from;
+  };
+  const lastIndex = (counts, from, to, floor) => {
+    for (let i = to; i >= from; i--) if (counts[i] >= floor) return i;
+    return to;
+  };
 
-  return sharp(inputBuffer).ensureAlpha().extract({ left: cropLeft, top: cropTop, width: cropWidth, height: cropHeight }).png({ force: true }).toBuffer();
+  return {
+    minX,
+    minY,
+    maxX,
+    maxY,
+    // The subject's own edges, specks excluded. crownY is the top of the head.
+    crownY: firstIndex(rowCounts, minY, maxY, rowFloor),
+    footY: lastIndex(rowCounts, minY, maxY, rowFloor),
+    bodyMinX: firstIndex(colCounts, minX, maxX, colFloor),
+    bodyMaxX: lastIndex(colCounts, minX, maxX, colFloor),
+    width,
+    height,
+  };
 }
 
 async function restoreFaceWithOpenAI(base64Image, ctx = {}) {
@@ -12501,6 +13643,75 @@ async function restoreFaceWithOpenAI(base64Image, ctx = {}) {
   return outBase64;
 }
 
+// UI-210: put the agent's portrait on its canvas with room around it.
+//
+// Boaz: "i didnt asked to shrink the big avatar instead recreated with padding". The
+// generated portrait filled its 1024 frame edge to edge, and the card draws it at
+// width:100% anchored to the bottom, so the figure ran from under the title straight into
+// the footer strip and read as a crop. Scaling it down in CSS was the wrong answer: that
+// leaves a hard-edged picture floating in the card's gradient. The margin belongs in the
+// artwork, so the file itself has space around the figure and still fills the card.
+//
+// trim() first, deliberately: the model leaves an arbitrary transparent border of its own,
+// so measuring the margin from the raw frame would give a different result every
+// generation. Trimming to the FIGURE and then padding to a fixed share makes every agent
+// picture sit the same way.
+//
+// Never throws. A picture with no padding is a cosmetic miss; losing the picture is not.
+const pad_transparent_subject = async function (base64, { canvas = 1024, scale = 0.78 } = {}) {
+  try {
+    const input = Buffer.from(base64, 'base64');
+
+    // UI-210: an OPAQUE render must not be padded. edit_image_transparent degrades to an
+    // opaque image whenever the model refuses `background: 'transparent'` (UI-138), and
+    // that render is a full rectangle of artwork with its own backdrop. Compositing it onto
+    // a transparent canvas would leave a hard-edged photo floating in the middle of the
+    // card with see-through margins around it, which looks far worse than the edge-to-edge
+    // framing this exists to fix. The padding only makes sense for a cutout.
+    const meta_in = await sharp(input).metadata();
+    if (!meta_in.hasAlpha) {
+      console.log('[pad_transparent_subject] opaque render, leaving it edge to edge');
+      return base64;
+    }
+    const { data: alpha, info: alpha_info } = await sharp(input).ensureAlpha().extractChannel('alpha').raw().toBuffer({ resolveWithObject: true });
+    let clear = 0;
+    for (let i = 0; i < alpha.length; i++) if (alpha[i] < 8) clear++;
+    // A real cutout leaves a good share of the frame empty. Anything below this is a
+    // near-opaque render with at most a stray soft edge, so treat it as opaque.
+    if (clear / (alpha_info.width * alpha_info.height) < 0.05) {
+      console.log('[pad_transparent_subject] no usable cutout, leaving it edge to edge');
+      return base64;
+    }
+
+    let trimmed = input;
+    try {
+      trimmed = await sharp(input).trim().png().toBuffer();
+    } catch (err) {
+      // Nothing to trim: pad the original instead.
+    }
+
+    const inner = Math.max(1, Math.round(canvas * scale));
+    const resized = await sharp(trimmed)
+      .resize(inner, inner, { fit: 'inside', withoutEnlargement: false, background: { r: 0, g: 0, b: 0, alpha: 0 } })
+      .png()
+      .toBuffer();
+
+    const meta = await sharp(resized).metadata();
+    const left = Math.max(0, Math.round((canvas - (meta.width || inner)) / 2));
+    const top = Math.max(0, Math.round((canvas - (meta.height || inner)) / 2));
+
+    const out = await sharp({ create: { width: canvas, height: canvas, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } })
+      .composite([{ input: resized, left, top }])
+      .png({ quality: 98, compressionLevel: 8, force: true })
+      .toBuffer();
+
+    return out.toString('base64');
+  } catch (err) {
+    console.error(`[pad_transparent_subject] ${err?.message || err}`);
+    return base64;
+  }
+};
+
 async function normalizeBase64To1024(
   base64Image,
   resize = {
@@ -18525,9 +19736,21 @@ export const update_widget_settings = async function (req) {
         if (config[key] === '') delete doc.widget_config[key];
       }
     }
+    const was_enabled = !!doc.widget_enabled;
     doc.ts = Date.now();
     await db_module.save_app_couch_doc_native(account_profile_info.app_id, doc);
 
+    // UI-204: the chat widget is a PUBLIC surface of this profile, and it is written here
+    // rather than through update_account_profile, so the profile trail never saw it. On or
+    // off is the part worth reading back; the styling changes travel as "settings changed".
+    account_msa.log_account_profile_activity({
+      uid,
+      app_id: account_profile_info.app_id,
+      profile_id: account_profile_info.account_profile_id,
+      event: typeof enabled === 'boolean' && enabled !== was_enabled ? (enabled ? 'widget_on' : 'widget_off') : 'widget_settings',
+      detail: { by: 'user' },
+    });
+
     return await get_widget_settings({ uid, profile_id });
   } catch (err) {
     return { code: -1, data: err.message || String(err) };
@@ -18648,9 +19871,21 @@ export const update_contact_form_settings = async function (req) {
         if (config[key] === '') delete doc.contact_form_config[key];
       }
     }
+    const was_enabled = !!doc.contact_form_enabled;
     doc.ts = Date.now();
     await db_module.save_app_couch_doc_native(account_profile_info.app_id, doc);
 
+    // UI-204: same as the widget. The contact form is public and is written straight onto
+    // the profile doc, so without this the profile trail could not answer "when did this
+    // start accepting messages from strangers".
+    account_msa.log_account_profile_activity({
+      uid,
+      app_id: account_profile_info.app_id,
+      profile_id: account_profile_info.account_profile_id,
+      event: typeof enabled === 'boolean' && enabled !== was_enabled ? (enabled ? 'contact_form_on' : 'contact_form_off') : 'contact_form_settings',
+      detail: { by: 'user' },
+    });
+
     return await get_contact_form_settings({ uid, profile_id });
   } catch (err) {
     return { code: -1, data: err.message || String(err) };