@pitcher/cli-scripts 3.1.1 → 3.3.0

package/dist/src/commands/roleplay.js

@@ -0,0 +1,702 @@
+import { Command } from 'commander';
+import { clickhouseClientFor, clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError, isCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { pageSizeFor } from '../core/analytics-shape.js';
+import { assignmentSessions, repStats, scaleOrNull, sessionScore, skillAverages, } from '../core/roleplay-stats.js';
+import { withAuthFlags } from './withAuth.js';
+export const ROLEPLAY_DIFFICULTIES = ['easy', 'medium', 'hard'];
+export const ROLEPLAY_SESSION_SORT = ['session_at', 'rep_name', 'score', 'duration_ms'];
+export const ROLEPLAY_GROUP_BY = ['rep', 'scenario'];
+export const REP_STATUSES = ['passed', 'in_progress', 'not_started', 'overdue', 'needs_coaching'];
+/** rep-summary reads at most this many pages of this size (5000 sessions), newest first. */
+export const REP_SUMMARY_PAGE_SIZE = 1000;
+export const REP_SUMMARY_MAX_PAGES = 5;
+export const REP_SUMMARY_MAX_GROUPS = 50;
+/** next-core's coach/data returns at most this many sessions, newest first, and no total. */
+export const COACH_DATA_SESSION_CAP = 1000;
+export const TEAM_MAX_ASSIGNMENTS = 50;
+export const TEAM_MAX_REPS_PER_ASSIGNMENT = 100;
+/**
+ * Pass progress (PIT-9971) is read in pages of 2000 (assignment, rep) pairs. Above this many pages the
+ * tools use no progress at all (the manager app allows 100,000 pages; one tool call stays bounded).
+ */
+export const PROGRESS_MAX_PAGES = 10;
+const COACH_BASE = '/core/api/protected/roleplay/coach';
+const APPSDB_QUERY = '/core/api/protected/appsdb/query';
+function requireInstance(opts, verb) {
+    if (!opts.instanceId)
+        throw createCliError('VALIDATION', `--instance-id is required for roleplay ${verb}`);
+    return opts.instanceId;
+}
+/** clickhouse-api params; `scenario` matches the persona OR scenario name server-side (`persona`). */
+function filterParams(opts, instanceId) {
+    if (opts.difficulty && !ROLEPLAY_DIFFICULTIES.includes(opts.difficulty)) {
+        throw createCliError('VALIDATION', `--difficulty must be one of: ${ROLEPLAY_DIFFICULTIES.join(', ')}`);
+    }
+    const params = { instance_id: instanceId };
+    if (opts.startDate)
+        params.start_date = opts.startDate;
+    if (opts.endDate)
+        params.end_date = opts.endDate;
+    if (opts.rep)
+        params.rep = opts.rep;
+    if (opts.scenario)
+        params.persona = opts.scenario;
+    if (opts.difficulty)
+        params.difficulty = opts.difficulty;
+    return params;
+}
+/** Dates have NO default window here (unlike the content-analytics verbs): omitted = all time. */
+function windowOf(opts) {
+    return { start_date: opts.startDate ?? null, end_date: opts.endDate ?? null };
+}
+export const finiteOrNull = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+/** clickhouse-api's roleplay routes are instance/org-admin only: say so, and where a manager goes instead. */
+function adminOnlyError(e) {
+    const err = toCliError(e);
+    if (err.code !== 'AUTH')
+        return err;
+    return createCliError('AUTH', `${err.message} — roleplay analytics are for instance or org admins; a coaching manager can use roleplay team`);
+}
+// ── kpis ─────────────────────────────────────────────────────────────────────
+/** Totals for the window: sessions, scored/unscored, mean score over SCORED sessions only, active reps. */
+export async function runRoleplayKpis(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'kpis');
+        const params = filterParams(opts, instanceId);
+        const client = clickhouseClientFor(opts, deps);
+        const res = await client.get('/analytics/roleplay/kpis', { params });
+        return ok({ ...res.data, window: windowOf(opts) });
+    }
+    catch (e) {
+        return fail(adminOnlyError(e));
+    }
+}
+// ── sessions ─────────────────────────────────────────────────────────────────
+const SESSION_FIELDS = [
+    'entry_id',
+    'session_at',
+    'rep_name',
+    'who',
+    'scenario_name',
+    'persona_name',
+    'difficulty',
+    'score',
+    'evaluated',
+    'rating',
+    'duration_ms',
+];
+/** The row allowlist: nothing else from the replica (provider, recording flags, rubric) leaves. */
+export function pickSessionRow(row) {
+    const out = {};
+    for (const f of SESSION_FIELDS)
+        out[f] = row[f] ?? null;
+    out.score = finiteOrNull(row.score);
+    return out;
+}
+export async function runRoleplaySessions(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'sessions');
+        if (opts.sortBy && !ROLEPLAY_SESSION_SORT.includes(opts.sortBy)) {
+            throw createCliError('VALIDATION', `--sort-by must be one of: ${ROLEPLAY_SESSION_SORT.join(', ')}`);
+        }
+        const sortOrder = opts.sortOrder?.toLowerCase();
+        if (sortOrder && sortOrder !== 'asc' && sortOrder !== 'desc') {
+            throw createCliError('VALIDATION', '--sort-order must be asc or desc');
+        }
+        const page = Number.isInteger(opts.page) && opts.page > 0 ? opts.page : 1;
+        const pageSize = pageSizeFor(opts.limit);
+        const params = { ...filterParams(opts, instanceId), page, page_size: pageSize };
+        if (opts.sortBy)
+            params.sort_by = opts.sortBy;
+        if (sortOrder)
+            params.sort_order = sortOrder;
+        const client = clickhouseClientFor(opts, deps);
+        const res = await client.get('/analytics/roleplay/sessions', { params });
+        const body = (res.data ?? {});
+        const rows = (Array.isArray(body.data) ? body.data : []).slice(0, pageSize).map(pickSessionRow);
+        const total = typeof body.total === 'number' ? body.total : rows.length;
+        const shown = (page - 1) * pageSize + rows.length;
+        const hasMore = shown < total;
+        return ok({
+            rows,
+            total_count: total,
+            returned: rows.length,
+            page,
+            has_more: hasMore,
+            ...(hasMore
+                ? { truncated: `Showing ${rows.length} of ${total.toLocaleString('en-US')} (page ${page}) — pass page=${page + 1} or narrow with filters` }
+                : {}),
+            window: windowOf(opts),
+        });
+    }
+    catch (e) {
+        return fail(adminOnlyError(e));
+    }
+}
+const round1 = (n) => Math.round(n * 10) / 10;
+/**
+ * Per-rep (keyed on the rep email `who`) or per-scenario (keyed on `scenario_id`) aggregates over
+ * the sessions list, read in pages of 1000 (newest first) up to 5000. `complete: false` when the
+ * window holds more than that; then the figures cover the newest 5000 only.
+ */
+export async function runRoleplayRepSummary(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'rep-summary');
+        const groupBy = opts.groupBy ?? 'rep';
+        if (!ROLEPLAY_GROUP_BY.includes(groupBy)) {
+            throw createCliError('VALIDATION', `--group-by must be one of: ${ROLEPLAY_GROUP_BY.join(', ')}`);
+        }
+        const base = filterParams(opts, instanceId);
+        const client = clickhouseClientFor(opts, deps);
+        const fetched = [];
+        let total = 0;
+        for (let page = 1; page <= REP_SUMMARY_MAX_PAGES; page += 1) {
+            const res = await client.get('/analytics/roleplay/sessions', {
+                params: { ...base, page, page_size: REP_SUMMARY_PAGE_SIZE, sort_by: 'session_at', sort_order: 'desc' },
+            });
+            const body = (res.data ?? {});
+            const batch = Array.isArray(body.data) ? body.data : [];
+            total = typeof body.total === 'number' ? body.total : fetched.length + batch.length;
+            fetched.push(...batch);
+            if (batch.length < REP_SUMMARY_PAGE_SIZE || fetched.length >= total)
+                break;
+        }
+        const groups = new Map();
+        for (const row of fetched) {
+            const key = String((groupBy === 'rep' ? row.who : row.scenario_id) ?? '');
+            const name = String((groupBy === 'rep' ? row.rep_name || row.who : row.scenario_name || row.persona_name) ?? '');
+            const g = groups.get(key) ?? { name, sessions: 0, scores: [], last: null };
+            g.sessions += 1;
+            const score = finiteOrNull(row.score);
+            if (score !== null)
+                g.scores.push(score);
+            const at = typeof row.session_at === 'string' ? row.session_at : null;
+            if (at && (!g.last || at > g.last))
+                g.last = at;
+            groups.set(key, g);
+        }
+        const all = Array.from(groups.entries())
+            .map(([key, g]) => ({
+            key,
+            name: g.name,
+            sessions: g.sessions,
+            scored_sessions: g.scores.length,
+            avg_score: g.scores.length ? round1(g.scores.reduce((a, b) => a + b, 0) / g.scores.length) : null,
+            last_session_at: g.last,
+        }))
+            .sort((a, b) => b.sessions - a.sessions || a.key.localeCompare(b.key));
+        const shown = all.slice(0, REP_SUMMARY_MAX_GROUPS);
+        const complete = fetched.length >= total;
+        const warnings = [];
+        if (!complete) {
+            warnings.push(`Covers the newest ${fetched.length.toLocaleString('en-US')} of ${total.toLocaleString('en-US')} sessions; narrow the dates for exact figures`);
+        }
+        return ok({
+            group_by: groupBy,
+            key_field: groupBy === 'rep' ? 'who (rep email)' : 'scenario_id',
+            groups: shown,
+            total_groups: all.length,
+            returned: shown.length,
+            sessions_read: fetched.length,
+            total_sessions: total,
+            complete,
+            ...(all.length > shown.length
+                ? { truncated: `Showing the ${shown.length} ${groupBy === 'rep' ? 'reps' : 'scenarios'} with most sessions of ${all.length}` }
+                : {}),
+            ...(warnings.length ? { warnings } : {}),
+            window: windowOf(opts),
+        });
+    }
+    catch (e) {
+        return fail(adminOnlyError(e));
+    }
+}
+/** `scopePref: 'coach'` skips the instance attempt; otherwise instance first, the caller's coaching scope on 403. */
+async function getCoachBundle(client, instanceId, scopePref) {
+    const headers = { 'x-instance-id': instanceId };
+    const asCoach = async () => {
+        const res = await client.get(`${COACH_BASE}/data`, { params: { instance_id: instanceId }, headers });
+        return { bundle: (res.data ?? {}), requested: 'coach' };
+    };
+    if (scopePref === 'coach')
+        return asCoach();
+    try {
+        const res = await client.get(`${COACH_BASE}/data`, { params: { instance_id: instanceId, scope: 'instance' }, headers });
+        return { bundle: (res.data ?? {}), requested: 'instance' };
+    }
+    catch (e) {
+        // Not an instance or org admin: fall back to the caller's own coaching assignments.
+        if (toCliError(e).code !== 'AUTH')
+            throw e;
+        return asCoach();
+    }
+}
+/** The caller's OWN coaching scope (coach/data without `scope`): what a coach may comment on (PIT-10113). */
+export async function getOwnCoachBundle(client, instanceId) {
+    return (await getCoachBundle(client, instanceId, 'coach')).bundle;
+}
+/** The manager app's progress map key (`useManagerData.ts`). */
+export const progressKey = (assignmentId, repUserId) => `${assignmentId}\u0000${repUserId}`;
+function toProgress(e) {
+    return {
+        passed: e.passed === true,
+        passSource: e.passSource === 'stored' || e.passSource === 'live' ? e.passSource : null,
+        attempts: typeof e.attempts === 'number' && Number.isFinite(e.attempts) ? e.attempts : 0,
+        bestScore: finiteOrNull(e.bestScore),
+        latestAt: typeof e.latestAt === 'string' ? e.latestAt : null,
+    };
+}
+const isProgressPage = (b) => Array.isArray(b.assignmentProgress) && !!b.assignmentProgressPage && typeof b.assignmentProgressPage.totalPairs === 'number';
+const PROGRESS_CHANGED = Symbol('progress-changed');
+/** Every page from 0, progress-only (`fetchAllProgressPages`, manager-app `lib/api.ts`). */
+async function fetchAllProgressPages(client, instanceId, scope) {
+    const out = [];
+    let total = null;
+    for (let page = 0; page < PROGRESS_MAX_PAGES; page += 1) {
+        const params = { instance_id: instanceId, assignment_page: page };
+        if (scope === 'instance')
+            params.scope = 'instance';
+        const res = await client.get(`${COACH_BASE}/data`, { params, headers: { 'x-instance-id': instanceId } });
+        const body = (res.data ?? {});
+        if (!isProgressPage(body))
+            throw new Error(`coach/data assignment_page=${page}: no progress in the answer`);
+        if (total !== null && body.assignmentProgressPage.totalPairs !== total)
+            return PROGRESS_CHANGED;
+        total = body.assignmentProgressPage.totalPairs;
+        out.push(...body.assignmentProgress);
+        if (!body.assignmentProgressPage.hasMore)
+            return out;
+    }
+    throw new Error(`coach/data: assignment progress has more than ${PROGRESS_MAX_PAGES} pages`);
+}
+const PROGRESS_LOST = 'Pass progress could not be loaded completely, so statuses, session counts and best scores come from the newest sessions only';
+/**
+ * `loadAssignmentProgress`: one page = the bundle's page 0 as is; more = every page from 0, progress-only
+ * with the APPLIED scope, restarted once if `totalPairs` changes; any failure, a second change or more
+ * than PROGRESS_MAX_PAGES pages = no progress (all-or-nothing). Absent progress is normal (empty bundle,
+ * older next-core, a server-side progress failure) and is not a warning.
+ */
+async function loadProgress(client, instanceId, bundle, scope, warnings) {
+    if (!isProgressPage(bundle))
+        return null;
+    const first = bundle.assignmentProgressPage;
+    let entries = null;
+    if (!first.hasMore)
+        entries = bundle.assignmentProgress;
+    else if (first.pageSize > 0 && Math.ceil(first.totalPairs / first.pageSize) > PROGRESS_MAX_PAGES)
+        entries = null;
+    else {
+        try {
+            const pass = await fetchAllProgressPages(client, instanceId, scope);
+            const again = pass === PROGRESS_CHANGED ? await fetchAllProgressPages(client, instanceId, scope) : pass;
+            entries = again === PROGRESS_CHANGED ? null : again;
+        }
+        catch {
+            entries = null;
+        }
+    }
+    if (!entries) {
+        warnings.push(PROGRESS_LOST);
+        return null;
+    }
+    const map = new Map();
+    for (const e of entries) {
+        if (typeof e.assignmentId !== 'string' || (typeof e.repUserId !== 'string' && typeof e.repUserId !== 'number'))
+            continue;
+        map.set(progressKey(e.assignmentId, String(e.repUserId)), toProgress(e));
+    }
+    return map;
+}
+/** D18 rep order: the reps who need the manager first. */
+export const STATUS_RANK = { overdue: 0, needs_coaching: 1, in_progress: 2, not_started: 3, passed: 4 };
+const cmpStr = (a, b) => (a ?? '').localeCompare(b ?? '', 'en');
+/** D18 assignment order: active first, then due date ascending (none last), then scenario name, then id. */
+export function compareAssignments(a, b) {
+    const active = Number(b.active !== false) - Number(a.active !== false);
+    if (active)
+        return active;
+    if (a.dueDate !== b.dueDate) {
+        if (!a.dueDate)
+            return 1;
+        if (!b.dueDate)
+            return -1;
+        return a.dueDate < b.dueDate ? -1 : 1;
+    }
+    return cmpStr(a.scenarioName, b.scenarioName) || cmpStr(a.id, b.id);
+}
+/** D18 rep order: status rank, then name (no name last), then user id. */
+export function compareReps(a, b) {
+    const rank = STATUS_RANK[a.status] - STATUS_RANK[b.status];
+    if (rank)
+        return rank;
+    if (a.name !== b.name) {
+        if (a.name === null)
+            return 1;
+        if (b.name === null)
+            return -1;
+    }
+    return cmpStr(a.name, b.name) || cmpStr(a.user_id, b.user_id);
+}
+/**
+ * The one team derivation shared by `roleplay team` and the roleplay manager view (PIT-10068): the
+ * coach bundle, its pass progress, the roleplay filters and the D18 order, so the text tool and the
+ * view always cut the same 50 assignments.
+ */
+export async function loadTeamModel(client, instanceId, scopePref) {
+    const { bundle, requested } = await getCoachBundle(client, instanceId, scopePref);
+    // An older next-core ignores scope=instance and answers without `scope`: report what was applied.
+    const scope = bundle.scope === 'instance' && requested === 'instance' ? 'instance' : 'coach';
+    const sessions = (bundle.sessions ?? []).filter((s) => s.sessionType !== 'manager-video-practice');
+    const assignments = (bundle.assignments ?? []).filter((a) => a.contentType !== 'practice').sort(compareAssignments);
+    const warnings = [];
+    const sessionsCapped = sessions.length >= COACH_DATA_SESSION_CAP;
+    if (sessionsCapped) {
+        warnings.push(`The server returned its maximum of ${COACH_DATA_SESSION_CAP} sessions (newest first); older sessions are missing, so statuses and averages may be understated`);
+    }
+    const progress = await loadProgress(client, instanceId, bundle, scope, warnings);
+    let pairsWithoutProgress = 0;
+    if (progress) {
+        for (const a of assignments) {
+            for (const id of a.resolvedUserIds ?? [])
+                if (!progress.has(progressKey(a.id, id)))
+                    pairsWithoutProgress += 1;
+        }
+    }
+    return {
+        scope,
+        requested,
+        coverage: { sessionsCapped, progress: progress ? 'full' : 'none', pairsWithoutProgress },
+        warnings,
+        assignments,
+        sessions,
+        progress,
+    };
+}
+/**
+ * Assignment completion per rep, ported from the manager app: an admin gets every roleplay
+ * assignment on the instance (`scope=instance`), anyone else the assignments they coach.
+ * Statuses, session counts and best scores follow `deriveStatus` / `repStats` with the server's
+ * pass progress when it loads (PIT-9971); assignments and reps in D18 order (`loadTeamModel`).
+ * Raw sessions, evaluations and comments never leave.
+ */
+export async function runRoleplayTeam(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'team');
+        if (opts.status && !REP_STATUSES.includes(opts.status)) {
+            throw createCliError('VALIDATION', `--status must be one of: ${REP_STATUSES.join(', ')}`);
+        }
+        const client = clientFor(opts, deps);
+        const model = await loadTeamModel(client, instanceId);
+        const { scope, sessions, progress, coverage, warnings } = model;
+        const roleplayAssignments = model.assignments;
+        const selected = opts.assignmentId ? roleplayAssignments.filter((a) => a.id === opts.assignmentId) : roleplayAssignments;
+        if (opts.assignmentId && selected.length === 0) {
+            throw createCliError('NOT_FOUND', `No roleplay assignment ${opts.assignmentId} in this ${scope === 'instance' ? 'instance' : 'coaching scope'}`);
+        }
+        const now = new Date();
+        const shownAssignments = selected.slice(0, TEAM_MAX_ASSIGNMENTS);
+        const assignments = shownAssignments.map((a) => {
+            const own = assignmentSessions(sessions, a);
+            const reps = (a.resolvedUserIds ?? [])
+                .map((id) => ({
+                ...repStats(id, own, a, now, progress?.get(progressKey(a.id, id)) ?? null),
+                name: a.resolvedUserNames?.[id] ?? null,
+            }))
+                .sort(compareReps);
+            const statusCounts = Object.fromEntries(REP_STATUSES.map((st) => [st, reps.filter((r) => r.status === st).length]));
+            const filtered = opts.status ? reps.filter((r) => r.status === opts.status) : reps;
+            const shownReps = filtered.slice(0, TEAM_MAX_REPS_PER_ASSIGNMENT);
+            return {
+                id: a.id,
+                scenario_id: a.scenarioId,
+                scenario_name: a.scenarioName ?? null,
+                type: a.type,
+                passing_score: a.passingScore,
+                due_date: a.dueDate,
+                active: a.active !== false,
+                created_at: a.createdAt,
+                rep_count: reps.length,
+                status_counts: statusCounts,
+                skills: skillAverages(own),
+                reps: shownReps,
+                ...(filtered.length > shownReps.length
+                    ? { truncated: `Showing ${shownReps.length} of ${filtered.length} reps — filter with status` }
+                    : {}),
+            };
+        });
+        return ok({
+            scope,
+            complete: !coverage.sessionsCapped,
+            coverage,
+            assignments,
+            total_assignments: selected.length,
+            returned: assignments.length,
+            ...(selected.length > assignments.length
+                ? { truncated: `Showing ${assignments.length} of ${selected.length} assignments — pass assignmentId` }
+                : {}),
+            ...(warnings.length ? { warnings } : {}),
+        });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * The allowlist, shared by `roleplay session` and the manager view's scorecard. Never the transcript,
+ * messages, contact name, graded snapshot, voice session, recording or audio ids, or any
+ * video-evaluation field. The two scales (`grading_scale`, `max_score`) are numbers only (PIT-10068):
+ * legacy evaluations grade on 5, and a skill score is meaningless without its scale.
+ */
+export function pickSessionDetail(id, data) {
+    const evaluation = (data.evaluation ?? null);
+    const categories = Array.isArray(evaluation?.category_scores) ? evaluation.category_scores : [];
+    const score = sessionScore(data);
+    return {
+        id,
+        scenario_name: data.scenarioName ?? null,
+        difficulty: data.difficulty ?? null,
+        timestamp: data.timestamp ?? null,
+        duration_ms: finiteOrNull(data.durationMs),
+        overall_score: score,
+        scored: score !== null,
+        evaluation_status: data.evaluationStatus ?? null,
+        evaluation: evaluation
+            ? {
+                summary: evaluation.summary ?? null,
+                strengths: Array.isArray(evaluation.strengths) ? evaluation.strengths : [],
+                improvements: Array.isArray(evaluation.improvements) ? evaluation.improvements : [],
+                grading_scale: scaleOrNull(evaluation.grading_scale),
+                category_scores: categories.map((c) => ({
+                    skill_id: c.skillId ?? null,
+                    title: c.title ?? null,
+                    score: finiteOrNull(c.score),
+                    max_score: scaleOrNull(c.max_score),
+                    feedback: c.feedback ?? null,
+                })),
+            }
+            : null,
+    };
+}
+export async function runRoleplaySessionGet(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'session');
+        if (!opts.entryId)
+            throw createCliError('VALIDATION', '--entry-id is required for roleplay session');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`${COACH_BASE}/sessions/${encodeURIComponent(opts.entryId)}`, {
+            params: { instance_id: instanceId },
+            headers: { 'x-instance-id': instanceId },
+        });
+        const body = (res.data ?? {});
+        return ok(pickSessionDetail(String(body.id ?? opts.entryId), body.data ?? {}));
+    }
+    catch (e) {
+        if (isCliError(e))
+            return fail(e);
+        const err = toCliError(e);
+        if (err.code === 'AUTH') {
+            return fail(createCliError('AUTH', `${err.message} — a session opens to its rep, a coach of that rep, or an instance or org admin`));
+        }
+        return fail(err);
+    }
+}
+// ── scenarios ────────────────────────────────────────────────────────────────
+/** The trimmed catalog: never the persona prompt or the evaluation prompt. */
+export function pickScenario(s) {
+    const persona = (s.persona ?? null);
+    const assessment = (s.assessment ?? null);
+    return {
+        id: s.id ?? null,
+        kind: s.kind === 'multi' ? 'multi' : 'single',
+        name: (persona?.name ?? s.name ?? null),
+        persona_title: persona?.title ?? null,
+        description: s.description ?? null,
+        difficulty: s.difficulty ?? 'medium',
+        active: s.active !== false,
+        time_limit_minutes: s.time_limit_minutes ?? null,
+        categories: (assessment?.categories ?? []).map((c) => ({ title: c.title ?? null, weight: c.weight ?? null })),
+    };
+}
+export async function runRoleplayScenariosList(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'scenarios');
+        const client = clientFor(opts, deps);
+        // Newest row only: duplicate cch-config rows exist, and the admin app reads the same one.
+        const res = await client.post(APPSDB_QUERY, {
+            type: 'cch-config',
+            where: { field: 'instance_id', operator: 'eq', value: instanceId },
+            orderBy: [{ field: 'updated_at', direction: 'desc' }],
+            limit: 1,
+        }, { headers: { 'x-instance-id': instanceId } });
+        const entry = (res.data ?? {}).entries?.[0];
+        const scenarios = Array.isArray(entry?.data?.scenarios) ? entry.data.scenarios : [];
+        return ok({ configured: !!entry, scenarios: scenarios.map(pickScenario), total_count: scenarios.length });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+// ── learning paths (PIT-10113) ───────────────────────────────────────────────
+const PATHS_BASE = '/core/api/protected/roleplay/paths';
+const PATH_ASSIGNMENTS = '/core/api/protected/roleplay/path-assignments';
+export const ROLEPLAY_PATH_STATUSES = ['published', 'draft', 'all'];
+/** The trimmed path: counts, never the stage/step bodies. */
+export function pickPath(p) {
+    return {
+        id: String(p.id ?? ''),
+        name: typeof p.name === 'string' ? p.name : '',
+        status: typeof p.status === 'string' ? p.status : '',
+        version: typeof p.version === 'number' ? p.version : 0,
+        stages: Array.isArray(p.stages) ? p.stages.length : 0,
+        steps: Array.isArray(p.steps) ? p.steps.length : 0,
+        default_passing_score: finiteOrNull(p.defaultPassingScore),
+        updated_at: typeof p.updatedAt === 'string' ? p.updatedAt : null,
+    };
+}
+/** next-core `GET roleplay/paths` (builder roles; 404 when paths are off or the caller is not a member). */
+export async function fetchPaths(client, instanceId, status = 'published') {
+    const res = await client.get(PATHS_BASE, {
+        params: { instance_id: instanceId, status },
+        headers: { 'x-instance-id': instanceId },
+    });
+    const paths = res.data?.paths;
+    return Array.isArray(paths) ? paths : [];
+}
+export async function runRoleplayPathsList(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'paths');
+        const status = opts.status ?? 'published';
+        if (!ROLEPLAY_PATH_STATUSES.includes(status)) {
+            throw createCliError('VALIDATION', `--status must be one of ${ROLEPLAY_PATH_STATUSES.join(', ')}`);
+        }
+        const client = clientFor(opts, deps);
+        const paths = (await fetchPaths(client, instanceId, status)).map(pickPath);
+        return ok({ paths, total_count: paths.length });
+    }
+    catch (e) {
+        if (isCliError(e))
+            return fail(e);
+        const err = toCliError(e);
+        if (err.code === 'NOT_FOUND') {
+            return fail(createCliError('NOT_FOUND', 'Learning paths are not enabled on this instance, or you are not a member of it', err.backendStatus));
+        }
+        return fail(err);
+    }
+}
+/** next-core `GET roleplay/path-assignments`: the records in the caller's view (admins get the membership keys). */
+export async function fetchPathRecords(client, instanceId) {
+    const res = await client.get(PATH_ASSIGNMENTS, { params: { instance_id: instanceId }, headers: { 'x-instance-id': instanceId } });
+    const records = res.data?.records;
+    return Array.isArray(records) ? records : [];
+}
+// ── confirmed writes (PIT-10113): the three next-core calls, each with an Idempotency-Key ─────────────────────────
+/** A stored answer replayed by next-core: 200 with `Idempotent-Replay: true`. */
+function isReplay(res) {
+    const h = (res.headers ?? {});
+    const v = typeof h.get === 'function' ? h.get('idempotent-replay') : (h['idempotent-replay'] ?? h['Idempotent-Replay']);
+    return res.status === 200 && String(v).toLowerCase() === 'true';
+}
+export async function postCoachComment(client, args, idempotencyKey) {
+    const res = await client.post(`${COACH_BASE}/comments`, {
+        instanceId: args.instanceId,
+        sessionEntryId: args.sessionEntryId,
+        feedbackType: args.sessionEntryId ? 'session' : 'general',
+        assignmentId: args.assignmentId,
+        repUserId: args.repUserId,
+        comment: args.comment,
+        product: 'roleplay',
+    }, { headers: { 'x-instance-id': args.instanceId, 'Idempotency-Key': idempotencyKey } });
+    return { body: (res.data ?? {}), replayed: isReplay(res) };
+}
+export async function deleteCoachComment(client, args, idempotencyKey) {
+    const res = await client.delete(`${COACH_BASE}/comments/${encodeURIComponent(args.commentId)}`, {
+        params: { instance_id: args.instanceId },
+        headers: { 'x-instance-id': args.instanceId, 'Idempotency-Key': idempotencyKey },
+    });
+    return { replayed: isReplay(res) };
+}
+export async function postPathAssignment(client, instanceId, body, idempotencyKey) {
+    // exactly the six schema keys: the strict schema refuses any other (instance_id rides in the query)
+    const res = await client.post(PATH_ASSIGNMENTS, {
+        pathId: body.pathId,
+        groupIds: body.groupIds,
+        recipientUserIds: body.recipientUserIds,
+        managerIds: body.managerIds,
+        mandatory: body.mandatory,
+        dueDate: body.dueDate,
+    }, { params: { instance_id: instanceId }, headers: { 'x-instance-id': instanceId, 'Idempotency-Key': idempotencyKey } });
+    return { body: (res.data ?? {}), replayed: isReplay(res) };
+}
+// ── commander ────────────────────────────────────────────────────────────────
+const ADMIN_NOTE = 'instance or org admins only';
+function withFilterFlags(cmd) {
+    return cmd
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--start-date <iso>', 'Window start (ISO date; omitted = all time)')
+        .option('--end-date <iso>', 'Window end (ISO date; omitted = all time)')
+        .option('--rep <text>', 'Rep name or email contains')
+        .option('--scenario <text>', 'Scenario or persona name contains')
+        .option('--difficulty <level>', `Difficulty: ${ROLEPLAY_DIFFICULTIES.join(', ')}`);
+}
+export function createRoleplayCommand() {
+    const cmd = new Command('roleplay').description('read AI Roleplay sessions, scores and assignment completion');
+    withFilterFlags(withAuthFlags(cmd.command('kpis')))
+        .description(`roleplay totals: sessions, scored/unscored, mean score of scored sessions, active reps (${ADMIN_NOTE})`)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayKpis({ ...options, quiet: globals.quiet }), globals);
+    });
+    withFilterFlags(withAuthFlags(cmd.command('sessions')))
+        .option('--sort-by <field>', `Sort field: ${ROLEPLAY_SESSION_SORT.join(', ')}`)
+        .option('--sort-order <dir>', 'asc or desc (default desc)')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Rows per page (default 20, max 100)', (v) => parseInt(v, 10))
+        .description(`roleplay session list (${ADMIN_NOTE})`)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplaySessions({ ...options, quiet: globals.quiet }), globals);
+    });
+    withFilterFlags(withAuthFlags(cmd.command('rep-summary')))
+        .option('--group-by <key>', `Group by: ${ROLEPLAY_GROUP_BY.join(', ')} (default rep)`)
+        .description(`per-rep or per-scenario session counts and mean scores (${ADMIN_NOTE})`)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayRepSummary({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('team'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--assignment-id <id>', 'Only this assignment')
+        .option('--status <status>', `Only reps with this status: ${REP_STATUSES.join(', ')}`)
+        .description('assignment completion per rep: every assignment for admins, your coached ones for managers')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayTeam({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('session'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--entry-id <id>', 'Session entry ID (required; entry_id from roleplay sessions)')
+        .description('one session: score, summary, strengths, improvements, per-skill scores (no transcript)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplaySessionGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('scenarios'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .description('the instance scenario catalog (names, difficulty, skills; no prompts)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayScenariosList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('paths'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--status <status>', `Path status: ${ROLEPLAY_PATH_STATUSES.join(', ')} (default published)`)
+        .description('the instance learning paths: id, name, version, stage and step counts (instance admins and editors, org admins)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayPathsList({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}