shakers-cli-beta 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakers-cli-beta",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Shakers AI usage & skills evaluator: a local-first CLI (`shakers` binary) plus a local MCP server. Commands: ai-usage (scan + classify your AI-tool setup, T0-T7), certify (certify Skills from your code), share (branded LinkedIn card).",
   "type": "commonjs",
   "bin": {

package/src/backend-request.js

@@ -3,6 +3,7 @@
 const http = require('http');
 const https = require('https');
 const crypto = require('crypto');
+const { getHubBase } = require('./config');
 
 // ONE BACKEND: the certifications service (talents-ai-score, ADR-042).
 
@@ -16,6 +17,20 @@ function setClientIdentity(identity) {
   clientIdentity = identity;
 }
 
+// Hub profile writes declare which surface made them; reads, auth and the onboarding funnel are not profile updates.
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const HUB_PROFILE_PATH_RE = /^\/(works\/(talents?\/me|me|users\/me)|works\/talent\/(portfolios|certifications\/me))(\/|$)/;
+const NOT_PROFILE_UPDATE_RE = /^\/works\/talent\/me\/onboarding-events(\/|$)/;
+
+function profileUpdateSourceHeader(url, method) {
+  if (!MUTATING_METHODS.has(String(method).toUpperCase())) return {};
+  const hubBase = getHubBase();
+  if (!hubBase || !url.href.startsWith(`${hubBase}/`)) return {};
+  const path = url.href.slice(hubBase.length).split(/[?#]/)[0];
+  if (!HUB_PROFILE_PATH_RE.test(path) || NOT_PROFILE_UPDATE_RE.test(path)) return {};
+  return { 'X-Profile-Update-Source': clientIdentity };
+}
+
 // Extra request headers, sanitized (talents-ai-score, issue 038 — the agent certification interview needs `Authorization: Bearer <sessionToken>`).
 const UNSAFE_HEADER_VALUE_RE = /[\r\n\0]/;
 
@@ -49,6 +64,7 @@ function postJsonWithTimeout(url, body, timeoutMs, method = 'POST', idempotencyK
           Accept: 'application/json',
           // Tells CLI and MCP traffic apart from the browser.
           'X-Shakers-Client': clientIdentity,
+          ...profileUpdateSourceHeader(u, method),
           // Only declared when there IS a body — see the bodyless note above.
           ...(data ? { 'Content-Type': 'application/json', 'Content-Length': data.length } : {}),
           ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
@@ -129,6 +145,7 @@ function postMultipartWithTimeout(url, fields, timeoutMs, method = 'POST', extra
           Accept: 'application/json',
           // See postJsonWithTimeout's identical header for why.
           'X-Shakers-Client': clientIdentity,
+          ...profileUpdateSourceHeader(u, method),
           'Content-Type': `multipart/form-data; boundary=${boundary}`,
           'Content-Length': data.length,
           ...sanitizeExtraHeaders(extraHeaders),

package/src/mcp-find-projects-tools.js

@@ -58,6 +58,7 @@ function makeFindProjectsTools(deps = {}) {
       description: 'Shows the open Shakers projects that match you best.',
       guidance: "List the Positions/Projects available to the talent right now (Shakers Find Positions), paginated and ordered by match desc. Each item carries its parent Project id/name, title, company, budget, work mode and match. Supports server-side pagination (page/limit) and filters (tab all|saved, attendance, country ISO2). `meta` carries {page,pageSize,total,totalPages}. Requires an active session. The positionId/projectId in each item are INTERNAL handles for calling other tools (e.g. show_project, save_project) — NEVER show or mention them to the talent; refer to a project by its title/company only.",
       inputSchema: FIND_PROJECTS_SCHEMA,
+      annotations: { readOnlyHint: true },
       handler: findProjects,
     },
   ];

package/src/mcp-instructions.js

@@ -15,11 +15,11 @@ function buildServerInstructions({ elicitation = false } = {}) {
     '2. LinkedIn: take it from the CV. If it has none, signup_start with linkedinMissing:true returns the question to print; never ask it in your own words. Only if they say they do not know where to find it, say the linkedinOpening text and call open_linkedin_profile.',
     '3. signup_email with the best email you know (CV first), or none.',
     '4. signup_draft with your draft of their profile (name, role, city, years, stack, languages, work mode, hours, hourly and annual rate in euros, both always: the talent\'s figures with ratesFromTalent:true, else your estimate; sources: cv and/or linkedin, only those you have). It shows the draft, the data notice and how the account window works, and asks them to confirm; if they want changes, ask what and call it again.',
-    '5. Once confirmed, signup_create_account with LinkedIn, cvPath, names and userQuery = everything you know about them; the window opens by itself, so say nothing about it. Then signup_status (waitSeconds 20) until the account exists, and follow its message (a failed LinkedIn import: its fixed line comes with the next question; retry once, then ask for their website or GitHub).',
+    '5. Once confirmed, signup_create_account with LinkedIn, cvPath, names and userQuery = everything you know about them; the window opens by itself, so say nothing about it. Then signup_status (waitSeconds 45) until the account exists, and follow its message (a failed LinkedIn import: its fixed line comes with the next question; retry once, then ask for their website or GitHub).',
     '6. New account: save_profile_details with the confirmed draft, without asking. Existing account (the talent signed in instead): update_existing_profile, which shows what would fill their empty fields and asks; nothing they already set is overwritten.',
     '7. AI usage, a step of its own: ai_usage without consent asks the question with the two disclaimers; nothing is scanned before their yes. On yes it runs in the background: never wait for it. If they skip it, its fixed line comes with the next question.',
     '8. Onboarding interview: skip it if signup_status says it is completed; otherwise onboarding_interview_start without disclaimerAcknowledged (here now or later on the web, default here), then how they want to answer (drafted, own, full), asked with the interview disclaimers. In drafted mode, show each question verbatim with your proposed answer and send it only after the talent approves or edits it; only if they explicitly ask you to answer everything yourself ("hazla entera", "do it all"), complete the remaining questions without per-answer approval and tell them at the end. Full mode is that from the first question. Own mode sends only their words. Never call onboarding_finish in this flow.',
-    '9. Main role, also when they skip the interview: list_my_roles (waitSeconds 20, again while pending), then, only when its next is set_main_role, set_main_role without clusterId and with evidence = one concrete fact per recommended role from their CV, the interview or the AI-usage analysis (with nothing recommended: answer = the role their CV names and skills = their stack). Never set a main role the talent did not pick.',
+    '9. Main role, also when they skip the interview: list_my_roles (waitSeconds 45, again while pending), then, only when its next is set_main_role, set_main_role without clusterId and with evidence = one concrete fact per recommended role from their CV, the interview or the AI-usage analysis (with nothing recommended: answer = the role their CV names and skills = their stack). Never set a main role the talent did not pick.',
     '10. Finish with open_web: it opens Shakers with the talent signed in.',
   ].join('\n');
 }

package/src/mcp-profile-tools.js

@@ -37,6 +37,7 @@ function makeProfileTools(deps = {}) {
       description: 'Shows your main role, your rate and your "My work with AI" summary on Shakers.',
       guidance: "Get the talent's summary: main role, per-project rate, and the 'My work with AI' read model (setup/usage tier+level, 3x3 cell, vision, how-I-work). Requires an active session. Present it in human terms; any internal ids/codes in the result are handles for tools only — never show or mention them to the talent.",
       inputSchema: GET_PROFILE_SCHEMA,
+      annotations: { readOnlyHint: true },
       handler: getProfile,
     },
   ];

package/src/mcp-role-tools.js

@@ -11,7 +11,9 @@ 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;
+// Cap on the waitSeconds the model may pass; kept under Claude Desktop's ~60 s tool-call cap, higher than
+// the old 25 so fewer polls (and fewer approval prompts) cover the ~90 s finalization.
+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 };

package/src/mcp-server.js

@@ -107,7 +107,7 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
     }
   }
 
