shakers-cli-beta 0.8.0-beta.0

package/src/agents-client.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError, WORKS_CODE_TO_REASON } = require('./skills-client');
+
+// Talent-agent client for `start`'s "Add agent" route (talents-ai-score Phase 2).
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+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;
+}
+
+// DIRECT-to-Hub headers (the relate route is not a certs relay): the Talent's own hub token IS the Authorization, same shape as portfolio-client's own `hubHeaders`.
+function hubHeaders({ hubAccessToken } = {}) {
+  const headers = {};
+  if (typeof hubAccessToken === 'string' && hubAccessToken) headers.Authorization = `Bearer ${hubAccessToken}`;
+  return headers;
+}
+
+// `GET .../agents` -> { ok, agents:[{name}] } | { ok:false, reason }. Used for
+// client-side dedup; a failed list is a named reason, never a silent skip.
+async function requestListAgents({ 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, null, timeoutMs, 'GET', null, authHeaders({ accessToken, 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) };
+  }
+
+  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 agents = data
+    .map((entry) => ({
+      name: entry && typeof entry.name === 'string' ? entry.name : null,
+      id: entry && (typeof entry.id === 'string' || typeof entry.id === 'number') ? String(entry.id) : null,
+    }))
+    .filter((a) => a.name !== null);
+  return { ok: true, agents };
+}
+
+// `POST .../agents/declare`. `no-hub-token` fires locally before any request.
+// Optional fields are OMITTED (never null/empty).
+async function requestDeclareAgent(
+  { name, catalogId, whatItDoes, humanDecides, accessToken, hubAccessToken } = {},
+  { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+
+  const body = { name };
+  // Hub's `catalogId` is an Int `num_id` (`@IsInt()` server-side).
+  if (typeof catalogId === 'number' && Number.isInteger(catalogId)) body.catalogId = catalogId;
+  if (typeof whatItDoes === 'string' && whatItDoes) body.whatItDoes = whatItDoes;
+  if (typeof humanDecides === 'string' && humanDecides) body.humanDecides = humanDecides;
+
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, body, 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: 'agent-exists' };
+    return { ok: false, reason: reasonForError(res.status, res.raw) };
+  }
+
+  const json = parseJson(res.raw);
+  if (!json || json.status !== 'OK') return { ok: false, reason: 'bad-response' };
+  // Thread the created agent's id back (relayed from Hub's declare response) so the relate step can PATCH `.../agents/:id/portfolios` (ADR-041).
+  const data = json.data && typeof json.data === 'object' ? json.data : null;
+  const rawId = data ? data.id : null;
+  const agentId = typeof rawId === 'string' || typeof rawId === 'number' ? String(rawId) : null;
+  return { ok: true, agentId };
+}
+
+// `PATCH {hub}/works/me/agents/:id/portfolios` — DIRECT to Hub (ADR-041), replace-set.
+async function requestRelateAgentPortfolios(
+  { agentId, items, hubAccessToken } = {},
+  { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  if (!agentId) return { ok: false, reason: 'no-agent' };
+
+  const body = {
+    items: (Array.isArray(items) ? items : []).map((it) => ({ portfolioId: it && it.portfolioId })),
+  };
+
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, body, timeoutMs, 'PATCH', null, hubHeaders({ 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) };
+  }
+  const json = parseJson(res.raw);
+  if (!json || (json.success !== true && json.status !== 'OK')) return { ok: false, reason: 'bad-response' };
+  return { ok: true };
+}
+
+// `POST .../agents/draft-fields` -> { ok, whatItDoes, humanDecides } | { ok:false, reason }.
+// No X-Hub-Token. The CALLER gates consent (ADR-052), so `consent:true` is always sent.
+async function requestDraftAgentFields(
+  { name, tools, model, parent, definition, accessToken } = {},
+  { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+
+  const body = { consent: true, name };
+  if (Array.isArray(tools) && tools.length > 0) body.tools = tools.filter((t) => typeof t === 'string' && t);
+  if (typeof model === 'string' && model) body.model = model;
+  if (typeof parent === 'string' && parent) body.parent = parent;
+  if (typeof definition === 'string' && definition) body.definition = definition;
+
+  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 && json.status === 'OK' && json.data && typeof json.data === 'object' ? json.data : null;
+  const whatItDoes = data && typeof data.whatItDoes === 'string' ? data.whatItDoes : null;
+  const humanDecides = data && typeof data.humanDecides === 'string' ? data.humanDecides : null;
+  if (!whatItDoes || !humanDecides) return { ok: false, reason: 'bad-response' };
+  return { ok: true, whatItDoes, humanDecides };
+}
+
+module.exports = {
+  requestListAgents,
+  requestDeclareAgent,
+  requestRelateAgentPortfolios,
+  requestDraftAgentFields,
+  WORKS_CODE_TO_REASON,
+};

package/src/ai-fluency-cell.js

@@ -0,0 +1,72 @@
+'use strict';
+
+// Setup(tier) x Usage(interaction) -> 3x3 cell; mapping mirrors certs/hub (keep in
+// sync). Usage level is judged server-side; this only maps already-judged bands.
+
+const SETUP_LEVELS = ['ASSISTED', 'EXTENDED', 'ORCHESTRATED'];
+const USAGE_LEVELS = ['REACTIVE', 'DELIBERATE', 'RIGOROUS'];
+
+const SETUP_CODE = { ASSISTED: 'S1', EXTENDED: 'S2', ORCHESTRATED: 'S3' };
+
+// hub CELL_NAMES, transposed to [setup][usage].
+const CELL_NAMES = {
+  ASSISTED: { REACTIVE: 'Explorer', DELIBERATE: 'Practitioner', RIGOROUS: 'Craftsman' },
+  EXTENDED: { REACTIVE: 'Tooled-up', DELIBERATE: 'Builder', RIGOROUS: 'Architect' },
+  ORCHESTRATED: { REACTIVE: 'Automated', DELIBERATE: 'Scaler', RIGOROUS: 'AI Native' },
+};
+
+function deriveSetupLevelFromTier(tier) {
+  if (tier === null || tier === undefined || tier <= 0) return null;
+  if (tier <= 2) return 'ASSISTED';
+  if (tier <= 4) return 'EXTENDED';
+  return 'ORCHESTRATED';
+}
+
+function deriveUsageLevelFromInteraction(interactionLevel) {
+  switch (interactionLevel) {
+    case 'reactive':
+      return 'REACTIVE';
+    case 'directive':
+      return 'DELIBERATE';
+    case 'orchestrative':
+      return 'RIGOROUS';
+    default:
+      return null;
+  }
+}
+
+function deriveAiFluencyCell(setupLevel, usageLevel) {
+  if (!setupLevel || !usageLevel) return null;
+  const row = CELL_NAMES[setupLevel];
+  return (row && row[usageLevel]) || null;
+}
+
+function isAiNative(setupLevel, usageLevel) {
+  return setupLevel === 'ORCHESTRATED' && usageLevel === 'RIGOROUS';
+}
+
+// tier (0-7) + interactionLevel ('reactive'|'directive'|'orchestrative') -> matrix.
+// Null bands when an input is missing (setup-only / usage-pending).
+function composeAiFluencyMatrix({ tier = null, interactionLevel = null } = {}) {
+  const setupLevel = deriveSetupLevelFromTier(tier);
+  const usageLevel = deriveUsageLevelFromInteraction(interactionLevel);
+  return {
+    setupLevel,
+    setupCode: setupLevel ? SETUP_CODE[setupLevel] : null,
+    usageLevel,
+    cell: deriveAiFluencyCell(setupLevel, usageLevel),
+    isAiNative: isAiNative(setupLevel, usageLevel),
+  };
+}
+
+module.exports = {
+  SETUP_LEVELS,
+  USAGE_LEVELS,
+  SETUP_CODE,
+  CELL_NAMES,
+  deriveSetupLevelFromTier,
+  deriveUsageLevelFromInteraction,
+  deriveAiFluencyCell,
+  isAiNative,
+  composeAiFluencyMatrix,
+};

package/src/ai-profile-client.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// GET hub `works/me/ai-profile` — the same read model the "My work with AI" front
+// paints: { setup, usage, cell, isAiNative, traction, vision, howIWork }.
+
+const { postJsonWithTimeout } = require('./backend-request');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function authHeaders(token) {
+  const headers = {};
+  if (typeof token === 'string' && token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+
+async function requestAiProfile({ accessToken, hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  const token = hubAccessToken || accessToken;
+
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, authHeaders(token));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+
+  // 404 = no profile row yet (projection hasn't landed) — a retriable "not ready".
+  if (res.status === 404) return { ok: false, reason: 'not-found' };
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: `http-${res.status}` };
+
+  const json = parseJson(res.raw);
+  const data = json && typeof json === 'object' ? json.data : null;
+  if (!data || typeof data !== 'object') return { ok: false, reason: 'bad-response' };
+  return { ok: true, profile: data };
+}
+
+module.exports = { requestAiProfile };

package/src/ai-profile-preview.js

@@ -0,0 +1,154 @@
+'use strict';
+
+// Polls the hub ai-profile (downstream of the report ingest, lands ~3-8s later) and normalizes it for the report/MCP.
+
+const { SETUP_CODE } = require('./ai-fluency-cell');
+
+const DEFAULT_TIMEOUT_MS = 90000;
+const POLL_INTERVAL_MS = 4000;
+const PROFILE_POLL_WINDOW_MS = DEFAULT_TIMEOUT_MS;
+const PROFILE_POLL_INTERVAL_MS = POLL_INTERVAL_MS;
+const MAX_TOKEN_REFRESHES = 2;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const strOrNull = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+const numOrNull = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+
+// Tolerant normalization of the hub TalentAiProfileDto into the render shape.
+function normalizeProfile(profile) {
+  const p = profile && typeof profile === 'object' ? profile : {};
+  const setup = p.setup && typeof p.setup === 'object' ? p.setup : {};
+  const usage = p.usage && typeof p.usage === 'object' ? p.usage : {};
+  const setupLevel = strOrNull(setup.level);
+  const usageLevel = strOrNull(usage.level);
+  const t = p.traction && typeof p.traction === 'object' ? p.traction : null;
+  const tools = t && Array.isArray(t.tools)
+    ? t.tools.map((x) => ({
+      id: strOrNull(x && (x.id ?? x.name)),
+      name: strOrNull(x && (x.name ?? x.id)),
+      detected: x ? x.detected === true : false,
+    })).filter((x) => x.id || x.name)
+    : null;
+  const vision = p.vision && typeof p.vision === 'object' ? p.vision : null;
+  const howIWork = p.howIWork && typeof p.howIWork === 'object' ? p.howIWork : null;
+
+  return {
+    matrix: {
+      setupLevel,
+      setupCode: setupLevel ? (SETUP_CODE[setupLevel] || null) : null,
+      usageLevel,
+      cell: strOrNull(p.cell),
+      isAiNative: p.isAiNative === true,
+    },
+    setup: { tier: strOrNull(setup.tier), level: setupLevel, explanation: strOrNull(setup.explanation) },
+    usage: { level: usageLevel, explanation: strOrNull(usage.explanation) },
+    traction: t
+      ? {
+        sessions90d: numOrNull(t.sessions90d),
+        activeDaysPerWeek: numOrNull(t.activeDaysPerWeek),
+        agentsDetected: numOrNull(t.agentsDetected),
+        agentsOnProfile: numOrNull(t.agentsOnProfile),
+        tools,
+      }
+      : null,
+    vision: vision ? strOrNull(vision.text) : null,
+    howIWork: howIWork ? strOrNull(howIWork.body) : null,
+  };
+}
+
+// The matrix band is populated once the CLI footprint tier has been projected.
+function matrixPresent(preview) {
+  const m = preview && preview.matrix;
+  return !!(m && (m.setupLevel || m.usageLevel || m.cell));
+}
+
+// Anything renderable: the matrix band OR the vision (E) OR how-I-work (F). The
+// three land on independent projections, so the render must not gate on the matrix.
+function hasRenderableProfile(preview) {
+  return !!preview && (matrixPresent(preview) || !!preview.vision || !!preview.howIWork);
+}
+
+// The full profile: matrix band AND both narratives. Once complete, stop polling.
+function isProfileComplete(preview) {
+  return matrixPresent(preview) && !!preview.vision && !!preview.howIWork;
+}
+
+// How many of the three parts (matrix, E, F) landed — to keep the most complete partial.
+function profileCompleteness(preview) {
+  if (!preview) return -1;
+  return (matrixPresent(preview) ? 1 : 0) + (preview.vision ? 1 : 0) + (preview.howIWork ? 1 : 0);
+}
+
+// Back-compat alias (matrix-band meaning preserved for external callers).
+const isProfileReady = matrixPresent;
+
+// deps (injectable for tests): requestAiProfile, now, wait, pollIntervalMs.
+async function resolveAiProfilePreview(args = {}, deps = {}) {
+  const { session = null, endpoint = null, timeoutMs = DEFAULT_TIMEOUT_MS } = args;
+  const {
+    requestAiProfile = require('./ai-profile-client').requestAiProfile,
+    refreshToken = null,
+    now = () => Date.now(),
+    wait = sleep,
+    pollIntervalMs = POLL_INTERVAL_MS,
+  } = deps;
+
+  let accessToken = session && typeof session.accessToken === 'string' ? session.accessToken : null;
+  let hubAccessToken = session && typeof session.hubAccessToken === 'string' ? session.hubAccessToken : null;
+  if ((!accessToken && !hubAccessToken) || !endpoint) return { status: 'unavailable', preview: null };
+
+  const deadline = now() + Math.max(0, timeoutMs);
+  // The matrix band, the vision (E) and howIWork (F) land on INDEPENDENT projections and
+  // in any order (the matrix can even lag to the hourly reconcile cron). Keep the most
+  // complete partial seen and render it — never gate the whole preview on the matrix band.
+  let best = null;
+  let refreshes = 0;
+
+  while (true) {
+    const remaining = deadline - now();
+    if (remaining <= 0) break;
+
+    let res;
+    try {
+      res = await requestAiProfile({ accessToken, hubAccessToken }, { endpoint, timeoutMs: remaining });
+    } catch {
+      res = { ok: false, reason: 'network-error' };
+    }
+
+    if (res && res.ok) {
+      const preview = normalizeProfile(res.profile);
+      if (isProfileComplete(preview)) return { status: 'ready', preview };
+      if (profileCompleteness(preview) > profileCompleteness(best)) best = preview;
+    } else if (res && res.reason === 'http-401' && typeof refreshToken === 'function' && refreshes < MAX_TOKEN_REFRESHES) {
+      refreshes += 1;
+      let fresh = null;
+      try { fresh = await refreshToken(); } catch { fresh = null; }
+      if (fresh && (fresh.accessToken || fresh.hubAccessToken)) {
+        accessToken = typeof fresh.accessToken === 'string' ? fresh.accessToken : accessToken;
+        hubAccessToken = typeof fresh.hubAccessToken === 'string' ? fresh.hubAccessToken : hubAccessToken;
+        continue;
+      }
+    }
+
+    if (deadline - now() <= pollIntervalMs) break;
+    await wait(pollIntervalMs);
+  }
+
+  // Anything renderable (matrix OR E OR F) is surfaced as `ready`; the renderers degrade
+  // per-field. Only a genuinely empty profile stays `pending`.
+  if (hasRenderableProfile(best)) return { status: 'ready', preview: best };
+  return { status: 'pending', preview: null };
+}
+
+module.exports = {
+  resolveAiProfilePreview,
+  normalizeProfile,
+  isProfileReady,
+  matrixPresent,
+  hasRenderableProfile,
+  isProfileComplete,
+  profileCompleteness,
+  DEFAULT_TIMEOUT_MS,
+  PROFILE_POLL_WINDOW_MS,
+  PROFILE_POLL_INTERVAL_MS,
+};

package/src/ai.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// The single named surface for every model-backed (LLM) call this CLI makes (talents-ai-score, arch-cleanup #4).
+
+const agentSynthesis = require('./agent-synthesis');
+const agentEvaluation = require('./agent-evaluation');
+const roadmapPersonalization = require('./roadmap-personalization');
+const onboardingClient = require('./onboarding-client');
+const config = require('./config');
+
+// The model calls, one entry each, paired with the request-builder, endpoint-getter and promptVersion pointer that define them. The skill-code certify/interview trio was removed when `certify` became a dimension LiveKit interview (its turns run over the onboarding HTTP/LiveKit surface, not a dedicated model call here).
+const AI_CALLS = Object.freeze({
+  agentSynthesis: {
+    call: agentSynthesis.requestAgentSynthesis,
+    build: agentSynthesis.buildSynthesisRequest,
+    endpoint: config.getSynthesisEndpoint,
+    promptVersion: null,
+  },
+  agentEvaluation: {
+    call: agentEvaluation.requestAgentEvaluation,
+    build: agentEvaluation.buildAgentEvaluationRequest,
+    endpoint: config.getAgentEvaluationEndpoint,
+    promptVersion: agentEvaluation.PROMPT_VERSION,
+  },
+  roadmapPersonalization: {
+    call: roadmapPersonalization.requestRoadmapPersonalization,
+    build: roadmapPersonalization.buildRoadmapPersonalizationRequest,
+    endpoint: config.getRoadmapEndpoint,
+    promptVersion: null,
+  },
+  onboardingOpen: {
+    call: onboardingClient.requestStartTextSession,
+    build: null,
+    endpoint: config.getOnboardingInterviewsEndpoint,
+    promptVersion: null,
+  },
+  onboardingTurn: {
+    call: onboardingClient.requestOnboardingTurn,
+    build: null,
+    endpoint: config.getOnboardingInterviewsEndpoint,
+    promptVersion: null,
+  },
+  onboardingComplete: {
+    call: onboardingClient.requestCompleteTextSession,
+    build: null,
+    endpoint: config.getOnboardingInterviewsEndpoint,
+    promptVersion: null,
+  },
+});
+
+module.exports = {
+  AI_CALLS,
+
+  requestAgentSynthesis: agentSynthesis.requestAgentSynthesis,
+  buildSynthesisRequest: agentSynthesis.buildSynthesisRequest,
+
+  requestAgentEvaluation: agentEvaluation.requestAgentEvaluation,
+  buildAgentEvaluationRequest: agentEvaluation.buildAgentEvaluationRequest,
+
+  requestRoadmapPersonalization: roadmapPersonalization.requestRoadmapPersonalization,
+  buildRoadmapPersonalizationRequest: roadmapPersonalization.buildRoadmapPersonalizationRequest,
+
+  requestStartTextSession: onboardingClient.requestStartTextSession,
+  requestOnboardingTurn: onboardingClient.requestOnboardingTurn,
+  requestCompleteTextSession: onboardingClient.requestCompleteTextSession,
+};

package/src/alma-client.js

@@ -0,0 +1,123 @@
+'use strict';
+
+// Alma client: POST `/alma/chat` (turn) and `/alma/decision` (approve/deny a
+// pending action) with the talent's hub Bearer (Alma verifies it against the hub
+// JWKS, ES256). Response is an NDJSON stream — one JSON event per line:
+// {type:'turn_started'|'text_delta'|'confirmation_required'|'link'|...}. Parsed
+// incrementally so the CLI can print tokens live. Zero-dep (http/https only).
+
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 120000;
+
+// Streams one NDJSON turn to `endpoint` with `body`. `onEvent(evt)` fires per line;
+// resolves with the aggregated assistant text (the concatenated text_delta chunks).
+function streamNdjson(endpoint, body, { hubAccessToken, onEvent, timeoutMs = DEFAULT_TIMEOUT_MS, requestImpl } = {}) {
+  return new Promise((resolve) => {
+    if (!endpoint) return resolve({ ok: false, reason: 'no-endpoint' });
+    if (!hubAccessToken) return resolve({ ok: false, reason: 'no-hub-token' });
+
+    let url;
+    try {
+      url = new URL(endpoint);
+    } catch {
+      return resolve({ ok: false, reason: 'bad-endpoint' });
+    }
+    const lib = requestImpl || (url.protocol === 'https:' ? https : http);
+    const payload = JSON.stringify(body);
+    const deltas = [];
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+
+    const req = lib.request(
+      {
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: `${url.pathname}${url.search}`,
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(payload),
+          accept: 'application/x-ndjson',
+          authorization: `Bearer ${hubAccessToken}`,
+        },
+        timeout: timeoutMs,
+      },
+      (res) => {
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          let err = '';
+          res.on('data', (c) => { err += c; });
+          res.on('end', () => done({ ok: false, reason: reasonForError(res.statusCode, err) }));
+          return;
+        }
+        res.setEncoding('utf8');
+        let buffer = '';
+        const handleLine = (line) => {
+          const s = line.trim();
+          if (!s) return;
+          let evt;
+          try { evt = JSON.parse(s); } catch { return; }
+          if (evt && evt.type === 'text_delta' && typeof evt.text === 'string') deltas.push(evt.text);
+          if (typeof onEvent === 'function') onEvent(evt);
+        };
+        res.on('data', (chunk) => {
+          buffer += chunk;
+          let idx;
+          while ((idx = buffer.indexOf('\n')) >= 0) {
+            handleLine(buffer.slice(0, idx));
+            buffer = buffer.slice(idx + 1);
+          }
+        });
+        // A stream error AFTER the headers (mid-stream reset) has no other
+        // handler — without this the promise would never settle (hang).
+        res.on('error', (e) => done({ ok: false, reason: (e && e.code) || 'stream-error' }));
+        res.on('end', () => { handleLine(buffer); done({ ok: true, text: deltas.join('') }); });
+      },
+    );
+    req.on('error', (e) => done({ ok: false, reason: (e && e.code) || 'network-error' }));
+    req.on('timeout', () => { req.destroy(); done({ ok: false, reason: 'timeout' }); });
+    req.write(payload);
+    req.end();
+  });
+}
+
+function streamAlmaChat({ hubAccessToken, message } = {}, opts = {}) {
+  if (typeof message !== 'string' || !message.trim()) return Promise.resolve({ ok: false, reason: 'no-message' });
+  return streamNdjson(opts.endpoint, { message, source: 'shakers-cli' }, { hubAccessToken, ...opts });
+}
+
+function streamAlmaDecision({ hubAccessToken, approved } = {}, opts = {}) {
+  if (typeof approved !== 'boolean') return Promise.resolve({ ok: false, reason: 'no-decision' });
+  return streamNdjson(opts.endpoint, { approved }, { hubAccessToken, ...opts });
+}
+
+// CLI+MCP entry: resolve the endpoint from config, then stream one turn.
+async function askAlma(deps = {}, { hubAccessToken, message, onEvent, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const {
+    getAlmaChatEndpoint = require('./config').getAlmaChatEndpoint,
+    streamAlmaChat: stream = streamAlmaChat,
+  } = deps;
+  const endpoint = getAlmaChatEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return stream({ hubAccessToken, message }, { endpoint, onEvent, timeoutMs });
+}
+
+async function decideAlma(deps = {}, { hubAccessToken, approved, onEvent, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const {
+    getAlmaDecisionEndpoint = require('./config').getAlmaDecisionEndpoint,
+    streamAlmaDecision: stream = streamAlmaDecision,
+  } = deps;
+  const endpoint = getAlmaDecisionEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return stream({ hubAccessToken, approved }, { endpoint, onEvent, timeoutMs });
+}
+
+module.exports = {
+  streamAlmaChat,
+  streamAlmaDecision,
+  askAlma,
+  decideAlma,
+};

package/src/alma-flow.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const EXIT_WORDS = new Set(['exit', 'quit', 'salir', 'q']);
+
+function makeAlmaDeps(overrides = {}) {
+  const client = require('./alma-client');
+  return {
+    askAlma: (opts) => client.askAlma({}, opts),
+    decideAlma: (opts) => client.decideAlma({}, opts),
+    startSpinner: (label) => require('./terminal-progress').startSpinner(label),
+    collectContextBlock: (o) => require('./alma-repo-context').collectContextBlock(o),
+    withStatus: (label, fn) => require('./terminal-progress').withStaticStatus(label, fn),
+    ...overrides,
+  };
+}
+
+async function oneTurn({ io, hubAccessToken, message, catalog, deps, onStreamEvent = null, sendTurn = null }) {
+  const fp = catalog.ask;
+  const stop = deps.startSpinner ? deps.startSpinner(fp.thinking) : () => {};
+  const onEvent = (evt) => { if (typeof onStreamEvent === 'function') onStreamEvent(evt); };
+  const call = sendTurn || ((o) => deps.askAlma(o));
+  const res = await call({ hubAccessToken, message, onEvent });
+  stop();
+  if (!res.ok) io.error(fp.failed(res.reason));
+  return res;
+}
+
+module.exports = {
+  makeAlmaDeps,
+  oneTurn,
+  EXIT_WORDS,
+};