shakers-cli 0.0.0-stage → 0.14.1

package/src/skills-client.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const { postJsonWithTimeout } = require('./backend-request');
+
+// Talent-skills client (talents-ai-score, ADR-054/055 — `start`'s "Añadir skills" route, src/start-add-skills.js).
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+// `works.*` business codes (WorksExceptionFilter's `codeMap`) -> this client's own reason vocabulary.
+const WORKS_CODE_TO_REASON = {
+  'certification.dimension_on_cooldown': 'dimension-on-cooldown',
+  'interview.non_conversational_blocks_in_text': 'needs-web',
+  'works.hub_token_missing': 'no-hub-token',
+  'works.hub_session_expired': 'hub-session-expired',
+  'works.hub_upstream_error': 'hub-upstream-error',
+  'works.hub_unavailable': 'hub-unavailable',
+  'works.ai_consent_required': 'ai-consent-required',
+  'interview.already_started': 'interview-already-started',
+  'interview.onboarding_not_found': 'onboarding-not-found',
+  'assigned-clusters.already_assigned': 'already-assigned',
+  'assigned-clusters.cap_reached': 'role-cap-reached',
+  'assigned-clusters.invalid_cluster': 'invalid-cluster',
+  'assigned-clusters.not_assigned': 'not-assigned',
+};
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+// The certs session Bearer (standard `AuthGuard`, required on ALL THREE talent-skills routes — none of them is `@Public()`) plus, only when present, the Talent's own Hub token.
+function authHeaders({ accessToken, hubAccessToken } = {}) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  if (typeof hubAccessToken === 'string' && hubAccessToken) headers['X-Hub-Token'] = hubAccessToken;
+  return headers;
+}
+
+function reasonForError(status, raw) {
+  const body = parseJson(raw);
+  const code = body && typeof body.code === 'string' ? body.code : null;
+  return (code && WORKS_CODE_TO_REASON[code]) || `http-${status}`;
+}
+
+// `POST .../skills/resolve-addable`.
+async function requestResolveAddableSkills({ technologies, accessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+
+  const body = { technologies: Array.isArray(technologies) ? technologies.filter((t) => typeof t === 'string' && t) : [] };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, body, timeoutMs, 'POST', null, authHeaders({ accessToken }));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    return { ok: false, reason: reasonForError(res.status, res.raw) };
+  }
+
+  const json = parseJson(res.raw);
+  const data = json && typeof json === 'object' && Array.isArray(json.data) ? json.data : null;
+  if (!data) return { ok: false, reason: 'bad-response' };
+
+  const addable = data
+    .map((entry) => ({
+      skillId: entry && typeof entry.skillId === 'number' ? entry.skillId : null,
+      skillName: entry && typeof entry.skillName === 'string' ? entry.skillName : null,
+      technology: entry && typeof entry.technology === 'string' ? entry.technology : null,
+    }))
+    .filter((s) => s.skillId !== null);
+  return { ok: true, addable };
+}
+
+// `POST .../skills/declare`.
+async function requestDeclareSkill({ skillId, accessToken, hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, { skillId }, timeoutMs, 'POST', null, authHeaders({ accessToken, hubAccessToken }));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    if (res.status === 409) return { ok: false, reason: 'skill-exists' };
+    return { ok: false, reason: reasonForError(res.status, res.raw) };
+  }
+
+  const json = parseJson(res.raw);
+  if (!json || json.status !== 'OK' || !Array.isArray(json.data)) {
+    return { ok: false, reason: 'bad-response' };
+  }
+  return { ok: true };
+}
+
+module.exports = { requestResolveAddableSkills, requestDeclareSkill, reasonForError, WORKS_CODE_TO_REASON };

package/src/socials-client.js