-  // `description` and `title` are what the talent reads in the client; `guidance` is how the model must use the tool, so it rides in the schema.
+  // `description` and `title` are what the talent reads in the client; `guidance` is how the model must use the tool, so it rides in the schema. `annotations` (e.g. readOnlyHint) is a standard MCP hint that passes straight through for clients that act on it.
   function shapeTool(t) {
     const schema = t.inputSchema || { type: 'object' };
     return {
@@ -115,6 +115,7 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
       ...(t.title ? { title: t.title } : {}),
       description: t.description || '',
       inputSchema: t.guidance ? { ...schema, description: [t.guidance, schema.description].filter(Boolean).join(' ') } : schema,
+      ...(t.annotations ? { annotations: t.annotations } : {}),
     };
   }
 

package/src/mcp-signup-tools.js

@@ -18,7 +18,11 @@ const { NOOP_FUNNEL, weeklyHours, rateTypes, workSituationValue } = require('./o
 const SIGNUP_WINDOW_TIMEOUT_MS = 15 * 60 * 1000;
 // The browser opens this long after the tool answers, so the AI's reply is on screen first.
 const BROWSER_OPEN_DELAY_MS = 4000;
-const MAX_WAIT_SECONDS = 25;
+// Each signup_status call holds up to this long waiting for a change, so a higher value means fewer calls
+// (and fewer per-call approval prompts in the client) cover the same wait. Kept under the ~60 s hard cap
+// Claude Desktop puts on a tool call (progress notifications do not extend it there), with margin for the
+// round-trip.
+const MAX_WAIT_SECONDS = 45;
 const IMPORT_POLL_MS = 3000;
 // Languages the profile importer writes in.
 const IMPORT_LANGUAGES = new Set(['es', 'en', 'it', 'pt', 'fr']);
@@ -667,7 +671,7 @@ function makeSignupTools(deps = {}) {
       ...(cvNote ? { cvNote } : {}),
       next: 'signup_status',
       message: (reused ? 'The sign-up window was already open; it now uses the new data. ' : 'The window opens in the talent\'s browser in a few seconds; they read how it works in the draft they confirmed. ')
-        + 'Say nothing about the window. Only if they say it did not open, call signup_status with windowLink:true. Now call signup_status (waitSeconds 20) until the account exists.',
+        + 'Say nothing about the window. Only if they say it did not open, call signup_status with windowLink:true. Now call signup_status (waitSeconds 45) until the account exists.',
     };
   }
 
