shakers-cli 0.16.0 → 0.18.0

package/src/mcp-register-tools.js

@@ -2,10 +2,11 @@
 
 const { TranscriptBuffer } = require('./interview-transcript');
 const path = require('path');
-const { askChoice, askConsent } = require('./mcp-choice');
+const { askChoice, askConsent, forChat, handOver, settle, withNextSay } = require('./mcp-choice');
 const { expandHome, tildify } = require('./env-paths');
 
 const ANSWER_MODES = ['drafted', 'own', 'full'];
+const WHERE_QUESTION = 'interview:where';
 
 const INTERVIEW_START_SCHEMA = {
   type: 'object',
@@ -123,10 +124,14 @@ function makeRegisterTools(deps = {}) {
     return { ok: false, reason: 'interview-later', message: 'The talent does the interview later on the web: skip it here and go on with the main role, then open_web.' };
   }
 
+  // The talent's answer to the interview disclaimers counts only after they went to the chat with the answer-mode question.
+  let disclaimersShown = false;
+
   async function askWhere(args, ctx) {
+    const c = copy();
+    if (args.where === 'here' || args.where === 'later') settle(WHERE_QUESTION, args.where === 'here' ? c.interviewHere : c.interviewLater);
     if (args.where === 'here') return { here: true };
     if (args.where === 'later') return { here: false };
-    const c = copy();
     const asked = await askChoice(ctx, { question: c.interviewWhereQuestion, options: [c.interviewHere, c.interviewLater] });
     if (asked.answer) return { here: asked.answer === c.interviewHere };
     return { chat: asked.chat, dismissed: asked.dismissed };
@@ -160,30 +165,35 @@ function makeRegisterTools(deps = {}) {
     if (!CHAT_INTERVIEW_LANGUAGES.has(textLang())) {
       return { ok: false, reason: 'interview-on-web', relayVerbatim: copy().interviewOnWeb, message: 'Print relayVerbatim word for word now. The interview is not offered here in this language: skip it, go on with the main role, then open_web.' };
     }
-    const acknowledged = args.disclaimerAcknowledged === true;
+    const acknowledged = args.disclaimerAcknowledged === true && disclaimersShown;
+    // One acknowledgement per interview: the next one shows its disclaimers again.
+    if (acknowledged) disclaimersShown = false;
     if (!acknowledged) {
       track(() => funnel.viewed('pre_interview'));
       const where = await askWhere(args, ctx);
       if (where.here === false) return interviewLater();
       if (where.chat) {
-        return {
+        // "Here" leads to the answer-mode question, whose disclaimers go to the model now.
+        const disclaimers = handOver(WHERE_QUESTION, { step: 'interview', ifAnswer: [copy().interviewHere], texts: Object.values(flow.interviewDisclaimers(textLang())) });
+        return withNextSay({
           ok: false,
           reason: 'where-required',
           ...(where.dismissed ? { dismissed: where.dismissed } : {}),
-          ...where.chat,
+          ...forChat(where.chat),
           message: `${where.chat.choiceMessage} Then call onboarding_interview_start again with where:"here" for the first option or where:"later" for the second.`,
-        };
+        }, disclaimers);
       }
     }
     // The two disclaimers travel with the answer-mode question, so they are read before the talent answers it.
     const disclaimers = acknowledged ? [] : Object.values(flow.interviewDisclaimers(textLang()));
     const answer = await askAnswerMode(acknowledged ? args : {}, ctx, disclaimers);
     if (answer.chat) {
+      if (disclaimers.length) disclaimersShown = true;
       return {
         ok: false,
         reason: 'answer-mode-required',
         ...(answer.dismissed ? { dismissed: answer.dismissed } : {}),
-        ...answer.chat,
+        ...forChat(answer.chat),
         message: `${answer.chat.choiceMessage} Then call onboarding_interview_start again with where:"here", disclaimerAcknowledged:true and answerMode: drafted for the first option, own for the second, full for the third.`,
       };
     }
@@ -283,7 +293,7 @@ function makeRegisterTools(deps = {}) {
       return { ok: false, reason: 'unknown-interview', message: 'No live interview for that interviewId (the server may have restarted). Nothing to complete; start again if the talent still wants the interview.' };
     }
     const saved = await teardownInterview(args.interviewId, { persist: true });
-    if (!saved.ok) return { ok: false, reason: saved.reason || 'complete-failed' };
+    if (!saved.ok) return { ok: false, reason: saved.reason || 'complete-failed', message: 'The interview could not be saved: it stays pending and the talent can take it later on the web. Do not retry it; go on with the main role (list_my_roles, then set_main_role).' };
     lastCompletedInterview = { interviewId: args.interviewId, completedAt: Date.now() };
     track(() => funnel.completed('interview', { interview_mode: 'text' }));
     return { ok: true, state: 'taken', message: catalog.interviewComplete };
@@ -325,7 +335,7 @@ function makeRegisterTools(deps = {}) {
   // Content-free context the model may PROPOSE to the talent (never auto-write), searched only after the talent says yes.
   async function suggestContext(args = {}, ctx = {}) {
     const c = copy().consent;
-    const asked = await askConsent(ctx, { tool: 'suggest_register_context', key: 'suggest_register_context', question: c.cvSearch, yes: c.yes, no: c.no, answer: args.answer });
+    const asked = await askConsent(ctx, { tool: 'suggest_register_context', key: 'suggest_register_context', question: c.cvSearch, yes: c.cvSearchYes, no: c.no, answer: args.answer });
     if (asked.reply) return asked.reply;
     if (!asked.granted) return { ok: false, reason: 'consent-declined', message: 'The talent said no: nothing was searched. Do not look for the CV on this computer; ask them to attach it in the chat.' };
     const read = deps.readRegisterContextSuggestions || require('./register-context').readRegisterContextSuggestions;
@@ -346,11 +356,12 @@ function makeRegisterTools(deps = {}) {
     if (typeof args.path !== 'string' || !args.path.trim()) return { ok: false, reason: 'cv-not-found', message: 'Pass the path of the CV file.' };
     const file = path.resolve(expandHome(args.path.trim()));
     const c = copy().consent;
-    const asked = await askConsent(ctx, { tool: 'read_cv', key: `read_cv:${file}`, question: c.cvRead(tildify(file)), yes: c.yes, no: c.no, answer: args.answer });
+    const asked = await askConsent(ctx, { tool: 'read_cv', key: `read_cv:${file}`, question: c.cvRead(tildify(file)), yes: c.cvReadYes(path.basename(file)), no: c.no, answer: args.answer });
     if (asked.reply) return asked.reply;
     if (!asked.granted) return { ok: false, reason: 'consent-declined', message: 'The talent said no: the file was not read. Do not read it; ask them to attach their CV in the chat or tell you what it says.' };
     const read = deps.readCvText || require('./cv-text').readCvText;
     const result = read(file, { talentName: args.talentName });
+    if (!result.ok && result.reason === 'not-found') return { ...result, message: 'That file is not on this computer. If the talent attached their CV to this chat, use the text you see there: in the sign-up pass it as cvText to signup_start, with the answer they gave. Never run commands, code or other tools to read an attached file.' };
     if (!result.ok) return { ...result, message: 'Could not read the CV text here. Ask the talent to attach the CV to the chat, or to tell you what it says.' };
     // Someone else's CV (a candidate they downloaded): never hand its contents over.
     if (result.mentionsTalent === false) return { ok: true, mentionsTalent: false, note: "This CV does not name the talent: it belongs to someone else. Do not use, quote or describe it; try the next candidate." };
@@ -362,7 +373,7 @@ function makeRegisterTools(deps = {}) {
       name: 'suggest_register_context',
       title: 'Look for your CV on this computer',
       description: 'Asks you first, then lists the names of PDF and Word files in your Desktop, Documents, Downloads and iCloud Drive folders that look like a CV and reads your time zone and the name, email and GitHub user saved by your coding tools. It does not open those files or send anything.',
-      guidance: "SUGGESTIONS for the sign-up read on this machine (no network, no file contents): timezone, git name/email, the gh CLI GitHub login, and cvCandidates: PDF/DOC/DOCX files in Desktop, Documents, Downloads and iCloud Drive whose NAME looks like a CV or carries the talent's name, each with nameMatch (null when their name is unknown) and generic flags. A candidate is only a lead (people who hire keep other people's CVs): confirm it with read_cv. Pass talentName to sharpen the match. The tool asks the talent first (a dialog when the client has one, otherwise it returns `say` to print word for word as your whole reply); nothing is searched until they answer yes. After a `say`, call it again with answer set to the option they pick. Never answer for them.",
+      guidance: "SUGGESTIONS for the sign-up read on this machine (no network, no file contents): timezone, git name/email, the gh CLI GitHub login, and cvCandidates: PDF/DOC/DOCX files in Desktop, Documents, Downloads and iCloud Drive whose NAME looks like a CV or carries the talent's name, each with nameMatch (null when their name is unknown) and generic flags. A candidate is only a lead (people who hire keep other people's CVs): confirm it with read_cv. Pass talentName to sharpen the match. The tool asks the talent first (a dialog when the client has one, otherwise it returns the question to ask as its message says); nothing is searched until they answer yes. After asking it in the chat, call it again with answer set to the option they pick. Never answer for them.",
       inputSchema: { type: 'object', properties: { talentName: { type: 'string', description: "The talent's full name as you know it (memory, chat); improves CV matching." }, answer: { type: 'string', description: 'The option the talent picked when you printed the question this tool returned. Never set it yourself.' } } },
       handler: suggestContext,
     },
@@ -370,7 +381,7 @@ function makeRegisterTools(deps = {}) {
       name: 'read_cv',
       title: 'Read your CV',
       description: 'Asks you first, then reads the text of the CV file you allow to prepare your profile draft. This step sends nothing to Shakers.',
-      guidance: "Read the TEXT of a CV file (PDF, DOC, DOCX) on this machine, with talentName set. The tool asks the talent first, naming the file (a dialog when the client has one, otherwise it returns `say` to print word for word as your whole reply); nothing is read until they answer yes. After a `say`, call it again with the same path and answer set to the option they pick. Never answer for them. Returns { mentionsTalent, links: { linkedin, github, emails, phones }, text } for the talent's own CV; a CV that does not name them returns only mentionsTalent:false: it is someone else's, drop it, never describe it, try the next candidate. Nothing is uploaded by this tool: pass the confirmed path to signup_start (or import_profile) as cvPath, use the text for userQuery and the email, and links.linkedin as their LinkedIn URL.",
+      guidance: "Read the TEXT of a CV file (PDF, DOC, DOCX) on this machine, with talentName set. The tool asks the talent first, naming the file (a dialog when the client has one, otherwise it returns the question to ask as its message says); nothing is read until they answer yes. After asking it in the chat, call it again with the same path and answer set to the option they pick. Never answer for them. Returns { mentionsTalent, links: { linkedin, github, emails, phones }, text } for the talent's own CV; a CV that does not name them returns only mentionsTalent:false: it is someone else's, drop it, never describe it, try the next candidate. Nothing is uploaded by this tool: pass the confirmed path to signup_start (or import_profile) as cvPath, use the text for userQuery and the email, and links.linkedin as their LinkedIn URL.",
       inputSchema: {
         type: 'object',
         properties: {
@@ -386,7 +397,7 @@ function makeRegisterTools(deps = {}) {
       name: 'onboarding_interview_start',
       title: 'Start your onboarding interview',
       description: 'Starts the short Shakers interview here in the chat, after asking you where and how you want to answer it. Your answers go to Shakers to get to know your profile.',
-      guidance: "Start the onboarding interview, here in the chat. Offer it only when signup_status says onboardingInterview.completed is not true. Call it first without disclaimerAcknowledged: it asks 'here now or later on the web?' (in a dialog when the client has one, otherwise it returns `say` to print word for word; default here), then how they want to answer, with the two interview disclaimers in that same question. reason 'interview-later' means they chose the web: skip the interview. reason 'interview-on-web' (a sign-up language the chat interview does not speak) is the same: print relayVerbatim and skip it. If it returns reason 'interview-already-started' (begun elsewhere and not finished), call open_web so they continue on the web. It runs over LiveKit and the server agent conducts it; the client does not decide its branch. When it returns `say`, print it word for word as your whole reply (it holds the disclaimers and the question) and, once they answer, call with where:'here', disclaimerAcknowledged:true and answerMode. Returns { interviewId, answerMode, greeting, ended }: relay the greeting VERBATIM, then drive it with onboarding_interview_turn. ANSWER MODES. For drafted and full, first gather everything you know (memory, a search of past conversations if you have that tool, their CV, the ai_usage report, the sign-up data) and show ONE short sheet 'esto es lo que se de ti' (roles and projects with concrete facts, stack, languages, what they want next); let them correct it once; those corrections override your memory. Your answers are first person, one or two short sentences in their plain voice, built only from facts on the confirmed sheet: no embellishment, no adjectives, metrics or claims they did not give, no repeating a fact already said unless asked; for wishes, preferences or opinions give your best guess and say it is a guess. (1) drafted: show each question VERBATIM with your proposed answer and send it only after the talent approves or edits it; if the sheet does not cover a question, ask them briefly instead of guessing. Only if the talent explicitly asks you to answer everything yourself (for example 'hazla entera' or 'contéstalas tú todas'), answer the remaining questions without asking for each approval, as in full. (2) full (they chose it, or asked for it as above): answer every question yourself without per-answer approval, still showing each question and your answer, and when the interview ends tell them in one line that you answered those questions yourself. (3) own: you are a pure CONDUIT: show every question VERBATIM and pass back only their REAL, VERBATIM words. In every mode never reword, summarize or translate the questions. `interviewId` is internal: never show it. If it fails with next:'open_web', print relayVerbatim word for word and call open_web so they do the interview on the web.",
+      guidance: "Start the onboarding interview, here in the chat. Offer it only when signup_status says onboardingInterview.completed is not true. Call it first without disclaimerAcknowledged: it asks 'here now or later on the web?' (in a dialog when the client has one, otherwise it returns the question to ask as its message says; default here), then how they want to answer, with the two interview disclaimers in that same question. reason 'interview-later' means they chose the web: skip the interview. reason 'interview-on-web' (a sign-up language the chat interview does not speak) is the same: print relayVerbatim and skip it. If it returns reason 'interview-already-started' (begun elsewhere and not finished), call open_web so they continue on the web. It runs over LiveKit and the server agent conducts it; the client does not decide its branch. When it returns a question, ask it as its message says (its `say` holds the disclaimers) and, once they answer, call with where:'here', disclaimerAcknowledged:true and answerMode. Returns { interviewId, answerMode, greeting, ended }: relay the greeting VERBATIM, then drive it with onboarding_interview_turn. ANSWER MODES. For drafted and full, first gather everything you know (memory, a search of past conversations if you have that tool, their CV, the ai_usage report, the sign-up data) and show ONE short sheet 'esto es lo que se de ti' (roles and projects with concrete facts, stack, languages, what they want next); let them correct it once; those corrections override your memory. Your answers are first person, one or two short sentences in their plain voice, built only from facts on the confirmed sheet: no embellishment, no adjectives, metrics or claims they did not give, no repeating a fact already said unless asked; for wishes, preferences or opinions give your best guess and say it is a guess. (1) drafted: show each question VERBATIM with your proposed answer and send it only after the talent approves or edits it; if the sheet does not cover a question, ask them briefly instead of guessing. Only if the talent explicitly asks you to answer everything yourself (for example 'hazla entera' or 'contéstalas tú todas'), answer the remaining questions without asking for each approval, as in full. (2) full (they chose it, or asked for it as above): answer every question yourself without per-answer approval, still showing each question and your answer, and when the interview ends tell them in one line that you answered those questions yourself. (3) own: you are a pure CONDUIT: show every question VERBATIM and pass back only their REAL, VERBATIM words. In every mode never reword, summarize or translate the questions. `interviewId` is internal: never show it. If it fails with next:'open_web', print relayVerbatim word for word and call open_web so they do the interview on the web.",
       inputSchema: INTERVIEW_START_SCHEMA,
       handler: interviewStart,
       available: async () => {
@@ -409,7 +420,7 @@ function makeRegisterTools(deps = {}) {
       name: 'onboarding_interview_complete',
       title: 'Finish the interview',
       description: 'Closes the interview and saves it on Shakers.',
-      guidance: "Close the onboarding interview once the turns report ended:true: the buffered transcript is saved and the live room is disconnected. `interviewId` is internal: never show it. Returns { state:'taken' }. If it returns reason 'unknown-interview' the room was already gone (server restart): nothing to complete. In the sign-up flow, go on to the main role (list_my_roles with waitSeconds, then set_main_role) and finish with open_web; do NOT call onboarding_finish there.",
+      guidance: "Close the onboarding interview once the turns report ended:true, or earlier when the talent asks to end it: the buffered transcript is saved and the live room is disconnected. `interviewId` is internal: never show it. Returns { state:'taken' }. If it returns reason 'unknown-interview' the room was already gone (server restart): nothing to complete. In the sign-up flow, go on to the main role (signup step \"roles\", then signup step \"set_main_role\") and finish with signup step \"open_web\"; do NOT call onboarding_finish there.",
       inputSchema: INTERVIEW_COMPLETE_SCHEMA,
       handler: interviewComplete,
     },

package/src/mcp-role-tools.js

@@ -2,7 +2,7 @@
 
 // MCP role tools: list, add and recommend roles, and set the main role (the sign-up's last step before open_web).
 
-const { askChoice, askAfterTexts, chatChoice, optionFor, SAY_MESSAGE } = require('./mcp-choice');
+const { askChoice, askAfterTexts, chatChoice, forChat, optionFor, OPEN_MESSAGE } = require('./mcp-choice');
 const { signupCopy, renderRole } = require('./signup-copy');
 const { signupLanguage } = require('./signup-language');
 
@@ -17,8 +17,10 @@ const MAX_WAIT_SECONDS = 45;
 const PENDING_FINALIZATION = new Set(['COLLECTING', 'PROCESSING']);
 // Alma's signal from the interview first, then the CV import, as the web stacks them.
 const SOURCE_ORDER = { ONBOARDING_INTERVIEW: 0, IMPORT: 1 };
-// A catalogue this short is offered whole; a longer one only by the roles that match what the talent says.
-const MAX_ROLE_OPTIONS = 5;
+// The chat's question tool takes two to four options: at most four roles are offered and the talent types any other one;
+// a single role gets the "other role" button as its second option.
+const MAX_ROLE_OPTIONS = 4;
+const withOther = (names, other) => (names.length === 1 ? [...names, other] : names);
 
 const fold = (text) => String(text || '').normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase();
 
@@ -77,7 +79,7 @@ const SET_MAIN_ROLE_SCHEMA = {
       description: 'In the sign-up, for each recommended role (by clusterId from list_my_roles): ONE short concrete fact from the CV, the interview or the AI-usage analysis that shows why it fits (e.g. "6 years with Spark and Airflow"), in the talent\'s language. It is shown under the role.',
     },
     answer: { type: 'string', description: 'The option the talent picked when you asked the question in the chat.' },
-    clusterId: { type: 'string', description: 'The role the talent already picked, by clusterId from list_my_roles or from the roles this tool returned. Omit it in the sign-up: the tool asks the talent which recommended role is their main one (a dialog, or options it returns), with the catalogue as the last option.' },
+    clusterId: { type: 'string', description: 'The role the talent already picked, by clusterId from list_my_roles or from the roles this tool returned. Omit it in the sign-up: the tool asks the talent which recommended role is their main one (a dialog, or options it returns); a role they type instead is looked up in the catalogue.' },
     catalogue: { type: 'boolean', description: 'true when the role comes from the catalogue: with clusterId it adds the role before setting it; without clusterId it asks from the catalogue.' },
   },
 };
@@ -112,7 +114,26 @@ function makeRoleTools(deps = {}) {
     sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
     now = () => Date.now(),
     funnel = require('./onboarding-funnel').NOOP_FUNNEL,
+    inSignup = () => require('./mcp-signup-tools').signupPhase() === 'account',
+    completeOnboarding = (session) => require('./onboarding-client').requestCompleteOnboarding(
+      { accessToken: session.accessToken, hubAccessToken: session.hubAccessToken },
+      { endpoint: require('./config').getCompleteOnboardingEndpoint() },
+    ),
   } = deps;
+  let clustersCount;
+  let onboardingCompleted = false;
+  // The recommended roles were offered in the chat, so an answer that names none of them is a role the talent typed.
+  let recommendedAsked = false;
+
+  async function finishSignup(session) {
+    if (onboardingCompleted || !inSignup()) return;
+    const res = await completeOnboarding(session).catch(() => null);
+    onboardingCompleted = !!(res && res.ok);
+  }
+
+  function trackSuggestions(roles) {
+    funnel.viewed('supercluster', { suggested_superclusters: roles.map((r) => r.clusterId), suggestion_source: 'assigned_clusters', suggestions_count: roles.length });
+  }
 
   const requireSession = () => {
     const session = loadAuthSession();
@@ -167,6 +188,7 @@ function makeRoleTools(deps = {}) {
     }
     const assigned = await requestAssignedClusters({ hubAccessToken }, { endpoint: getAssignedClustersEndpoint() });
     const clusters = assigned.ok ? assigned.clusters || [] : [];
+    if (assigned.ok) clustersCount = clusters.length;
     const recommended = clusters
       .filter((c) => c.type === 'RECOMMENDED')
       .sort((a, b) => (SOURCE_ORDER[a.source] ?? 2) - (SOURCE_ORDER[b.source] ?? 2));
@@ -193,6 +215,7 @@ function makeRoleTools(deps = {}) {
       next = 'set_main_role';
       message = 'Call set_main_role without clusterId: it asks the talent which recommended role is their main one, in a dialog or with options it returns for you to show.';
     } else if (read.mainClusterId) {
+      await finishSignup(session);
       next = 'open_web';
       message = 'The talent already has a main role and nothing new was recommended: do not ask it again, go on to open_web. Only if the talent asks to change it, call set_main_role with catalogue:true.';
     } else {
@@ -207,7 +230,7 @@ function makeRoleTools(deps = {}) {
       ok: false,
       reason: 'main-role-choice-required',
       ...(asked.dismissed ? { dismissed: asked.dismissed } : {}),
-      ...asked.chat,
+      ...forChat(asked.chat),
       roles: roles.map((r) => ({ clusterId: r.clusterId, name: r.name })),
       message: `${asked.chat.choiceMessage} Then call set_main_role with the clusterId (from roles) of the one they pick. ${extra}`,
     };
@@ -225,28 +248,42 @@ function makeRoleTools(deps = {}) {
     }));
   }
 
-  // The main-role step: why each recommended role fits and how many projects want it, then the question; the catalogue is the last option.
+  // The main-role step: why each of the best recommended roles fits and how many projects want it, then the question; any other role the talent types is looked up in the catalogue.
   async function chooseMainRole(session, args, ctx) {
     const read = await readRoles(session.hubAccessToken);
-    const recommended = byName(read.recommended);
+    const recommended = byName(read.recommended).slice(0, MAX_ROLE_OPTIONS);
     if (!recommended.length && read.mainClusterId) {
+      await finishSignup(session);
       return { reply: { ok: true, alreadySet: true, clusterId: read.mainClusterId, message: 'The talent already has a main role and nothing new was recommended: nothing to ask. Go on to open_web; only if they ask to change it, call set_main_role with catalogue:true.' } };
     }
     if (!recommended.length) return chooseFromCatalogue(args, ctx);
     const c = copy();
     const counts = await openCounts(session.hubAccessToken, recommended);
+    trackSuggestions(recommended);
     const evidence = args.evidence && typeof args.evidence === 'object' ? args.evidence : {};
-    const blocks = recommended.map((r, i) => renderRole(lang(), { name: r.name, source: r.source, evidence: evidence[r.clusterId], openProjects: counts[i], recommended: i === 0 }));
+    const options = withOther(recommended.map((r) => r.name), c.mainRoleOther);
+    // Each option numbered with why it fits; "another role" is its own label.
+    const blocks = options.map((name, i) => (recommended[i] ? renderRole(lang(), { name, source: recommended[i].source, evidence: evidence[recommended[i].clusterId], openProjects: counts[i], recommended: i === 0 }) : name));
+    const typed = typeof args.answer === 'string' ? args.answer.trim() : '';
+    if (recommendedAsked && typed && !optionFor(typed, options)) {
+      recommendedAsked = false;
+      return chooseFromCatalogue({ answer: typed, skills: args.skills }, ctx);
+    }
     const asked = await askAfterTexts(ctx, {
       tool: 'set_main_role',
-      texts: [[c.rolesIntro, ...blocks, c.rolesOutro].join('\n\n')],
+      texts: [c.rolesIntro],
+      listed: { blocks, after: [c.rolesOutro] },
       question: c.mainRoleQuestion,
-      options: [...recommended.map((r) => r.name), c.mainRoleOther],
+      options,
       answer: args.answer,
+      about: options,
     });
     if (asked.reply) {
-      return { reply: { ...asked.reply, roles: recommended.map((r) => ({ clusterId: r.clusterId, name: r.name })), message: `${asked.reply.message} Pass the same evidence again. If they pick the last option, call set_main_role with catalogue:true and no clusterId.` } };
+      recommendedAsked = true;
+      const other = options.includes(c.mainRoleOther) ? ' If they pick the last option, call set_main_role with catalogue:true and no clusterId.' : '';
+      return { reply: { ...asked.reply, roles: recommended.map((r) => ({ clusterId: r.clusterId, name: r.name })), message: `${asked.reply.message} Pass the same evidence again.${other} If they type another role instead of picking one, pass what they typed as answer: the closest catalogue roles are offered.` } };
     }
+    recommendedAsked = false;
     if (asked.answer === c.mainRoleOther) return chooseFromCatalogue({}, ctx);
     return { role: recommended.find((r) => r.name === asked.answer) };
   }
@@ -261,7 +298,7 @@ function makeRoleTools(deps = {}) {
         ok: false,
         reason: 'main-role-ask',
         say: copy().mainRoleAsk,
-        message: `${SAY_MESSAGE} Then call set_main_role with catalogue:true and answer = what they say: it offers the closest catalogue roles.`,
+        message: `${OPEN_MESSAGE} Then call set_main_role with catalogue:true and answer = what they say: it offers the closest catalogue roles.`,
       },
     };
   }
@@ -270,7 +307,7 @@ function makeRoleTools(deps = {}) {
     const c = copy();
     const said = typeof args.answer === 'string' ? args.answer.trim() : '';
     if (offered) {
-      const picked = optionFor(said, [...offered.map((r) => r.name), c.mainRoleNotListed]);
+      const picked = optionFor(said, withOther(offered.map((r) => r.name), c.mainRoleNotListed));
       if (picked === c.mainRoleNotListed) return askOwnRole();
       const role = picked && offered.find((r) => r.name === picked);
       if (role) { offered = null; return { role, add: true }; }
@@ -296,7 +333,9 @@ function makeRoleTools(deps = {}) {
       typeof counts[i] === 'number' && counts[i] > 0 ? c.openProjects(counts[i]) : null,
     ].filter(Boolean).join('\n'));
     const texts = [[...(blocks.length ? [c.rolesIntro, ...blocks] : []), c.rolesOutro].join('\n\n')];
-    const asked = await askChoice(ctx, { texts, question: c.mainRoleQuestion, options: [...options.map((r) => r.name), c.mainRoleNotListed] });
+    trackSuggestions([]);
+    const names = withOther(options.map((r) => r.name), c.mainRoleNotListed);
+    const asked = await askChoice(ctx, { texts, question: c.mainRoleQuestion, options: names });
     if (asked.answer === c.mainRoleNotListed) return askOwnRole();
     const role = asked.answer && options.find((r) => r.name === asked.answer);
     if (role) {
@@ -304,7 +343,8 @@ function makeRoleTools(deps = {}) {
       return { role, add: true };
     }
     offered = options;
-    return { reply: roleChoice(asked.chat ? asked : { chat: chatChoice(c.mainRoleQuestion, [...options.map((r) => r.name), c.mainRoleNotListed], texts) }, options, `Pass catalogue:true too: it adds the role first. If they pick the last option, call set_main_role with catalogue:true and answer = that option.`) };
+    const other = names.includes(c.mainRoleNotListed) ? ' If they pick the last option, call set_main_role with catalogue:true and answer = that option.' : '';
+    return { reply: roleChoice(asked.chat ? asked : { chat: chatChoice(c.mainRoleQuestion, names, texts) }, options, `Pass catalogue:true too: it adds the role first.${other} If they type another role instead, call set_main_role with catalogue:true and answer = what they typed.`) };
   }
 
   async function setMainRole(args = {}, ctx = {}) {
@@ -330,8 +370,9 @@ function makeRoleTools(deps = {}) {
     const res = await requestSetMainRole({ clusterId, hubAccessToken: session.hubAccessToken }, { endpoint: getSetMainRoleEndpoint() });
     if (res.ok === false && res.reason === 'http-400') return { ok: false, reason: res.reason, message: 'The talent does not hold that role yet: call add_role with it, then set_main_role again.' };
     if (!res.ok) return { ok: false, reason: res.reason };
-    funnel.completed('supercluster', { supercluster: clusterId, was_suggestion_accepted: suggestion });
+    funnel.completed('supercluster', { supercluster: clusterId, clusters_count: clustersCount, was_suggestion_accepted: suggestion });
     funnel.flush();
+    await finishSignup(session);
     return { ok: true, clusterId };
   }
 
@@ -356,7 +397,7 @@ function makeRoleTools(deps = {}) {
       name: 'list_my_roles',
       title: 'Your roles',
       description: 'Shows your roles on Shakers and the ones suggested by your interview and your CV.',
-      guidance: "List the roles the talent already holds, plus mainClusterId (their current main role) and `recommended`: the roles the onboarding interview and the CV import suggest, interview first. Use it before set_main_role. In the sign-up pass waitSeconds (20): it waits for the interview evaluation to recommend roles and says when to call again (`pending`) or to fall back to list_available_roles. Follow `message`. clusterId is an internal handle — refer to roles by name to the talent. Requires an active session.",
+      guidance: "List the roles the talent already holds, plus mainClusterId (their current main role) and `recommended`: the roles the onboarding interview and the CV import suggest, interview first. Use it before set_main_role. In the sign-up pass waitSeconds (45): it waits for the interview evaluation to recommend roles and says when to call again (`pending`) or to fall back to list_available_roles. Follow `message`. clusterId is an internal handle — refer to roles by name to the talent. Requires an active session.",
       inputSchema: LIST_MY_ROLES_SCHEMA,
       handler: listMyRoles,
     },
@@ -364,7 +405,7 @@ function makeRoleTools(deps = {}) {
       name: 'set_main_role',
       title: 'Choose your main role',
       description: 'Asks you which role is your main one and saves it on your Shakers profile.',
-      guidance: "Set the talent's MAIN role. In the sign-up it is the last step before open_web: after onboarding_interview_complete (or when the talent skipped the interview) and once list_my_roles is no longer pending, call it without clusterId: it asks the talent which of the recommended roles is their main one, with the catalogue as the last option (or straight from the catalogue when nothing is recommended), in a dialog when the client has one; otherwise it returns `say` to print word for word and the roles, to call it again with the clusterId they pick. Then it sets that role (adding a catalogue role first). Also usable standalone with clusterId to change the main role later; catalogue:true adds a catalogue role first. Requires an active session.",
+      guidance: "Set the talent's MAIN role. In the sign-up it is the last step before open_web: after onboarding_interview_complete (or when the talent skipped the interview) and once list_my_roles is no longer pending, call it without clusterId: it asks the talent which of the (at most four) recommended roles is their main one (or straight from the catalogue when nothing is recommended), in a dialog when the client has one; otherwise it returns the question and the roles, to call it again with the clusterId they pick, or with answer = another role they type, which it looks up in the catalogue. Then it sets that role (adding a catalogue role first). Also usable standalone with clusterId to change the main role later; catalogue:true adds a catalogue role first. Requires an active session.",
       inputSchema: SET_MAIN_ROLE_SCHEMA,
       handler: setMainRole,
     },

package/src/mcp-server-name.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const SERVER_NAME = 'shakers';
+const LEGACY_SERVER_NAME = 'shakers-ai-usage';
+const OWN_MCP_SERVER_NAMES = new Set([SERVER_NAME, LEGACY_SERVER_NAME]);
+
+module.exports = { SERVER_NAME, LEGACY_SERVER_NAME, OWN_MCP_SERVER_NAMES };

package/src/mcp-server.js

@@ -34,7 +34,28 @@ function errorResponse(id, code, message, data) {
   return { jsonrpc: JSONRPC, id: id === undefined ? null : id, error };
 }
 
-function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVersion, beforeCall = null, afterCall = null, onInitialize = null, instructions = null, elicitationTimeoutMs = ELICITATION_TIMEOUT_MS } = {}) {
+// Cowork advertises elicitation, drops the request and leaves the call hanging ~180 s (anthropics/claude-ai-mcp#1046);
+// it names itself in clientInfo ('claude-code', version '... (remote_cowork)'). Claude Desktop ('claude-ai') does not
+// advertise it today and is matched so that advertising it later cannot lead to the same hang. Both ask in the chat.
+// Matched on clientInfo only, the one thing the handshake says about the client.
+function dropsElicitation(clientInfo = {}) {
+  const name = typeof clientInfo.name === 'string' ? clientInfo.name.toLowerCase() : '';
+  const version = typeof clientInfo.version === 'string' ? clientInfo.version.toLowerCase() : '';
+  return name === 'claude-ai' || name.includes('cowork') || version.includes('cowork');
+}
+
+// The tool's narration opens every result. A reply with `say` (text the talent must read) follows it in the same
+// plain-text block, so the model writes both as one message, and the rest goes as JSON after it: a model writes a
+// readable text before it reasons over a JSON field, and the talent never sees tool results.
+function contentOf(value, narration = null) {
+  if (value && typeof value === 'object' && typeof value.say === 'string' && value.say) {
+    const { say, ...rest } = value;
+    return [{ type: 'text', text: [narration, say].filter(Boolean).join('\n\n') }, { type: 'text', text: JSON.stringify(rest, null, 2) }];
+  }
+  return [...(narration ? [{ type: 'text', text: narration }] : []), { type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+
+function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVersion, beforeCall = null, afterCall = null, narrate = null, onInitialize = null, instructions = null, elicitationTimeoutMs = ELICITATION_TIMEOUT_MS } = {}) {
   const registry = new Map();
   for (const t of tools) {
     if (!t || !t.name || typeof t.handler !== 'function') {
@@ -54,6 +75,7 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
   const advertisedVersion = protocolVersion || DEFAULT_PROTOCOL_VERSION;
 
   let clientCapabilities = {};
+  let clientInfo = {};
   let send = null;
   let lastRequestId = 0;
   const pending = new Map();
@@ -91,7 +113,7 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
   // (`{ url }` without `{ form }`), which only opens links and falls back to the chat.
   function canElicitForm() {
     const e = clientCapabilities.elicitation;
-    if (!e) return false;
+    if (!e || dropsElicitation(clientInfo)) return false;
     if (typeof e === 'object' && e.url !== undefined && e.form === undefined) return false;
     return true;
   }
@@ -174,15 +196,20 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
     if (typeof beforeCall === 'function') {
       try { await beforeCall(name); } catch { /* hook must never break a tool call */ }
     }
+    const narration = (failed) => {
+      const text = typeof narrate === 'function' ? narrate(name, { failed, args }) : null;
+      return text ? [{ type: 'text', text }] : [];
+    };
     try {
-      const value = await tool.handler(args, { elicit, elicitation: !!send && canElicitForm() });
+      const asking = narration(false);
+      const value = await tool.handler(args, { elicit, elicitation: !!send && canElicitForm(), narration: asking.length ? asking[0].text : null });
       return {
-        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        content: contentOf(value, asking.length ? asking[0].text : null),
         isError: false,
       };
     } catch (e) {
       return {
-        content: [{ type: 'text', text: `${name} tool error: ${e && e.message ? e.message : String(e)}` }],
+        content: [...narration(true), { type: 'text', text: `${name} tool error: ${e && e.message ? e.message : String(e)}` }],
         isError: true,
       };
     } finally {
@@ -213,8 +240,9 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
         case 'initialize': {
           const requested = msg.params && msg.params.protocolVersion;
           clientCapabilities = (msg.params && msg.params.capabilities) || {};
+          clientInfo = (msg.params && msg.params.clientInfo) || {};
           if (typeof onInitialize === 'function') {
-            try { onInitialize({ clientInfo: (msg.params && msg.params.clientInfo) || {} }); } catch { /* never breaks the handshake */ }
+            try { onInitialize({ clientInfo }); } catch { /* never breaks the handshake */ }
           }
           // One line per connection on stderr (never stdout: it carries JSON-RPC), so the host's
           // declared elicitation shape and the resulting decision are visible in the MCP log.
@@ -292,4 +320,4 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
   return { handleMessage, listTools, listAvailableTools, callTool, start };
 }
 
-module.exports = { createMcpServer, ERROR, DEFAULT_PROTOCOL_VERSION };
+module.exports = { createMcpServer, dropsElicitation, ERROR, DEFAULT_PROTOCOL_VERSION };

package/src/mcp-signup-client.js

@@ -96,13 +96,10 @@ async function requestMyImportStatus({ hubAccessToken } = {}, { endpoint, timeou
   return { ok: true, ...importStateOf(data) };
 }
 
-// better-auth reads the session from the cookie (email sign-in) or the Bearer session token (device flow).
-async function requestOneTimeToken({ cookie = null, sessionToken = null } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+async function requestOneTimeToken({ sessionToken = null } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   if (!endpoint) return { ok: false, reason: 'no-endpoint' };
-  const headers = {};
-  if (cookie) headers.Cookie = cookie;
-  else if (sessionToken) headers.Authorization = `Bearer ${sessionToken}`;
-  else return { ok: false, reason: 'no-session' };
+  if (!sessionToken) return { ok: false, reason: 'no-session' };
+  const headers = { Authorization: `Bearer ${sessionToken}` };
   let res;
   try {
     res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, headers);