@@ -0,0 +1,91 @@
+'use strict';
+
+// Social links client. VIEW = GET `works/me/social`; SET = PUT the same endpoint
+// (upsert of the WHOLE object — a fixed set of named URL fields, not per-link rows).
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+const NETWORKS = ['linkedin', 'github', 'website', 'twitter', 'instagram', 'facebook', 'dribbble', 'behance'];
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+function normalizeSocial(data) {
+  const it = data && typeof data === 'object' ? data : {};
+  const out = {};
+  for (const k of NETWORKS) out[k] = typeof it[k] === 'string' && it[k] ? it[k] : null;
+  return out;
+}
+
+async function requestSocials({ hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  // No social section yet is a normal empty state, not an error.
+  if (res.status === 404) return { ok: true, social: normalizeSocial({}) };
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+  const env = parseJson(res.raw);
+  const data = env && env.status === 'OK' ? env.data : env;
+  if (!data || typeof data !== 'object') return { ok: false, reason: 'bad-response' };
+  return { ok: true, social: normalizeSocial(data) };
+}
+
+// Upsert the WHOLE object: `social` carries every network (value or null).
+async function requestSetSocials({ hubAccessToken, social } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  if (!social || typeof social !== 'object') return { ok: false, reason: 'no-social' };
+  const body = {};
+  for (const k of NETWORKS) body[k] = typeof social[k] === 'string' && social[k] ? social[k] : null;
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, body, timeoutMs, 'PUT', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+  return { ok: true };
+}
+
+async function fetchSocials(deps = {}, { hubAccessToken, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const getEndpoint = deps.getMeSocialEndpoint || require('./config').getMeSocialEndpoint;
+  const request = deps.requestSocials || requestSocials;
+  const endpoint = getEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return request({ hubAccessToken }, { endpoint, timeoutMs });
+}
+
+async function saveSocials(deps = {}, { hubAccessToken, social, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const getEndpoint = deps.getMeSocialEndpoint || require('./config').getMeSocialEndpoint;
+  const request = deps.requestSetSocials || requestSetSocials;
+  const endpoint = getEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return request({ hubAccessToken, social }, { endpoint, timeoutMs });
+}
+
+module.exports = {
+  NETWORKS,
+  normalizeSocial,
+  requestSocials,
+  requestSetSocials,
+  fetchSocials,
+  saveSocials,
+};

package/src/socials-flow.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// `socials` flow: view the talent's social links, and `--set` (interactive,
+// confirmation) to add/update/clear one. The write upserts the WHOLE object, so
+// we merge the chosen field into the current object and PUT it.
+
+const { styleLabelPrefix } = require('./ansi');
+const { NETWORKS } = require('./socials-client');
+
+function makeSocialsDeps(overrides = {}) {
+  const client = require('./socials-client');
+  return {
+    fetchSocials: (opts) => client.fetchSocials({}, opts),
+    saveSocials: (opts) => client.saveSocials({}, opts),
+    promptSelect: (opts) => require('./prompt-select').promptSelect(opts),
+    ...overrides,
+  };
+}
+
+function setNetworks(social) {
+  return NETWORKS.filter((k) => social && social[k]);
+}
+
+function renderView(io, fp, social) {
+  io.section(fp.title);
+  const present = setNetworks(social);
+  if (!present.length) { io.notify(fp.none); io.success(fp.done); return; }
+  present.forEach((k) => io.notify(styleLabelPrefix(fp.line(fp.networkLabel(k), social[k]))));
+  io.success(fp.done);
+}
+
+async function runSet({ io, ask, session, catalog, opts, deps }) {
+  const fp = catalog.socials;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+  if (!opts.stdinIsTTY) { io.error(fp.setNeedsInteractive); return { ok: false, reason: 'non-interactive' }; }
+  const selOut = (s) => io.notify(s);
+
+  const cur = await io.withProgress(fp.loading, () => deps.fetchSocials({ hubAccessToken }));
+  if (!cur.ok) { io.error(fp.fetchFailed(cur.reason)); return { ok: false, reason: cur.reason }; }
+  const social = { ...cur.social };
+
+  io.section(fp.setTitle);
+  const present = setNetworks(social);
+  if (present.length) present.forEach((k) => io.notify(styleLabelPrefix(fp.line(fp.networkLabel(k), social[k]))));
+
+  const net = await deps.promptSelect({
+    ask, stdinIsTTY: opts.stdinIsTTY, out: selOut, header: fp.pickNetwork,
+    items: NETWORKS.map((k) => ({ label: fp.networkLabel(k), value: k })), labelFor: (x) => x.label, input: opts.input, output: opts.output,
+  });
+  if (!net) { io.notify(fp.setCancelled); return { ok: true, cancelled: true }; }
+  const key = net.value;
+
+  const raw = (await io.ask(fp.askUrl(fp.networkLabel(key)))).trim();
+  const value = raw === '' ? null : raw;
+  social[key] = value;
+
+  io.notify(value ? fp.setDiffSet(fp.networkLabel(key), value) : fp.setDiffClear(fp.networkLabel(key)));
+  const confirmed = await io.confirm(fp.setConfirm);
+  if (!confirmed) { io.notify(fp.setCancelled); return { ok: true, cancelled: true }; }
+
+  const res = await io.withProgress(fp.setSaving, () => deps.saveSocials({ hubAccessToken, social }));
+  if (!res.ok) { io.error(fp.setFailed(res.reason)); return { ok: false, reason: res.reason }; }
+  io.success(value ? fp.setDone(fp.networkLabel(key)) : fp.setCleared(fp.networkLabel(key)));
+  return { ok: true, set: { key, value } };
+}
+
+async function runSocials({ io, rawOut, ask, session, catalog, opts = {}, deps = makeSocialsDeps() }) {
+  const fp = catalog.socials;
+  if (opts.set) return runSet({ io, ask, session, catalog, opts, deps });
+
+  const hubAccessToken = session ? session.hubAccessToken : null;
+  const doFetch = () => deps.fetchSocials({ hubAccessToken });
+  const res = opts.json ? await doFetch() : await io.withProgress(fp.loading, doFetch);
+  if (!res.ok) { io.error(fp.fetchFailed(res.reason)); return { ok: false, reason: res.reason }; }
+  if (opts.json) {
+    (rawOut || ((s) => process.stdout.write(s)))(`${JSON.stringify({ ok: true, social: res.social }, null, 2)}\n`);
+    return { ok: true, social: res.social };
+  }
+  renderView(io, fp, res.social);
+  return { ok: true, social: res.social };
+}
+
+module.exports = { makeSocialsDeps, runSocials, setNetworks, renderView };

package/src/specificity-extract.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const { eachHumanText } = require('./transcript-turns');
+
+const MIN_INSTRUCTION_LEN = 12;
+
+const CONCRETE_RE =
+  /(`[^`]+`|\b[\w-]+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|css|scss|html|json|ya?ml|md|sql|sh|toml)\b|\/[\w./-]{2,}|"[^"]{2,}"|\d|\b(must|should|shouldn'?t|don'?t|do not|ensure|avoid|instead|because|so that|only|never|always|exactly|specifically|at least|at most|no more than|make sure|asegúrate|debe|deber[íi]as?|no (uses?|hagas|pongas)|en vez de|en lugar de|porque|exactamente|específicamente|solo|nunca|siempre)\b)/i;
+
+function makeSpecificityAccumulator() {
+  let instructionTurnCount = 0;
+  let specificInstructionCount = 0;
+  let totalInstructionLength = 0;
+  return {
+    add(text) {
+      const trimmed = typeof text === 'string' ? text.trim() : '';
+      if (trimmed.length < MIN_INSTRUCTION_LEN) return;
+      instructionTurnCount += 1;
+      totalInstructionLength += trimmed.length;
+      if (CONCRETE_RE.test(trimmed)) specificInstructionCount += 1;
+    },
+    result() {
+      if (instructionTurnCount === 0) return null;
+      return {
+        specificInstructionCount,
+        instructionTurnCount,
+        avgInstructionLength: Math.round(
+          totalInstructionLength / instructionTurnCount,
+        ),
+      };
+    },
+  };
+}
+
+function collectSpecificity(env = process.env, selectedCwds = null) {
+  const acc = makeSpecificityAccumulator();
+  for (const text of eachHumanText(env, { selectedCwds })) acc.add(text);
+  return acc.result();
+}
+
+module.exports = { collectSpecificity, makeSpecificityAccumulator };

package/src/start-add-agents.js

@@ -0,0 +1,306 @@
+'use strict';
+
+const {
+  getUsageDiscoveredInventoryEndpoint,
+  getAgentsListEndpoint,
+  getAgentsDeclareEndpoint,
+  getAgentsDraftFieldsEndpoint,
+  getPortfoliosListEndpoint,
+  getAgentPortfoliosEndpoint,
+} = require('./config');
+const {
+  requestListAgents, requestDeclareAgent, requestDraftAgentFields, requestRelateAgentPortfolios,
+} = require('./agents-client');
+const { requestListPortfolios } = require('./portfolio-client');
+const { requestDiscoveredInventory } = require('./inventory-client');
+const { ensureFreshSession } = require('./session-refresh');
+const { confirmDisclaimerAcceptance } = require('./certify-disclaimer');
+const { runInteractiveMultiSelect } = require('./interactive-select');
+const { loadAuthSession, sessionStatus } = require('./auth-session-store');
+const { withSpinner } = require('./terminal-progress');
+const { reasonCopy, pickPortfolios } = require('./start-add-skills');
+// `askWithDefault`: pre-filled line prompt (empty enter accepts the default),
+// reused from the portfolio route.
+const { askWithDefault } = require('./start-add-portfolio');
+const { styleQuestion, styleSuccess } = require('./ansi');
+
+// `start`'s "Add agent to profile" route (talents-ai-score Phase 2), mirror of src/start-add-portfolio.js: the IA pre-drafts, the Talent edits.
+
+const MAX_DEFINITION_CHARS = 4000;
+
+async function askFreeText(ask, promptText) {
+  return String(await ask(styleQuestion(promptText))).trim();
+}
+
+async function askNumberedChoice(ask, promptText, count) {
+  const raw = (await ask(styleQuestion(promptText))).trim();
+  if (!raw) return null;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isInteger(n) || n < 1 || n > count) return null;
+  return n - 1;
+}
+
+// Step 1 — pick ONE detected agent (single-select, numbered-prompt fallback).
+// Returns the agent, or null on cancel.
+async function chooseAgent({ ask, stdinIsTTY, agents, c, input, output }) {
+  const labelFor = (a) => a.pickerLabel || a.name;
+  if (stdinIsTTY && typeof ask.suspend === 'function') {
+    ask.suspend();
+    const picked = await runInteractiveMultiSelect({
+      items: agents,
+      labelFor,
+      header: c.agentPickHeading,
+      hint: c.agentPickHint,
+      single: true,
+      ...(input ? { input } : {}),
+      ...(output ? { output } : {}),
+    });
+    ask.resume();
+    // Drain the picker-residual-Enter (the suspend/resume mode switch can leave a
+    // stray Enter that pre-answers the next prompt) — same fix as bin/start.js/certify.js.
+    if (typeof ask.drain === 'function') ask.drain();
+    return picked && picked.length ? picked[0] : null;
+  }
+
+  process.stdout.write(`\n  ${styleQuestion(c.agentPickHeading)}\n`);
+  agents.forEach((a, i) => process.stdout.write(`    ${i + 1}) ${labelFor(a)}\n`));
+  const idx = await askNumberedChoice(ask, `  ${c.agentPickPrompt(agents.length)}`, agents.length);
+  return idx === null ? null : agents[idx];
+}
+
+// Step 4 — the two AI-drafted fields, consent-gated (ADR-052) before any egress.
+async function resolveAgentFields({ ask, catalog, c, stdinIsTTY, agent, accessToken, preAccepted = false }) {
+  const freeText = async () => ({
+    whatItDoes: await askFreeText(ask, c.agentWhatItDoesFreeTextPrompt),
+    humanDecides: await askFreeText(ask, c.agentHumanDecidesFreeTextPrompt),
+  });
+
+  const draftEndpoint = getAgentsDraftFieldsEndpoint();
+  if (!draftEndpoint) return freeText();
+
+  const acceptance = await confirmDisclaimerAcceptance({
+    ask, catalog, stdinIsTTY, preAccepted, text: c.agentFieldsConsentDisclaimer,
+  });
+  if (!acceptance.accepted) return freeText();
+
+  const definition = typeof agent.definition === 'string' && agent.definition
+    ? agent.definition.slice(0, MAX_DEFINITION_CHARS)
+    : null;
+  const draft = await withSpinner(c.agentDraftingLabel, () => requestDraftAgentFields(
+    { name: agent.name, tools: agent.tools, model: agent.model, parent: agent.parent, definition, accessToken },
+    { endpoint: draftEndpoint },
+  ));
+  if (!draft.ok) return freeText();
+
+  process.stdout.write(`\n  ${styleQuestion(c.agentWhatItDoesDraftLabel)}\n  ${draft.whatItDoes}\n`);
+  const whatItDoes = await askWithDefault(ask, c.agentWhatItDoesEditPrompt, draft.whatItDoes);
+  process.stdout.write(`\n  ${styleQuestion(c.agentHumanDecidesDraftLabel)}\n  ${draft.humanDecides}\n`);
+  const humanDecides = await askWithDefault(ask, c.agentHumanDecidesEditPrompt, draft.humanDecides);
+  return { whatItDoes, humanDecides };
+}
+
+// Asks to re-login and returns the fresh session, or null. Reuses the portfolio
+// route's generic relogin copys.
+async function offerRelogin({ ask, c, runLogin }) {
+  if (typeof runLogin !== 'function') return null;
+  const raw = String(await ask(`\n  ${styleQuestion(c.portfolioOfferRelogin)} `)).trim();
+  if (!/^(y|yes|s|si|sí)$/i.test(raw)) {
+    process.stdout.write(`\n  ${c.portfolioRelaunchDeclined}\n\n`);
+    return null;
+  }
+  await runLogin([], { ask });
+  const fresh = loadAuthSession();
+  if (sessionStatus(fresh) !== 'active' || !fresh.hubAccessToken) {
+    process.stdout.write(`\n  ${c.portfolioReloginFailed}\n\n`);
+    return null;
+  }
+  return fresh;
+}
+
+async function offerRelateAgentToPortfolios({
+  ask, stdinIsTTY, agentId, agentName, session, c, input, output,
+}) {
+  if (!agentId) return;
+  const listEndpoint = getPortfoliosListEndpoint();
+  const relateEndpoint = getAgentPortfoliosEndpoint(agentId);
+  if (!listEndpoint || !relateEndpoint) return;
+
+  const listed = await requestListPortfolios(
+    { accessToken: session.accessToken, hubAccessToken: session.hubAccessToken },
+    { endpoint: listEndpoint },
+  );
+  if (!listed.ok || listed.portfolios.length === 0) {
+    process.stdout.write(`\n  ${c.agentRelateNoPortfolios}\n`);
+    return;
+  }
+
+  const wantsRelate = /^(y|yes|s|si|sí)$/i.test(String(await ask(`\n  ${styleQuestion(c.agentRelateAsk(agentName))} `)).trim());
+  if (!wantsRelate) {
+    process.stdout.write(`  ${c.agentRelateSkipped(agentName)}\n`);
+    return;
+  }
+
+  const heading = c.agentRelateSelectHeading(agentName);
+  const chosen = await pickPortfolios({ ask, stdinIsTTY, portfolios: listed.portfolios, heading, c, input, output });
+  if (!chosen || chosen.length === 0) {
+    process.stdout.write(`  ${c.agentRelateSkipped(agentName)}\n`);
+    return;
+  }
+
+  const items = chosen.map((portfolio) => ({ portfolioId: portfolio.id }));
+
+  const r = await requestRelateAgentPortfolios(
+    { agentId, items, hubAccessToken: session.hubAccessToken },
+    { endpoint: relateEndpoint },
+  );
+  if (r.ok) {
+    for (const portfolio of chosen) {
+      process.stdout.write(`  ${styleSuccess(c.agentRelated(agentName, portfolio.name))}\n`);
+    }
+  } else {
+    process.stdout.write(`  ${c.agentRelateFailed(agentName, reasonCopy(r.reason, c))}\n`);
+  }
+}
+
+async function runAddAgents({
+  ask, catalog, root, session, stdinIsTTY, input, output, preAccepted = false, deps = {},
+} = {}) {
+  const c = catalog.start;
+  const runLogin = deps.runLogin;
+  const refreshSession = deps.refreshSession || (() => ensureFreshSession(process.env));
+
+  const inventoryEndpoint = getUsageDiscoveredInventoryEndpoint();
+  const listEndpoint = getAgentsListEndpoint();
+  const declareEndpoint = getAgentsDeclareEndpoint();
+  if (!inventoryEndpoint || !listEndpoint || !declareEndpoint) {
+    process.stderr.write(`\n  ${c.agentErrorNoEndpoint}\n\n`);
+    return;
+  }
+
+  let hubAccessToken = session.hubAccessToken;
+  if (!hubAccessToken) {
+    process.stderr.write(`\n  ${c.agentNoHubToken}\n\n`);
+    return;
+  }
+
+  let inventory = await requestDiscoveredInventory(
+    { accessToken: session.accessToken },
+    { endpoint: inventoryEndpoint },
+  );
+  // An expired hub JWT (the same 401 the usage poll hits) must not break add-agent:
+  // refresh the session once and retry the read (and adopt the fresh tokens downstream).
+  if (inventory.reason === 'http-401') {
+    let fresh = null;
+    try { fresh = await refreshSession(); } catch { fresh = null; }
+    if (fresh && (fresh.accessToken || fresh.hubAccessToken)) {
+      session = { ...session, accessToken: fresh.accessToken || session.accessToken, hubAccessToken: fresh.hubAccessToken || session.hubAccessToken };
+      hubAccessToken = session.hubAccessToken;
+      inventory = await requestDiscoveredInventory(
+        { accessToken: session.accessToken },
+        { endpoint: inventoryEndpoint },
+      );
+    }
+  }
+  if (!inventory.ok) {
+    process.stderr.write(`\n  ${c.agentInventoryError(reasonCopy(inventory.reason, c))}\n\n`);
+    return;
+  }
+  const agents = inventory.agents;
+  if (agents.length === 0) {
+    process.stdout.write(`\n  ${c.agentNoAgentsDetected}\n\n`);
+    return;
+  }
+  for (const a of agents) a.pickerLabel = a.role ? `${a.name} — ${a.role}` : a.name;
+
+  // DEDUP by name (before asking anything). A failed list is reported as "could
+  // not verify" (never "no duplicates") and the flow continues.
+  const listed = await withSpinner(
+    c.agentDedupCheckingLabel,
+    () => requestListAgents({ accessToken: session.accessToken, hubAccessToken }, { endpoint: listEndpoint }),
+  );
+  const existingNames = listed.ok ? listed.agents.map((a) => a.name.toLowerCase()) : null;
+  if (!listed.ok) process.stdout.write(`\n  ${c.agentDedupCheckFailed(reasonCopy(listed.reason, c))}\n`);
+
+  process.stdout.write(`\n  ${c.agentIntro}\n`);
+
+  // (1) Pick a detected agent.
+  const agent = await chooseAgent({ ask, stdinIsTTY, agents, c, input, output });
+  if (!agent) {
+    process.stdout.write(`\n  ${c.agentCancelled}\n\n`);
+    return;
+  }
+
+  // (3) Name ← detected, editable. (2) dedup applies to the FINAL name.
+  const name = await askWithDefault(ask, c.agentNamePrompt(agent.name), agent.name);
+  if (existingNames && existingNames.includes(name.toLowerCase())) {
+    const existing = listed.ok ? listed.agents.find((a) => a.name.toLowerCase() === name.toLowerCase()) : null;
+    const existingId = existing && existing.id ? existing.id : null;
+    if (existingId) {
+      process.stdout.write(`\n  ${c.agentAlreadyAdded(name)}\n`);
+      await offerRelateAgentToPortfolios({
+        ask, stdinIsTTY, agentId: existingId, agentName: name, session, c, input, output,
+      });
+      process.stdout.write('\n');
+    } else {
+      process.stdout.write(`\n  ${c.agentDuplicateName(name)}\n\n`);
+    }
+    return;
+  }
+
+  // (4) whatItDoes + humanDecides — AI draft (consent-gated) or free-text.
+  const { whatItDoes, humanDecides } = await resolveAgentFields({
+    ask, catalog, c, stdinIsTTY, agent, accessToken: session.accessToken, preAccepted,
+  });
+
+  const matchedRole = agent.role || null;
+  if (matchedRole) process.stdout.write(`\n  ${c.agentCatalogMatched(matchedRole)}\n`);
+
+  const payload = { name, whatItDoes: whatItDoes || agent.whatItDoes, humanDecides };
+
+  // Declare.
+  const declared = await withSpinner(
+    c.agentDeclaring,
+    () => requestDeclareAgent({ ...payload, accessToken: session.accessToken, hubAccessToken }, { endpoint: declareEndpoint }),
+  );
+  if (declared.ok) {
+    process.stdout.write(`\n  ${styleSuccess(c.agentDeclaredSuccess(name))}\n`);
+    await offerRelateAgentToPortfolios({
+      ask, stdinIsTTY, agentId: declared.agentId, agentName: name, session, c, input, output,
+    });
+    process.stdout.write('\n');
+    return;
+  }
+  if (declared.reason !== 'hub-session-expired') {
+    process.stdout.write(`\n  ${c.agentDeclareFailed(reasonCopy(declared.reason, c))}\n\n`);
+    return;
+  }
+
+  // Hub session expired mid-flight — offer one relogin + retry.
+  process.stdout.write(`\n  ${c.agentHubSessionExpired}\n`);
+  const relogged = await offerRelogin({ ask, c, runLogin });
+  if (!relogged) return;
+  process.stdout.write(`  ${c.portfolioRelaunchAfterRelogin}\n`);
+  const retried = await withSpinner(
+    c.agentDeclaring,
+    () => requestDeclareAgent(
+      { ...payload, accessToken: relogged.accessToken, hubAccessToken: relogged.hubAccessToken },
+      { endpoint: declareEndpoint },
+    ),
+  );
+  if (retried.ok) {
+    process.stdout.write(`\n  ${styleSuccess(c.agentDeclaredSuccess(name))}\n`);
+    await offerRelateAgentToPortfolios({
+      ask, stdinIsTTY, agentId: retried.agentId, agentName: name, session: relogged, c, input, output,
+    });
+    process.stdout.write('\n');
+  } else {
+    process.stdout.write(`\n  ${c.agentDeclareFailed(reasonCopy(retried.reason, c))}\n\n`);
+  }
+}
+
+module.exports = {
+  runAddAgents,
+  chooseAgent,
+  resolveAgentFields,
+  offerRelateAgentToPortfolios,
+};