@@ -703,7 +707,7 @@ function makeSignupTools(deps = {}) {
   }
 
   function nextSteps(account) {
-    const interview = 'Then the onboarding interview: if onboardingInterview.completed is true, skip it without mentioning it; otherwise call onboarding_interview_start without disclaimerAcknowledged (it asks here now or later on the web). Then, also if they skip it, the main role: list_my_roles (waitSeconds 20), then set_main_role without clusterId only when its next says so. Finally open_web.';
+    const interview = 'Then the onboarding interview: if onboardingInterview.completed is true, skip it without mentioning it; otherwise call onboarding_interview_start without disclaimerAcknowledged (it asks here now or later on the web). Then, also if they skip it, the main role: list_my_roles (waitSeconds 45), then set_main_role without clusterId only when its next says so. Finally open_web.';
     const aiUsage = 'Then ai_usage without consent: it returns the two AI-usage disclaimers and the question (show them right before asking; no scan happens before a yes).';
     if (account.state === 'existing') {
       return `This talent already had an account and signed in. Call update_existing_profile: it shows what would change and asks whether to update, and its text tells the talent about the account, so say nothing about it yourself. ${aiUsage} ${interview}`;
@@ -1121,8 +1125,9 @@ function makeSignupTools(deps = {}) {
       name: 'signup_status',
       title: 'Sign-up progress',
       description: 'Shows whether your account is ready and how the import of your profile is going.',
-      guidance: "State of the sign-up: account (waiting | created | existing | failed) and, once it exists, the profile import per source (linkedin, cv: running | done | failed). Pass waitSeconds (up to 25) to wait for a change. Follow `message`: it gives the remaining steps. Never show internal codes to the talent.",
+      guidance: "State of the sign-up: account (waiting | created | existing | failed) and, once it exists, the profile import per source (linkedin, cv: running | done | failed). Pass waitSeconds (up to 45) to wait for a change; a high value means fewer calls cover the wait. Follow `message`: it gives the remaining steps. Never show internal codes to the talent.",
       inputSchema: STATUS_SCHEMA,
+      annotations: { readOnlyHint: true },
       handler: signupStatus,
     },
     {