shakers-cli-beta 0.8.0-beta.5 → 0.10.0

package/src/mcp-role-tools.js

@@ -1,11 +1,28 @@
 'use strict';
 
-// MCP: role/cluster management — list addable roles, add one, list held roles,
-// and set the main role. The onboarding final step is set_main_role after the
-// interview (or after skipping it).
+// 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 } = require('./mcp-choice');
+const { signupCopy, renderRole } = require('./signup-copy');
+const { signupLanguage } = require('./signup-language');
 
 const EMPTY_SCHEMA = { type: 'object', properties: {} };
 
+// Same bounds as the web's growth-direction step: certs finalizes an interview within ~90 s, polled every 2 s.
+const FINALIZATION_WAIT_LIMIT_MS = 90000;
+const POLL_MS = 2000;
+const MAX_WAIT_SECONDS = 25;
+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 };
+
+const LIST_MY_ROLES_SCHEMA = {
+  type: 'object',
+  properties: {
+    waitSeconds: { type: 'number', description: `In the sign-up, wait up to this many seconds (max ${MAX_WAIT_SECONDS}) for the interview evaluation or the import to recommend roles.` },
+  },
+};
+
 const CLUSTER_SCHEMA = {
   type: 'object',
   properties: {
@@ -14,7 +31,31 @@ const CLUSTER_SCHEMA = {
   required: ['clusterId'],
 };
 
+const SET_MAIN_ROLE_SCHEMA = {
+  type: 'object',
+  properties: {
+    evidence: {
+      type: 'object',
+      additionalProperties: { type: 'string' },
+      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.',
+    },
+    shown: { type: 'boolean', description: 'true only after you showed relayVerbatim from the previous call: it then asks the question in a dialog.' },
+    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.' },
+    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.' },
+  },
+};
+
+// One option per role name: the talent picks by name, so two rows with the same name would be one choice.
+function byName(roles) {
+  const seen = new Map();
+  for (const r of roles) if (r && r.name && !seen.has(r.name)) seen.set(r.name, r);
+  return [...seen.values()];
+}
+
 function makeRoleTools(deps = {}) {
+  const lang = () => signupLanguage(deps.lang || require('./i18n').detectFlowLang());
+  const copy = () => signupCopy(lang());
   const {
     getAvailableRolesEndpoint = require('./config').getAvailableRolesEndpoint,
     getSetMainRoleEndpoint = require('./config').getSetMainRoleEndpoint,
@@ -28,6 +69,12 @@ function makeRoleTools(deps = {}) {
     loadAuthSession = require('./auth-session-store').loadAuthSession,
     sessionStatus = require('./auth-session-store').sessionStatus,
     dedupeByCluster = require('./roles-flow').dedupeByCluster,
+    getOnboardingInterviewsEndpoint = require('./config').getOnboardingInterviewsEndpoint,
+    requestInterviewFinalization = require('./onboarding-status-client').requestInterviewFinalization,
+    completedOnboardingInterview = () => require('./mcp-register-tools').completedOnboardingInterview(),
+    countOpenPositions = (opts) => require('./find-projects-client').countOpenPositions({}, opts),
+    sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
+    now = () => Date.now(),
   } = deps;
 
   const requireSession = () => {
@@ -38,7 +85,14 @@ function makeRoleTools(deps = {}) {
     return session;
   };
 
-  const shape = (r) => ({ clusterId: r.clusterId, name: r.name, category: r.category, ...(r.proposalKind ? { proposalKind: r.proposalKind } : {}) });
+  const shape = (r) => ({
+    clusterId: r.clusterId,
+    name: r.name,
+    category: r.category,
+    ...(r.proposalKind ? { proposalKind: r.proposalKind } : {}),
+    ...(r.type ? { type: r.type } : {}),
+    ...(r.source ? { source: r.source } : {}),
+  });
 
   async function listAvailableRoles() {
     const session = requireSession();
@@ -58,9 +112,15 @@ function makeRoleTools(deps = {}) {
     return { ok: true, clusterId: args.clusterId };
   }
 
-  async function listMyRoles() {
-    const session = requireSession();
-    const hubAccessToken = session.hubAccessToken;
+  // Whether certs is still evaluating the interview this process completed, within the web's wait.
+  async function evaluationPending(session) {
+    const interview = completedOnboardingInterview();
+    if (!interview || now() - interview.completedAt >= FINALIZATION_WAIT_LIMIT_MS) return false;
+    const res = await requestInterviewFinalization({ interviewId: interview.interviewId, accessToken: session.accessToken }, { base: getOnboardingInterviewsEndpoint() });
+    return res.ok && PENDING_FINALIZATION.has(res.status);
+  }
+
+  async function readRoles(hubAccessToken) {
     const held = [];
     let mainClusterId = null;
     const cert = await requestMeCertifications({ hubAccessToken }, { endpoint: getMyCertificationsEndpoint() });
@@ -69,14 +129,115 @@ function makeRoleTools(deps = {}) {
       for (const g of cert.growingInto || []) held.push(g);
     }
     const assigned = await requestAssignedClusters({ hubAccessToken }, { endpoint: getAssignedClustersEndpoint() });
-    if (assigned.ok) for (const c of assigned.clusters || []) held.push(c);
-    return { ok: true, mainClusterId, roles: dedupeByCluster(held).map(shape) };
+    const clusters = assigned.ok ? assigned.clusters || [] : [];
+    const recommended = clusters
+      .filter((c) => c.type === 'RECOMMENDED')
+      .sort((a, b) => (SOURCE_ORDER[a.source] ?? 2) - (SOURCE_ORDER[b.source] ?? 2));
+    return { mainClusterId, roles: dedupeByCluster([...held, ...clusters]).map(shape), recommended: recommended.map(shape) };
   }
 
-  async function setMainRole(args = {}) {
+  async function listMyRoles(args = {}) {
     const session = requireSession();
-    if (!args.clusterId) return { ok: false, reason: 'no-cluster' };
+    const deadline = now() + Math.min(Math.max(Number(args.waitSeconds) || 0, 0), MAX_WAIT_SECONDS) * 1000;
+    let pending = await evaluationPending(session);
+    while (pending && now() < deadline) {
+      await sleep(POLL_MS);
+      pending = await evaluationPending(session);
+    }
+    let read = await readRoles(session.hubAccessToken);
+    while (!pending && read.recommended.length === 0 && now() < deadline) {
+      await sleep(POLL_MS);
+      read = await readRoles(session.hubAccessToken);
+    }
+    let message;
+    let next = null;
+    if (pending) message = 'The interview evaluation is still recommending roles: tell the talent you are preparing their roles and call list_my_roles again with waitSeconds.';
+    else if (read.recommended.length) {
+      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 {
+      next = 'set_main_role';
+      message = 'Nothing was recommended: call set_main_role without clusterId, it offers the catalogue (list_available_roles), then adds (add_role) and sets the role the talent picks.';
+    }
+    return { ok: true, ...read, pending, ...(next ? { next } : {}), message };
+  }
+
+  function roleChoice(asked, roles, extra) {
+    return {
+      ok: false,
+      reason: 'main-role-choice-required',
+      ...(asked.dismissed ? { dismissed: asked.dismissed } : {}),
+      ...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}`,
+    };
+  }
+
+  // How many open projects look for each role; a failed count leaves its line out.
+  async function openCounts(hubAccessToken, roles) {
+    return Promise.all(roles.map(async (r) => {
+      try {
+        const res = await countOpenPositions({ hubAccessToken, clusterId: r.clusterId });
+        return res && res.ok ? res.total : null;
+      } catch {
+        return null;
+      }
+    }));
+  }
+
+  // The main-role step: why each recommended role fits and how many projects want it, then the question; the catalogue is the last option.
+  async function chooseMainRole(session, args, ctx) {
+    const recommended = byName((await readRoles(session.hubAccessToken)).recommended);
+    if (!recommended.length) return chooseFromCatalogue(args, ctx);
+    const c = copy();
+    const counts = await openCounts(session.hubAccessToken, 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 asked = await askAfterTexts(ctx, {
+      tool: 'set_main_role',
+      texts: [[c.rolesIntro, ...blocks, c.rolesOutro].join('\n\n')],
+      question: c.mainRoleQuestion,
+      options: [...recommended.map((r) => r.name), c.mainRoleOther],
+      shown: args.shown,
+      answer: args.answer,
+    });
+    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.` } };
+    }
+    if (asked.answer === c.mainRoleOther) return chooseFromCatalogue({}, ctx);
+    return { role: recommended.find((r) => r.name === asked.answer) };
+  }
+
+  async function chooseFromCatalogue(args, ctx) {
+    const available = await listAvailableRoles();
+    if (!available.ok) return { reply: { ok: false, reason: available.reason } };
+    const roles = byName(available.roles);
+    if (!roles.length) return { reply: { ok: false, reason: 'no-roles' } };
+    const typed = roles.find((r) => typeof args.answer === 'string' && r.name === args.answer.trim());
+    if (typed) return { role: typed, add: true };
+    const asked = await askChoice(ctx, { question: copy().mainRoleQuestion, options: roles.map((r) => r.name) });
+    if (!asked.answer) return { reply: roleChoice(asked, roles, 'Pass catalogue:true too: it adds the role first.') };
+    return { role: roles.find((r) => r.name === asked.answer), add: true };
+  }
+
+  async function setMainRole(args = {}, ctx = {}) {
+    const session = requireSession();
+    if (args.clusterId && args.catalogue === true) {
+      const added = await addRole({ clusterId: args.clusterId });
+      if (!added.ok) return added;
+    }
+    if (!args.clusterId) {
+      const picked = args.catalogue === true ? await chooseFromCatalogue(args, ctx) : await chooseMainRole(session, args, ctx);
+      if (picked.reply) return picked.reply;
+      if (picked.add) {
+        const added = await addRole({ clusterId: picked.role.clusterId });
+        if (!added.ok) return added;
+      }
+      const set = await setMainRole({ clusterId: picked.role.clusterId });
+      return set.ok ? { ...set, name: picked.role.name } : set;
+    }
     const res = await requestSetMainRole({ clusterId: args.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 };
     return { ok: true, clusterId: args.clusterId };
   }
@@ -96,17 +257,17 @@ function makeRoleTools(deps = {}) {
     },
     {
       name: 'list_my_roles',
-      description: "List the roles the talent already holds, plus mainClusterId (their current main role). Use it before set_main_role. clusterId is an internal handle — refer to roles by name to the talent. Requires an active session.",
-      inputSchema: EMPTY_SCHEMA,
+      description: "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.",
+      inputSchema: LIST_MY_ROLES_SCHEMA,
       handler: listMyRoles,
     },
     {
       name: 'set_main_role',
-      description: "Set the talent's MAIN role to one they already hold, by clusterId from list_my_roles. This is the onboarding FINAL step: after onboarding_interview_complete (or if the talent skipped the interview), offer them their held roles and set the one they pick. Also usable standalone to change the main role later. Requires an active session.",
-      inputSchema: CLUSTER_SCHEMA,
+      description: "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 the question, its options 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.",
+      inputSchema: SET_MAIN_ROLE_SCHEMA,
       handler: setMainRole,
     },
   ];
 }
 
-module.exports = { makeRoleTools, EMPTY_SCHEMA, CLUSTER_SCHEMA };
+module.exports = { makeRoleTools, EMPTY_SCHEMA, CLUSTER_SCHEMA, LIST_MY_ROLES_SCHEMA, SET_MAIN_ROLE_SCHEMA };

package/src/mcp-server.js

@@ -4,6 +4,9 @@ const readline = require('readline');
 
 const JSONRPC = '2.0';
 const DEFAULT_PROTOCOL_VERSION = '2025-06-18';
+// A talent answering a dialog takes human time; past this the tool falls back to asking in the chat.
+const ELICITATION_TIMEOUT_MS = 5 * 60 * 1000;
+const ELICITATION_ACTIONS = new Set(['accept', 'decline', 'cancel']);
 
 const ERROR = {
   PARSE: -32700,
@@ -13,6 +16,10 @@ const ERROR = {
   INTERNAL: -32603,
 };
 
+function isResponse(msg) {
+  return !!msg && msg.jsonrpc === JSONRPC && msg.method === undefined && msg.id !== undefined && msg.id !== null && ('result' in msg || 'error' in msg);
+}
+
 function isNotification(msg) {
   return !msg || msg.id === undefined || msg.id === null;
 }
@@ -27,7 +34,7 @@ function errorResponse(id, code, message, data) {
   return { jsonrpc: JSONRPC, id: id === undefined ? null : id, error };
 }
 
-function createMcpServer({ tools = [], serverInfo = {}, protocolVersion, beforeCall = null, instructions = null } = {}) {
+function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVersion, beforeCall = null, instructions = null, elicitationTimeoutMs = ELICITATION_TIMEOUT_MS } = {}) {
   const registry = new Map();
   for (const t of tools) {
     if (!t || !t.name || typeof t.handler !== 'function') {
@@ -36,8 +43,66 @@ function createMcpServer({ tools = [], serverInfo = {}, protocolVersion, beforeC
     registry.set(t.name, t);
   }
 
+  const promptRegistry = new Map();
+  for (const p of prompts) {
+    if (!p || !p.name || typeof p.buildMessages !== 'function') {
+      throw new Error('each prompt needs a name and a buildMessages function');
+    }
+    promptRegistry.set(p.name, p);
+  }
+
   const advertisedVersion = protocolVersion || DEFAULT_PROTOCOL_VERSION;
 
+  let clientCapabilities = {};
+  let send = null;
+  let lastRequestId = 0;
+  const pending = new Map();
+
+  function request(method, params, timeoutMs) {
+    if (!send) return Promise.reject(new Error('no transport to the client'));
+    lastRequestId += 1;
+    const id = `shakers-${lastRequestId}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { pending.delete(id); reject(new Error(`${method} timed out`)); }, timeoutMs);
+      pending.set(id, { resolve, reject, timer });
+      send({ jsonrpc: JSONRPC, id, method, params });
+    });
+  }
+
+  function settle(msg) {
+    const waiter = pending.get(msg.id);
+    if (!waiter) return;
+    pending.delete(msg.id);
+    clearTimeout(waiter.timer);
+    if (msg.error) waiter.reject(new Error((msg.error && msg.error.message) || 'client error'));
+    else waiter.resolve(msg.result);
+  }
+
+  function rejectPending(reason) {
+    for (const [id, waiter] of pending) {
+      pending.delete(id);
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error(reason));
+    }
+  }
+
+  // An `elicitation` capability without `form` but with `url` only opens links, so it cannot ask a closed question.
+  function canElicitForm() {
+    const e = clientCapabilities.elicitation;
+    return !!e && typeof e === 'object' && (e.form !== undefined || e.url === undefined);
+  }
+
+  // MCP elicitation/create: the client's { action, content }, or null when it has no dialog or the exchange failed.
+  async function elicit({ message, requestedSchema }) {
+    if (!send || !canElicitForm()) return null;
+    try {
+      const result = await request('elicitation/create', { message, requestedSchema }, elicitationTimeoutMs);
+      return result && ELICITATION_ACTIONS.has(result.action) ? result : null;
+    } catch {
+      return null;
+    }
+  }
+
   function shapeTool(t) {
     return {
       name: t.name,
@@ -50,6 +115,27 @@ function createMcpServer({ tools = [], serverInfo = {}, protocolVersion, beforeC
     return { tools: [...registry.values()].map(shapeTool) };
   }
 
+  function shapePrompt(p) {
+    const out = { name: p.name, description: p.description || '' };
+    if (Array.isArray(p.arguments)) out.arguments = p.arguments;
+    return out;
+  }
+
+  function listPrompts() {
+    return { prompts: [...promptRegistry.values()].map(shapePrompt) };
+  }
+
+  function getPrompt(params) {
+    const name = params && params.name;
+    const prompt = name && promptRegistry.get(name);
+    if (!prompt) {
+      const err = new Error(`unknown prompt: ${name}`);
+      err.rpcCode = ERROR.INVALID_PARAMS;
+      throw err;
+    }
+    return { description: prompt.description || '', messages: prompt.buildMessages((params && params.arguments) || {}) };
+  }
+
   async function listAvailableTools() {
     const out = [];
     for (const t of registry.values()) {
@@ -81,7 +167,7 @@ function createMcpServer({ tools = [], serverInfo = {}, protocolVersion, beforeC
       try { await beforeCall(name); } catch { /* hook must never break a tool call */ }
     }
     try {
-      const value = await tool.handler(args);
+      const value = await tool.handler(args, { elicit, elicitation: !!send && canElicitForm() });
       return {
         content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
         isError: false,
@@ -95,6 +181,10 @@ function createMcpServer({ tools = [], serverInfo = {}, protocolVersion, beforeC
   }
 
   async function handleMessage(msg) {
+    if (isResponse(msg)) {
+      settle(msg);
+      return null;
+    }
     if (!msg || msg.jsonrpc !== JSONRPC || typeof msg.method !== 'string') {
       if (isNotification(msg)) return null;
       return errorResponse(msg && msg.id, ERROR.INVALID_REQUEST, 'invalid JSON-RPC request');
@@ -110,16 +200,21 @@ function createMcpServer({ tools = [], serverInfo = {}, protocolVersion, beforeC
       switch (method) {
         case 'initialize': {
           const requested = msg.params && msg.params.protocolVersion;
+          clientCapabilities = (msg.params && msg.params.capabilities) || {};
+          const text = typeof instructions === 'function' ? instructions({ elicitation: canElicitForm() }) : instructions;
           return resultResponse(id, {
             protocolVersion: requested || advertisedVersion,
-            capabilities: { tools: { listChanged: false } },
+            capabilities: {
+              tools: { listChanged: false },
+              ...(promptRegistry.size ? { prompts: { listChanged: false } } : {}),
+            },
             serverInfo: {
               name: serverInfo.name || 'shakers-mcp',
               version: serverInfo.version || '0.0.0',
             },
             // Server-level guidance the client keeps in the model's context even
             // when it loads tool schemas lazily (Claude Code defers MCP tools).
-            ...(typeof instructions === 'string' && instructions ? { instructions } : {}),
+            ...(typeof text === 'string' && text ? { instructions: text } : {}),
           });
         }
         case 'ping':
@@ -128,6 +223,10 @@ function createMcpServer({ tools = [], serverInfo = {}, protocolVersion, beforeC
           return resultResponse(id, await listAvailableTools());
         case 'tools/call':
           return resultResponse(id, await callTool(msg.params));
+        case 'prompts/list':
+          return resultResponse(id, listPrompts());
+        case 'prompts/get':
+          return resultResponse(id, getPrompt(msg.params));
         default:
           if (isNotification(msg)) return null;
           return errorResponse(id, ERROR.METHOD_NOT_FOUND, `method not found: ${method}`);
@@ -142,6 +241,11 @@ function createMcpServer({ tools = [], serverInfo = {}, protocolVersion, beforeC
   function start({ input = process.stdin, output = process.stdout, onError } = {}) {
     const rl = readline.createInterface({ input, crlfDelay: Infinity });
     const write = (obj) => output.write(`${JSON.stringify(obj)}\n`);
+    send = write;
+    rl.on('close', () => {
+      send = null;
+      rejectPending('the client closed the connection');
+    });
 
     rl.on('line', async (line) => {
       const trimmed = line.trim();

package/src/mcp-signup-client.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const { postJsonWithTimeout, postMultipartWithTimeout } = require('./backend-request');
+
+// Hub calls of the MCP sign-up (ticket 39540): public sign-up + claim code, the signed-in talent's import status, and the one-time web login token.
+
+const SIGNUP_TIMEOUT_MS = 60000;
+const DEFAULT_TIMEOUT_MS = 15000;
+
+// Hub's coded errors on the sign-up, verified against the works-ai exception filter (hub MR !2198); none says whether an account exists.
+const CODE_TO_REASON = {
+  MISSING_SOURCE: 'missing-source',
+  INVALID_CV: 'invalid-cv',
+  INVALID_LINKEDIN_URL: 'invalid-linkedin-url',
+  RATE_LIMITED: 'rate-limited',
+};
+const IMPORT_SOURCES = ['linkedin', 'cv'];
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function failure(res) {
+  const body = parseJson(res.raw);
+  const code = body && typeof body.code === 'string' ? body.code : null;
+  return { ok: false, reason: (code && CODE_TO_REASON[code]) || `http-${res.status}`, status: res.status };
+}
+
+function envelopeData(raw) {
+  const json = parseJson(raw);
+  return json && json.status === 'OK' && json.data && typeof json.data === 'object' ? json.data : null;
+}
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+async function requestMcpSignup(
+  { linkedinUrl, cv, email, firstName, lastName, userQuery, language } = {},
+  { endpoint, timeoutMs = SIGNUP_TIMEOUT_MS } = {},
+) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  const fields = {
+    linkedinUrl: nonEmpty(linkedinUrl),
+    email: nonEmpty(email),
+    firstName: nonEmpty(firstName),
+    lastName: nonEmpty(lastName),
+    userQuery: nonEmpty(userQuery),
+    language: nonEmpty(language),
+    file: cv && Buffer.isBuffer(cv.data) ? cv : undefined,
+  };
+  let res;
+  try {
+    res = await postMultipartWithTimeout(endpoint, fields, timeoutMs, 'POST');
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return failure(res);
+  const data = envelopeData(res.raw);
+  if (!data || typeof data.claimCode !== 'string' || !data.claimCode) return { ok: false, reason: 'bad-response' };
+  return { ok: true, claimCode: data.claimCode, claimCodeExpiresAt: data.claimCodeExpiresAt || null };
+}
+
+// hub works/me/import-profile/status → { state: running | done | failed, sources: { linkedin?, cv? } }, the shape signup_status reports.
+function importStateOf(data) {
+  const status = data.profileImportStatus;
+  const reported = Array.isArray(data.sources) ? data.sources : [];
+  const sources = {};
+  for (const entry of reported) {
+    if (!entry || !IMPORT_SOURCES.includes(entry.source) || !['imported', 'failed'].includes(entry.status)) continue;
+    const failed = entry.status === 'failed';
+    sources[entry.source] = { state: failed ? 'failed' : 'done', ...(failed && typeof entry.code === 'string' ? { code: entry.code } : {}) };
+  }
+  if (status === 'PENDING' || status === 'RUNNING') return { state: 'running', sources: {} };
+  if (status === 'FAILED' || status === 'SKIPPED') return { state: 'failed', code: data.errorCode || null, sources };
+  if (status === 'DONE') return { state: 'done', sources };
+  return { state: 'none', sources: {} };
+}
+
+async function requestMyImportStatus({ hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-session' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, { Authorization: `Bearer ${hubAccessToken}` });
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: `http-${res.status}`, status: res.status };
+  const data = envelopeData(res.raw);
+  if (!data) return { ok: false, reason: 'bad-response' };
+  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 } = {}) {
+  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' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, headers);
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: `http-${res.status}`, status: res.status };
+  const body = parseJson(res.raw);
+  const token = body && (typeof body.token === 'string' ? body.token : (body.data && body.data.token));
+  return typeof token === 'string' && token ? { ok: true, token } : { ok: false, reason: 'bad-response' };
+}
+
+module.exports = { requestMcpSignup, requestMyImportStatus, requestOneTimeToken, CODE_TO_REASON };