shakers-cli-beta 0.8.0-beta.0

package/src/mcp-register-tools.js

@@ -0,0 +1,517 @@
+'use strict';
+
+const {
+  FREELANCE_TYPES, WORK_SITUATIONS, EMPLOYMENT_PARTICIPATIONS, FREELANCE_OPINIONS,
+  CHANGE_MOTIVATORS, MONTHLY_HOURS, LANGUAGE_CODES, LANGUAGE_LEVELS,
+} = require('./onboarding-flow');
+const { getCatalog } = require('./i18n');
+const { TranscriptBuffer } = require('./interview-transcript');
+
+const MONTHLY_HOURS_QUOTED = MONTHLY_HOURS.map((h) => `'${h}'`).join(', ');
+const MONTHLY_HOURS_SLASHED = MONTHLY_HOURS.join('/');
+
+// "Friendly label (CODE)" list from an i18n label map: the talent sees the label, the model passes the canonical code.
+function labelledOptions(codes, labels) {
+  return codes.map((code) => `${labels[code] || code} (${code})`).join(', ');
+}
+
+function buildSchemas(lang) {
+  const L = getCatalog(lang).onboarding;
+  const showLabel = 'Show the talent the label, pass the code';
+
+  const ACCOUNT_FIELDS = {
+    name: { type: 'string', description: "The talent's first name, as they give it in the chat." },
+    lastName: { type: 'string', description: "The talent's last name, as they give it in the chat." },
+    email: { type: 'string', description: "The talent's own email address, used as their account login. They give it in the chat." },
+    preferredLanguage: { type: 'string', enum: ['ES', 'EN', 'IT', 'PT', 'FR'], description: 'Preferred language as an UPPERCASE ISO code. Optional — defaults to the session language.' },
+    newsletterConsent: { type: 'boolean', description: 'Whether the talent agrees to receive the newsletter. Optional, defaults to false.' },
+    freelanceType: { type: 'string', enum: FREELANCE_TYPES, description: `How the talent is set up to work. ${showLabel}: ${labelledOptions(FREELANCE_TYPES, L.freelanceTypeLabels)}. Distinct from workSituation below (that is the CURRENT freelance/employed/etc situation).` },
+  };
+
+  const WORK_SITUATION_SCHEMA = {
+    type: 'object',
+    description: "The talent's current work situation (ADR-036), asked once after account creation — the same question the web's registration flow asks. NOT the same thing as freelanceType above.",
+    properties: {
+      situation: { type: 'string', enum: WORK_SITUATIONS, description: `Current work situation. ${showLabel}: ${labelledOptions(WORK_SITUATIONS, L.workSituationLabels)}. 'EMPLOYED' requires participation below.` },
+      participation: { type: 'string', enum: EMPLOYMENT_PARTICIPATIONS, description: `Only when situation is 'EMPLOYED'. ${showLabel}: ${labelledOptions(EMPLOYMENT_PARTICIPATIONS, L.employmentParticipationLabels)}.` },
+      opinion: { type: 'string', enum: FREELANCE_OPINIONS, description: `The talent's opinion on freelancing. ${showLabel}: ${labelledOptions(FREELANCE_OPINIONS, L.freelanceOpinionLabels)}. Required unless situation is 'FREELANCE' (implied ALREADY_FREELANCE).` },
+      changeMotivators: { type: 'string', enum: CHANGE_MOTIVATORS, description: `What motivates the talent about freelancing/Shakers. ${showLabel}: ${labelledOptions(CHANGE_MOTIVATORS, L.changeMotivatorLabels)}. Required only when the talent is or is considering freelance (situation 'FREELANCE', or opinion 'WAS_FREELANCE_BEFORE'/'OPEN_TO_FREELANCE'); omit when opinion is 'NOT_INTERESTED'.` },
+    },
+    required: ['situation'],
+  };
+
+  const LANGUAGES_SCHEMA = {
+    type: 'array',
+    description: `Languages the talent speaks (ADR-036). ALWAYS ask this — it must not be skipped. ${showLabel}. Language options: ${labelledOptions(LANGUAGE_CODES, L.languageNames)}; and for each language a level: ${labelledOptions(LANGUAGE_LEVELS, L.languageLevelLabels)}. Bulk upsert — send the talent’s FULL language list. Omit only if the talent explicitly declines.`,
+    items: {
+      type: 'object',
+      properties: {
+        language: { type: 'string', enum: LANGUAGE_CODES, description: `Language code. ${showLabel}: ${labelledOptions(LANGUAGE_CODES, L.languageNames)}.` },
+        level: { type: 'string', enum: LANGUAGE_LEVELS, description: `Language level. ${showLabel}: ${labelledOptions(LANGUAGE_LEVELS, L.languageLevelLabels)}.` },
+      },
+      required: ['language', 'level'],
+    },
+  };
+
+  const AVAILABILITY_SCHEMA = {
+    type: 'object',
+    description: `Availability AND location (ADR-028). ALWAYS ask this — it must not be skipped. There is NO separate location field: the talent's LOCATION (country, timezone, region) lives here. Offer the options: available (yes/no); monthlyHours must be one of ${MONTHLY_HOURS_QUOTED}; onlyRemote (yes/no — accepts only remote work); longFullTimeProjects (yes/no — open to long full-time projects). For location, ask the talent their country and timezone (region is optional). All fields optional/nullable, but collect what you can. monthlyHours is a STRICT enum string (not an int). city is not collected here.`,
+    properties: {
+      available: { type: 'boolean', description: 'Whether the talent is currently available (yes/no).' },
+      monthlyHours: { type: 'string', enum: MONTHLY_HOURS, description: `Monthly hours the talent can work, exactly one of: ${MONTHLY_HOURS_QUOTED} (send '> 160' verbatim, with the space).` },
+      onlyRemote: { type: 'boolean', description: 'Whether the talent accepts only remote work (yes/no).' },
+      country: { type: 'string', description: 'LOCATION — ISO-2 country code, 2 letters (e.g. ES, US, GB).' },
+      timezone: { type: 'string', description: 'LOCATION — IANA timezone (e.g. Europe/Madrid, America/New_York). Max 100 chars.' },
+      subdivision: { type: 'string', description: 'LOCATION — optional region/state code (e.g. ES-CT). Max 10 chars.' },
+      longFullTimeProjects: { type: 'boolean', description: 'Whether the talent is open to long full-time projects (yes/no).' },
+    },
+  };
+
+  const REGISTER_SCHEMA = {
+    type: 'object',
+    properties: {
+      ...ACCOUNT_FIELDS,
+      profile: PROFILE_SCHEMA,
+      workSituation: WORK_SITUATION_SCHEMA,
+      pricing: PRICING_SCHEMA,
+      availability: AVAILABILITY_SCHEMA,
+      languages: LANGUAGES_SCHEMA,
+      phone: PHONE_SCHEMA,
+    },
+    required: ['name', 'lastName', 'email', 'freelanceType', 'profile', 'workSituation', 'pricing'],
+  };
+
+  return { ACCOUNT_FIELDS, WORK_SITUATION_SCHEMA, LANGUAGES_SCHEMA, AVAILABILITY_SCHEMA, REGISTER_SCHEMA };
+}
+
+// The register tool's own long description, per language: the batched
+// collection guide with friendly labels inline for every choice field.
+function buildRegisterDescription(lang) {
+  const L = getCatalog(lang).onboarding;
+  return "The talent registers THEMSELVES on Shakers (self-service; no prior session needed). Your job is to relay the non-secret profile details the talent gives you in the chat as arguments. Credentials never touch the chat or any tool argument: the tool opens a sign-up window on the talent's own machine (127.0.0.1) where they either Continue with Google (no password at all) or type an email and password directly into that local window.\n\nCOLLECT THE DETAILS IN A FEW GROUPED BATCHES, not one field at a time, and for every CHOICE field PRESENT THE VALID OPTIONS so the talent just picks one. For every choice field SHOW THE TALENT THE FRIENDLY LABEL, never the raw code (e.g. show 'Nativo', not 'NATIVE'), and pass the code as the value. Suggested batches:\n1. Identity — name, lastName, email (optional: preferredLanguage, newsletterConsent).\n2. Profile — `profile.linkedinUrl` (required source; optional GitHub/website/CV path).\n3. Work — freelanceType (offer: "
+    + labelledOptions(FREELANCE_TYPES, L.freelanceTypeLabels)
+    + ") and `workSituation` (offer situation: "
+    + labelledOptions(WORK_SITUATIONS, L.workSituationLabels)
+    + "; participation "
+    + labelledOptions(EMPLOYMENT_PARTICIPATIONS, L.employmentParticipationLabels)
+    + " only when EMPLOYED; opinion "
+    + labelledOptions(FREELANCE_OPINIONS, L.freelanceOpinionLabels)
+    + " unless FREELANCE; changeMotivators "
+    + labelledOptions(CHANGE_MOTIVATORS, L.changeMotivatorLabels)
+    + " when the talent is or is considering freelance).\n4. Pricing — per-PROJECT price; currency USD, EUR or GBP.\n5. Availability + languages — `availability` (offer monthlyHours "
+    + MONTHLY_HOURS_SLASHED
+    + ", onlyRemote yes/no, longFullTimeProjects yes/no, and LOCATION: country as ISO-2 e.g. ES, timezone as IANA e.g. Europe/Madrid) and `languages` (offer "
+    + labelledOptions(LANGUAGE_CODES, L.languageNames)
+    + ", each with a level "
+    + labelledOptions(LANGUAGE_LEVELS, L.languageLevelLabels)
+    + ").\n6. Contact — `phone` (telephoneCode e.g. +34 and telephoneNumber).\n\nALWAYS ask for availability (including location), languages and phone — they are expected, not optional extras; only omit one if the talent explicitly declines. There is NO separate location field: location (country/timezone/region) is part of `availability`.\n\nOnce the window completes the account exists and the session is set; the tool then starts the background profile import, saves the work situation, per-PROJECT pricing (ADR-024), and any availability/languages/phone provided. If the account already exists, the tool returns { accountAlreadyExists: true } — switch to the login tool (method 'google') instead. Returns { importJobId, next, disclaimers, profileUrl }. `next` is 'ai_usage' when the talent has no prior AI-usage evidence (offer step 4, the ai_usage tool) or 'onboarding_interview_start' when they already do (step 4 is skipped). When you run ai_usage as this step, pass the returned `usageRepoScope` ({ mode: 'all' }) — registration always measures the whole machine, never a single repo. Before running ai_usage OR onboarding_interview_start, show the talent the matching `disclaimers` block, its two parts (info accessed, goal+duration) separately. Poll register_status with the importJobId to track the import. Always finish any path by calling onboarding_finish (whether or not the talent takes steps 4 and 5) — that is what marks the onboarding complete and moves the talent's registration level.";
+}
+
+const PHONE_SCHEMA = {
+  type: 'object',
+  description: "Phone (ADR-036). ALWAYS ask this — it must not be skipped. Two parts: telephoneCode = the international dialling code (e.g. +34, +1, +44), telephoneNumber = the local number. Omit only if the talent explicitly declines to share it.",
+  properties: {
+    telephoneCode: { type: 'string', description: "International dialling code, e.g. '+34', '+1', '+44'. Max 10 chars." },
+    telephoneNumber: { type: 'string', description: 'Local phone number. Max 20 chars.' },
+  },
+  required: ['telephoneCode', 'telephoneNumber'],
+};
+
+const PROFILE_SCHEMA = {
+  type: 'object',
+  properties: {
+    linkedinUrl: { type: 'string', description: "The talent's LinkedIn URL. Required — it is the mandatory profile source." },
+    cvPath: { type: 'string', description: 'Absolute path to a CV PDF on the machine (optional).' },
+    githubUrl: { type: 'string', description: 'GitHub URL (optional).' },
+    websiteUrl: { type: 'string', description: 'Personal website URL (optional).' },
+  },
+  required: ['linkedinUrl'],
+};
+
+const PRICING_SCHEMA = {
+  type: 'object',
+  description: 'Per-PROJECT pricing (ADR-024). NOT hourly or annual. Amounts are the whole project price as a plain number, no thousands separators, at most 2 decimals, 0..999999.99. Currency is USD, EUR or GBP. The full-time (standard) price is the primary one and should always be captured, exactly as the CLI asks it; part-time is an additional modality. At least one variant must be selected.',
+  properties: {
+    fullTimeSelected: { type: 'boolean', description: 'Whether the talent offers full-time projects. This standard/full-time price is the primary one — capture it by default.' },
+    fullTimeAmount: { type: 'number', description: 'Full-time (standard) per-project price, plain number without thousands separators (e.g. 60000).' },
+    fullTimeCurrency: { type: 'string', enum: ['USD', 'EUR', 'GBP'], description: 'Currency for the full-time price.' },
+    partTimeSelected: { type: 'boolean', description: 'Whether the talent also offers part-time projects (additional modality).' },
+    partTimeAmount: { type: 'number', description: 'Part-time per-project price, plain number without thousands separators (e.g. 50).' },
+    partTimeCurrency: { type: 'string', enum: ['USD', 'EUR', 'GBP'], description: 'Currency for the part-time price.' },
+  },
+};
+
+// Default (English) static exports for callers/tests that read the module-level
+// schemas directly. The live tools rebuild these per session language.
+const { ACCOUNT_FIELDS, WORK_SITUATION_SCHEMA, LANGUAGES_SCHEMA, AVAILABILITY_SCHEMA, REGISTER_SCHEMA } = buildSchemas('en');
+
+const STATUS_SCHEMA = {
+  type: 'object',
+  properties: { jobId: { type: 'string', description: 'The importJobId returned by register — an internal handle for polling; never shown or mentioned to the talent.' } },
+  required: ['jobId'],
+};
+
+const INTERVIEW_START_SCHEMA = {
+  type: 'object',
+  properties: {
+    candidateId: { type: 'string', description: "Talent UUID (the JWT sub). Optional — defaults to the signed-in talent's UUID derived from the session. An email is NOT accepted by the server." },
+    language: { type: 'string', enum: ['es', 'en'] },
+    disclaimerAcknowledged: {
+      type: 'boolean',
+      description: 'Must be true. Set it only after showing the talent BOTH interview disclaimers separately (info accessed AND goal+duration) from the register response, and getting their agreement.',
+    },
+    confirmRepeat: {
+      type: 'boolean',
+      description: 'Only needed when the talent has ALREADY completed onboarding. The tool then refuses with an already-completed notice unless you set this true after the talent explicitly confirms they want to repeat the interview.',
+    },
+  },
+  required: ['disclaimerAcknowledged'],
+};
+
+const INTERVIEW_TURN_SCHEMA = {
+  type: 'object',
+  properties: {
+    interviewId: { type: 'string', description: 'Internal handle for this interview — for calling the interview tools ONLY; never shown or mentioned to the talent.' },
+    message: { type: 'string', description: "The talent's REAL, VERBATIM answer to the current question. NEVER invent, infer, complete, translate, or answer on the talent's behalf. If the talent has not answered yet, do NOT call this — wait for their actual words." },
+  },
+  required: ['interviewId', 'message'],
+};
+
+const INTERVIEW_COMPLETE_SCHEMA = {
+  type: 'object',
+  properties: { interviewId: { type: 'string' } },
+  required: ['interviewId'],
+};
+
+const FINISH_SCHEMA = { type: 'object', properties: {} };
+
+function makeRegisterTools(deps = {}) {
+  const flow = require('./onboarding-flow');
+  const resolved = flow.makeDeps(deps.flowDeps || {});
+  const lang = deps.lang || 'en';
+  const schemas = buildSchemas(lang);
+  const registerDescription = buildRegisterDescription(lang);
+  // Same confirmation copy the CLI prints ("Price saved.", …), reused verbatim.
+  const catalog = require('./i18n').getCatalog(lang).onboarding;
+  const runLoopbackAuth = deps.runLoopbackAuth || require('./mcp-auth-form').runLoopbackAuth;
+  const checkCompleted = deps.checkOnboardingCompleted || require('./onboarding-availability').checkOnboardingCompleted;
+
+  // The LiveKit room is a live WebRTC connection that must survive between the
+  // separate start/turn/complete JSON-RPC calls of this long-lived stdio server.
+  const interviewSessions = new Map();
+
+  function connectHint(kind) {
+    if (kind === 'livekit-not-installed') return catalog.livekitMissing;
+    if (kind === 'livekit-no-text-streams') return catalog.livekitOld;
+    return catalog.livekitConnectError;
+  }
+
+  async function teardownInterview(interviewId, { persist = false } = {}) {
+    const sess = interviewSessions.get(interviewId);
+    if (!sess) return { ok: true };
+    interviewSessions.delete(interviewId);
+    let saved = { ok: true };
+    if (persist && sess.buffer.length > 0) {
+      const durationSeconds = Math.max(0, Math.floor((Date.now() - sess.connectAt) / 1000));
+      saved = await flow.completeLivekitOnboarding(resolved, {
+        interviewId,
+        durationSeconds,
+        transcripts: sess.buffer.toTranscripts(),
+      });
+    }
+    try { await sess.client.disconnect(); } catch { /* room already gone */ }
+    return saved;
+  }
+
+  async function register(args = {}) {
+    const registerFields = {
+      name: args.name,
+      lastName: args.lastName,
+      email: args.email,
+      preferredLanguage: args.preferredLanguage,
+      newsletterConsent: args.newsletterConsent === true,
+      freelanceType: args.freelanceType,
+    };
+    const check = flow.validateRegisterFields(registerFields);
+    if (!check.ok) return { ok: false, step: 'signup', reason: check.reason };
+
+    const created = await runLoopbackAuth({ mode: 'register', deps: resolved, lang, registerFields });
+    if (created.viaGoogle) {
+      // Social registration is the device flow (start/poll tools), not this single blocking call.
+      return {
+        ok: false,
+        step: 'signup',
+        reason: 'use-device-flow',
+        next: 'social_signin_start',
+        mode: 'register',
+        message: `To register with a social provider, call social_signin_start (provider "google" or "linkedin", mode "register", freelanceType "${registerFields.freelanceType || ''}") to get a URL and code to show the talent, then social_signin_poll. Once it returns authorized, run the profile steps (import, work situation, pricing).`,
+      };
+    }
+    if (!created.ok) {
+      return { ok: false, step: 'signup', reason: created.reason };
+    }
+
+    const profile = args.profile || {};
+    const importRes = await flow.startProfileImport(resolved, {
+      linkedinUrl: profile.linkedinUrl,
+      cvPath: profile.cvPath,
+      githubUrl: profile.githubUrl,
+      websiteUrl: profile.websiteUrl,
+      language: lang,
+    });
+    const importOutcome = importRes.ok
+      ? { ok: true, jobId: importRes.jobId, state: importRes.state }
+      : { ok: false, reason: importRes.reason, warning: 'Profile import is unavailable right now; registration continues and the import can be retried later.' };
+
+    const workSituationRes = await flow.saveWorkSituation(resolved, args.workSituation || {});
+    if (!workSituationRes.ok) return { ok: false, step: 'work-situation', reason: workSituationRes.reason };
+
+    const priceRes = await flow.savePricing(resolved, args.pricing || {});
+    if (!priceRes.ok) return { ok: false, step: 'pricing', reason: priceRes.reason };
+
+    let availabilityOutcome = { skipped: true };
+    if (args.availability && typeof args.availability === 'object') {
+      const availRes = await flow.saveAvailability(resolved, args.availability);
+      availabilityOutcome = availRes.ok
+        ? { ok: true }
+        : { ok: false, reason: availRes.reason, warning: 'Availability could not be saved; registration continues and it can be set later.' };
+    }
+
+    let languagesOutcome = { skipped: true };
+    if (Array.isArray(args.languages) && args.languages.length > 0) {
+      const langRes = await flow.saveLanguages(resolved, args.languages);
+      languagesOutcome = langRes.ok
+        ? { ok: true }
+        : { ok: false, reason: langRes.reason, unresolved: langRes.unresolved, warning: 'Languages could not be saved; registration continues and they can be added later.' };
+    }
+
+    let phoneOutcome = { skipped: true };
+    if (args.phone && typeof args.phone === 'object') {
+      const phoneRes = await flow.savePhone(resolved, args.phone);
+      phoneOutcome = phoneRes.ok
+        ? { ok: true }
+        : { ok: false, reason: phoneRes.reason, warning: 'Phone could not be saved; registration continues and it can be set later.' };
+    }
+
+    const prior = await flow.detectPriorUsage(resolved);
+    const hasEvidence = prior.ok ? prior.hasEvidence : null;
+
+    // Human-readable confirmations, identical to the CLI step notices.
+    const confirmations = [catalog.accountReady, catalog.professionalSaved, catalog.pricingSaved];
+    if (importOutcome.ok) confirmations.push(catalog.importDone);
+    if (availabilityOutcome.ok) confirmations.push(catalog.availabilitySaved);
+    if (languagesOutcome.ok) confirmations.push(catalog.languagesSaved);
+    if (phoneOutcome.ok) confirmations.push(catalog.phoneSaved);
+
+    return {
+      ok: true,
+      message: catalog.accountReady,
+      confirmations,
+      import: importOutcome,
+      importJobId: importOutcome.jobId || null,
+      availability: availabilityOutcome,
+      languages: languagesOutcome,
+      phone: phoneOutcome,
+      priorUsage: { hasEvidence },
+      next: hasEvidence === true ? 'onboarding_interview_start' : 'ai_usage',
+      usageRepoScope: { mode: 'all' },
+      disclaimers: {
+        usage: flow.usageDisclaimers(lang),
+        interview: flow.interviewDisclaimers(lang),
+      },
+      profileUrl: flow.profileUrl(resolved),
+    };
+  }
+
+  async function registerStatus(args = {}) {
+    const res = await flow.pollProfileImport(resolved, { jobId: args.jobId });
+    return res.ok ? { ok: true, state: res.state } : { ok: false, reason: res.reason };
+  }
+
+  async function interviewStart(args = {}) {
+    let alreadyCompleted = false;
+    try {
+      alreadyCompleted = await checkCompleted({});
+    } catch {
+      alreadyCompleted = false;
+    }
+    if (alreadyCompleted && args.confirmRepeat !== true) {
+      return {
+        ok: false,
+        reason: 'onboarding-already-completed',
+        alreadyCompleted: true,
+        message:
+          'You have already completed the onboarding interview. Re-running it is optional. If the talent explicitly wants to repeat it, call again with confirmRepeat:true.',
+      };
+    }
+    if (args.disclaimerAcknowledged !== true) {
+      return {
+        ok: false,
+        reason: 'disclaimers-not-acknowledged',
+        disclaimers: flow.interviewDisclaimers(lang),
+        message: 'Show the talent BOTH interview disclaimers separately (info accessed AND goal+duration), then call again with disclaimerAcknowledged:true.',
+      };
+    }
+    const start = await flow.createAndStartLivekitOnboarding(resolved, {
+      candidateId: args.candidateId,
+      language: args.language || lang,
+    });
+    if (!start.ok) return { ok: false, step: start.step || 'start', reason: start.reason };
+
+    const closing = start.closingMessage;
+    const isClosing = closing ? (t) => typeof t === 'string' && t.includes(closing) : null;
+    const client = resolved.makeInterviewClient({ isClosing });
+    const buffer = new TranscriptBuffer();
+
+    try {
+      await client.connect(start.livekitUrl, start.token);
+    } catch (e) {
+      try { await client.disconnect(); } catch { /* nothing joined */ }
+      const kind = (e && e.kind) || 'connect-failed';
+      return { ok: false, step: 'connect', reason: kind, message: connectHint(kind) };
+    }
+
+    let opening;
+    try {
+      opening = await client.receiveTurn();
+    } catch (e) {
+      try { await client.disconnect(); } catch { /* room already gone */ }
+      return { ok: false, step: 'greeting', reason: (e && e.kind) || 'no-greeting' };
+    }
+    buffer.recordAgent(opening.text);
+    interviewSessions.set(start.interviewId, { client, buffer, connectAt: Date.now(), ended: opening.ended === true });
+    return { ok: true, interviewId: start.interviewId, greeting: opening.text, ended: opening.ended === true };
+  }
+
+  async function interviewTurn(args = {}) {
+    const sess = interviewSessions.get(args.interviewId);
+    if (!sess) {
+      return { ok: false, reason: 'unknown-interview', message: 'No live interview for that interviewId (the server may have restarted). Start again with onboarding_interview_start.' };
+    }
+    if (sess.ended) return { ok: true, response: '', ended: true };
+
+    const message = typeof args.message === 'string' ? args.message : '';
+    sess.buffer.recordUser(message);
+    let res;
+    try {
+      res = await sess.client.sendTurn(message);
+    } catch (e) {
+      await teardownInterview(args.interviewId, { persist: true });
+      return { ok: false, reason: (e && e.kind) || 'turn-error', message: 'The interview connection failed; the transcript so far was saved. Start again with onboarding_interview_start.' };
+    }
+    sess.buffer.recordAgent(res.text);
+    if (res.ended === true) sess.ended = true;
+    return { ok: true, response: res.text, ended: res.ended === true };
+  }
+
+  async function interviewComplete(args = {}) {
+    if (!interviewSessions.has(args.interviewId)) {
+      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' };
+    return { ok: true, state: 'taken', message: catalog.interviewComplete };
+  }
+
+  // OVERWRITE-repeat: reset the taken onboarding interview so it can be re-run.
+  async function repeatOnboarding() {
+    const reset = await flow.restartOnboarding(resolved);
+    if (!reset.ok) {
+      if (reset.reason === 'onboarding-not-found') {
+        return { ok: false, reason: 'onboarding-not-found', message: 'The talent has no onboarding interview yet — run the normal onboarding first (register + onboarding_interview_start), nothing to repeat.' };
+      }
+      return { ok: false, reason: reset.reason };
+    }
+    return {
+      ok: true,
+      interviewId: reset.interviewId,
+      language: reset.language,
+      next: 'onboarding_interview_start',
+      message: 'Onboarding reset — the previous interview was overwritten. Now run it again with onboarding_interview_start; do NOT run the main-role step (that belongs to first-time registration) — go straight to onboarding_finish.',
+    };
+  }
+
+  async function onboardingFinish() {
+    const fin = await flow.completeOnboardingRegistration(resolved);
+    if (!fin.ok) return { ok: false, finalized: false, reason: fin.reason, profileUrl: flow.profileUrl(resolved) };
+    const pct = fin.completedProfilePercentage;
+    return {
+      ok: true,
+      finalized: true,
+      message: typeof pct === 'number' ? catalog.finalizedAt(pct) : catalog.finalizedGeneric,
+      onboardingStatus: fin.onboardingStatus,
+      registrationLevel: fin.registrationLevel,
+      completedProfilePercentage: pct,
+      profileUrl: flow.profileUrl(resolved),
+    };
+  }
+
+  return [
+    {
+      name: 'register',
+      description: registerDescription,
+      inputSchema: schemas.REGISTER_SCHEMA,
+      handler: register,
+    },
+    {
+      name: 'register_status',
+      description: 'Check the state of the background profile import started by register. Pass the importJobId (an internal handle — never shown to the talent). Returns { state } (e.g. running | done | failed).',
+      inputSchema: STATUS_SCHEMA,
+      handler: registerStatus,
+    },
+    {
+      name: 'onboarding_interview_start',
+      description: "Start the onboarding interview (step 5, optional). Runs over LiveKit: the server joins a live room and the agent conducts it, transparently resolving the branch (role/dedication only when AI-usage evidence exists, otherwise the AI-usage blocks too) — the client does NOT decide the branch. You MUST first show the talent BOTH interview disclaimers separately (from register's disclaimers.interview) and only then call with disclaimerAcknowledged:true. Returns { interviewId, greeting, ended }: relay the greeting to the talent VERBATIM, then drive the interview with onboarding_interview_turn. INTERVIEW RULE — you are a pure CONDUIT, never a participant: show every interview question to the talent VERBATIM (do not reword, clarify, summarize, translate, or add your own hints/examples/answers), and only ever pass the talent's REAL, VERBATIM words back. Do NOT opine, guide, correct, interpret, or answer for the talent at any point. `interviewId` is an internal handle for the interview tools only — never show or mention it to the talent. If it returns reason 'livekit-not-installed', relay the `message` (it tells the talent how to install the optional @livekit/rtc-node package). If the talent declines the interview, do not call this — instead run the final main-role step (list_my_roles + set_main_role) and offer them their profile URL from register. If the talent has ALREADY completed onboarding this refuses with an already-completed notice unless confirmRepeat:true; note a completed onboarding interview cannot actually be restarted (it returns reason 'interview-already-started') — in that case just run set_main_role.",
+      inputSchema: INTERVIEW_START_SCHEMA,
+      handler: interviewStart,
+      available: async () => {
+        try {
+          return !(await checkCompleted({ timeoutMs: 3000 }));
+        } catch {
+          return true;
+        }
+      },
+    },
+    {
+      name: 'onboarding_interview_turn',
+      description: "Send the talent's answer to the current onboarding-interview question and get the next one. You are a pure CONDUIT: pass ONLY the talent's REAL, VERBATIM answer in `message` — NEVER invent, infer, complete, or answer on their behalf; if they have not answered, do NOT call this, wait for them. Relay the returned `response` (the next question) to the talent VERBATIM — do not reword, clarify, summarize, translate, or add hints/examples/opinions of your own. Keep calling with their next `message` until `ended` is true, then call onboarding_interview_complete. Do NOT show or mention `interviewId` to the talent (internal handle). If it returns reason 'unknown-interview' (the server was restarted and the live room is gone), start again with onboarding_interview_start.",
+      inputSchema: INTERVIEW_TURN_SCHEMA,
+      handler: interviewTurn,
+    },
+    {
+      name: 'onboarding_interview_complete',
+      description: "Close the onboarding interview once the turns report ended:true: the buffered transcript is saved and the live room is disconnected. `interviewId` is an internal handle for the interview tools only — never show or mention it to the talent. Returns { state:'taken' }. If it returns reason 'unknown-interview' the room was already gone (server restart) — nothing to complete. After this, if this is first-time REGISTRATION, run the final registration step — offer the talent their main role with list_my_roles + set_main_role — then call onboarding_finish. If you got here from repeat_onboarding_interview (a re-run, not registration), SKIP the main-role step and go straight to onboarding_finish. To change the main role outside registration, the talent uses change-role.",
+      inputSchema: INTERVIEW_COMPLETE_SCHEMA,
+      handler: interviewComplete,
+    },
+    {
+      name: 'repeat_onboarding_interview',
+      description: "OVERWRITE-repeat the onboarding interview: resets the talent's completed onboarding interview IN PLACE — the previous evaluation is DISCARDED and CANNOT be recovered. You MUST clearly warn the talent that this overwrites their previous onboarding and is irreversible, and get their explicit go-ahead, BEFORE calling this. On success run the interview again (onboarding_interview_start → onboarding_interview_turn until ended → onboarding_interview_complete), then onboarding_finish. This is a RE-RUN, not registration: do NOT run the main-role step (list_my_roles/set_main_role) afterwards — to change the main role outside registration the talent uses change-role. Returns { interviewId, language } or reason 'onboarding-not-found' (the talent has no onboarding yet — do the normal onboarding first), 'http-401'/'http-403'.",
+      inputSchema: { type: 'object', properties: {} },
+      handler: repeatOnboarding,
+    },
+    {
+      name: 'onboarding_finish',
+      description: "Mark the onboarding as complete — the TERMINAL step, ALWAYS call it once the mandatory steps (register) are done, whether the talent took OR skipped the AI-usage evaluation and the interview. This flips their onboarding status to COMPLETED and lets Shakers promote their registration level (the metrics the team tracks). Idempotent: safe to call once at the end of any path. Returns { finalized, onboardingStatus, registrationLevel, completedProfilePercentage, profileUrl }: use completedProfilePercentage to tell the talent how complete their profile is, and profileUrl to point them to it.",
+      inputSchema: FINISH_SCHEMA,
+      handler: onboardingFinish,
+    },
+  ];
+}
+
+module.exports = {
+  makeRegisterTools,
+  ACCOUNT_FIELDS,
+  REGISTER_SCHEMA,
+  STATUS_SCHEMA,
+  INTERVIEW_START_SCHEMA,
+  INTERVIEW_TURN_SCHEMA,
+  INTERVIEW_COMPLETE_SCHEMA,
+  FINISH_SCHEMA,
+  PROFILE_SCHEMA,
+  WORK_SITUATION_SCHEMA,
+  PRICING_SCHEMA,
+  AVAILABILITY_SCHEMA,
+  LANGUAGES_SCHEMA,
+  PHONE_SCHEMA,
+};

package/src/mcp-report-tools.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const REPORT_SCHEMA = {
+  type: 'object',
+  properties: {
+    root: { type: 'string', description: 'Repository root whose report to materialize. Defaults to the server working directory. Ignored when stored is true.' },
+    lang: { type: 'string', enum: ['es', 'en'] },
+    stored: { type: 'boolean', description: "When true, return the talent's ENTIRE stored server report (inventory + activity + AI-fluency level + prompting/interaction level) as plain text, read from the certs endpoint WITHOUT re-running any scan. When false/omitted, build the local shareable HTML report and return its file path." },
+  },
+};
+
+const SHARE_SCHEMA = {
+  type: 'object',
+  properties: {
+    root: { type: 'string', description: 'Repository root whose share card to generate. Defaults to the server working directory.' },
+  },
+};
+
+function makeReportTools(deps = {}) {
+  const {
+    materializeProjectReport = require('./report-store').materializeProjectReport,
+    loadFootprint = require('./report-store').loadFootprint,
+    generateShareCard = require('./share-card').generateShareCard,
+    loadAuthSession = require('./auth-session-store').loadAuthSession,
+    sessionStatus = require('./auth-session-store').sessionStatus,
+    getUsageReportEndpoint = require('./config').getUsageReportEndpoint,
+    requestUsageReport = require('./report-view-client').requestUsageReport,
+    renderUsageReportText = require('./render-usage-report-text').renderUsageReportText,
+    renderFullReportText = require('./render-report-text').renderFullReportText,
+    detectFlowLang = require('./i18n').detectFlowLang,
+  } = deps;
+
+  const requireSession = () => {
+    const session = loadAuthSession();
+    if (sessionStatus(session) !== 'active') {
+      throw new Error('no active Shakers session — call the login tool (or run `shakers login`) first.');
+    }
+    return session;
+  };
+
+  async function storedReport(session, lang) {
+    const endpoint = getUsageReportEndpoint();
+    if (!endpoint) {
+      return { ok: false, reason: 'no-endpoint', message: 'no certs endpoint configured to read the stored report.' };
+    }
+    const res = await requestUsageReport({ accessToken: session.accessToken }, { endpoint });
+    if (!res.ok) {
+      return { ok: false, reason: res.reason || 'read-failed', message: `could not read the stored report (${res.reason || 'unknown'}).` };
+    }
+    if (!res.report) {
+      return { ok: true, hasReport: false, message: 'no stored report for this talent yet — run ai_usage first (and share the report).' };
+    }
+    return { ok: true, hasReport: true, text: renderUsageReportText(res, { lang }) };
+  }
+
+  async function report(args = {}) {
+    const session = requireSession();
+    if (args.stored === true) {
+      return storedReport(session, args.lang || detectFlowLang());
+    }
+    const result = materializeProjectReport({ root: args.root || null, lang: args.lang || null });
+    if (!result.hasData) {
+      return { ok: false, reason: 'no-data', message: 'no report yet — run ai_usage (and optionally certify) for this repo first.' };
+    }
+    const ret = { ok: true, path: result.htmlPath, fileUrl: result.fileUrl };
+    const footprint = loadFootprint({ root: args.root || null });
+    if (footprint && footprint.report) {
+      const preview = footprint.report.aiWorkPreview;
+      const aiProfile = preview ? { status: 'ready', preview } : { status: 'unavailable', preview: null };
+      const text = renderFullReportText(footprint.report, footprint.maturity, aiProfile, { lang: args.lang || detectFlowLang() });
+      if (text) ret.text = text;
+    }
+    return ret;
+  }
+
+  async function share(args = {}) {
+    requireSession();
+    const result = generateShareCard({ root: args.root || null });
+    if (!result.ok) {
+      return { ok: false, reason: 'no-footprint', message: 'no report yet — run ai_usage for this repo first.' };
+    }
+    return { ok: true, path: result.htmlPath, fileUrl: result.fileUrl };
+  }
+
+  return [
+    {
+      name: 'report',
+      description: "Two modes. stored:true returns the talent's ENTIRE stored server report (inventory + activity + AI-fluency level + prompting/interaction level) as plain text, read from certs WITHOUT re-running any scan — says so cleanly when none is stored (this stored view does NOT include the Setup×Usage matrix or the vision/how-I-work narratives). Otherwise builds the local report for this repo from local state: it returns the full human-readable report in `text` (Markdown mirroring the CLI terminal — Setup level and rank rationale, tools, MCP servers, agents, activity, plus the Setup×Usage matrix and vision/how-I-work when available) AND the HTML file path (no browser). Render `text` verbatim to the talent; keep the fenced blocks fenced so the tables stay aligned. Requires an active session. Any internal ids/codes are handles for tools only — never show or mention them to the talent.",
+      inputSchema: REPORT_SCHEMA,
+      handler: report,
+    },
+    {
+      name: 'share',
+      description: "Generate the Shakers-branded LinkedIn share card for this repo and return its file path. Does not open a browser. Requires an active session.",
+      inputSchema: SHARE_SCHEMA,
+      handler: share,
+    },
+  ];
+}
+
+module.exports = { makeReportTools, REPORT_SCHEMA, SHARE_SCHEMA };