@pitcher/cli-scripts 3.2.0 → 3.3.0

package/dist/src/mcp/apps/roleplayManager.js

@@ -0,0 +1,606 @@
+import { z } from 'zod';
+import { compareReps, finiteOrNull, loadTeamModel, progressKey, REP_STATUSES, runRoleplaySessionGet, STATUS_RANK, } from '../../commands/roleplay.js';
+import { ok, fail } from '../../core/envelope.js';
+import { createCliError } from '../../core/errors.js';
+import { clientFor, toCliError } from '../../core/http.js';
+import { assignmentSessions, latestSkills, meanOfFinite, normalizeScore, repStats, scoredCount, sessionScore, } from '../../core/roleplay-stats.js';
+import { byteLen, clipBytes, fitText as fitAppText, jsonBytes, listHead } from './text.js';
+/**
+ * MCP Apps AI Roleplay manager view (PIT-10068): a KPI header and the assignment grid, then drills into one
+ * assignment's reps, one rep's sessions and one session's scorecard. Read-only. Every tool derives from
+ * `loadTeamModel`, the loader `pitcher_roleplay_team` uses, so the view and the text tool never disagree.
+ * The runners live here, not in commands/roleplay.ts: registry.test.ts requires every `run*` of a command
+ * module to back exactly one `allTools` tool, and app tools are not in `allTools` (D25).
+ */
+export const roleplayManagerView = {
+    name: 'roleplay-manager',
+    title: 'Pitcher AI Roleplay team view',
+    description: 'Team assignment completion, rep drill and session scorecard for AI Roleplay managers.',
+    // csp omitted: block all external origins (no thumbnails; avatars are initials)
+};
+/** structuredContent budget per result (the picker's, PIT-10066 D14). */
+export const ROLEPLAY_VIEW_MAX_BYTES = 120000;
+/** Model-facing text budget per result, in UTF-8 bytes. */
+export const ROLEPLAY_TEXT_MAX_BYTES = 4096;
+export const REPS_PAGE_SIZE = 25;
+export const REP_SESSIONS_MAX = 50;
+export const VIEW_MAX_ASSIGNMENTS = 50;
+const NEEDS_ATTENTION_MAX = 10;
+const MORE_RESERVED_BYTES = 120;
+// ── text in bytes (7.3; helpers in text.ts) ───────────────────────────────────
+/** The roleplay text budget over the shared helper (also used by roleplayReps.ts). */
+export const roleplayFitText = (input) => fitAppText({ ...input, maxBytes: ROLEPLAY_TEXT_MAX_BYTES, reserve: MORE_RESERVED_BYTES });
+/** One decimal, no trailing ".0" (66.66666 -> "66.7"). */
+export const fmtNum = (x) => String(Math.round(x * 10) / 10);
+export const inRange = (x) => x !== null && Number.isFinite(x) && x >= 0 && x <= 9999;
+/** "62/100", "unscored", or the whole token "invalid" when the score or the scale is outside 0..9999. */
+export function scoreToken(score, scale) {
+    if (score === null)
+        return 'unscored';
+    const s = scale ?? 100;
+    return inRange(score) && inRange(s) ? `${fmtNum(score)}/${fmtNum(s)}` : 'invalid';
+}
+/** "2026-11-02 14:05" in UTC (ASCII), or the fixed "unknown-date --:--". */
+export function fmtUtc(ts) {
+    const d = ts ? new Date(ts) : null;
+    if (!d || Number.isNaN(d.getTime()))
+        return 'unknown-date --:--';
+    return d.toISOString().slice(0, 16).replace('T', ' ');
+}
+export const name60 = (s, fallback) => clipBytes(s || fallback, 60);
+export const STATUS_TEXT = {
+    passed: 'passed',
+    in_progress: 'in progress',
+    not_started: 'not started',
+    overdue: 'overdue',
+    needs_coaching: 'needs coaching',
+};
+const fmtMean = (m) => (m === null ? 'no scored sessions' : `mean ${fmtNum(m)}`);
+/** 8.2 row 9 (also the capped head of the overview text). */
+export function cappedSentence(coverage) {
+    const exact = coverage.progress === 'full' && coverage.pairsWithoutProgress === 0;
+    return `Newest 1000 sessions only. ${exact
+        ? 'Passed, not started and best scores are exact; trends and averages may be understated.'
+        : 'Some statuses come from these sessions only and may be understated.'}`;
+}
+// ── derivation ───────────────────────────────────────────────────────────────
+export const emptyCounts = () => Object.fromEntries(REP_STATUSES.map((s) => [s, 0]));
+const repOrder = (a, b) => compareReps({ status: a.status, name: a.name, user_id: a.userId }, { status: b.status, name: b.name, user_id: b.userId });
+export function deriveAssignment(model, a, now) {
+    const own = assignmentSessions(model.sessions, a);
+    const reps = (a.resolvedUserIds ?? [])
+        .map((id) => {
+        const r = repStats(id, own, a, now, model.progress?.get(progressKey(a.id, id)) ?? null);
+        return {
+            userId: id,
+            name: a.resolvedUserNames?.[id] ?? null,
+            status: r.status,
+            sessions: r.sessions,
+            scoredSessions: r.scored_sessions,
+            bestScore: r.best_score,
+            avgScore: r.avg_score,
+            trend: r.trend,
+            lastSessionAt: r.last_session_at,
+            recentOnly: r.recent_only,
+            passSource: r.pass_source,
+        };
+    })
+        .sort(repOrder);
+    const statusCounts = emptyCounts();
+    for (const r of reps)
+        statusCounts[r.status] += 1;
+    return {
+        assignment: a,
+        own,
+        reps,
+        summary: {
+            id: a.id,
+            scenarioName: a.scenarioName ?? null,
+            type: a.type,
+            passingScore: a.passingScore,
+            dueDate: a.dueDate ?? null,
+            active: a.active !== false,
+            repCount: reps.length,
+            sessions: reps.reduce((n, r) => n + r.sessions, 0),
+            meanScore: meanOfFinite(own.map(sessionScore)),
+            statusCounts,
+        },
+    };
+}
+function headerOf(models) {
+    const statusCounts = emptyCounts();
+    const reps = new Set();
+    let sessions = 0;
+    let scoredSessions = 0;
+    const scores = [];
+    for (const m of models) {
+        for (const r of m.reps) {
+            reps.add(r.userId);
+            statusCounts[r.status] += 1;
+            sessions += r.sessions;
+        }
+        scoredSessions += scoredCount(m.own);
+        scores.push(...m.own.map(sessionScore));
+    }
+    const pairs = models.reduce((n, m) => n + m.reps.length, 0);
+    return {
+        assignments: models.length,
+        reps: reps.size,
+        sessions,
+        scoredSessions,
+        meanScore: meanOfFinite(scores),
+        passedPairs: statusCounts.passed,
+        repAssignmentPairs: pairs,
+        statusCounts,
+    };
+}
+export function scoped(kind, instanceId, model) {
+    return { kind, instanceId, scope: model.scope, coverage: model.coverage, complete: !model.coverage.sessionsCapped };
+}
+function repsPage(m, base, status, page) {
+    const filtered = status ? m.reps.filter((r) => r.status === status) : m.reps;
+    const start = (page - 1) * REPS_PAGE_SIZE;
+    const reps = filtered.slice(start, start + REPS_PAGE_SIZE);
+    return {
+        ...base,
+        kind: 'assignment-reps',
+        assignmentId: m.assignment.id,
+        scenarioName: m.assignment.scenarioName ?? null,
+        status,
+        page,
+        pageSize: REPS_PAGE_SIZE,
+        totalReps: filtered.length,
+        hasMore: start + reps.length < filtered.length,
+        reps,
+    };
+}
+const SHORTENED = 'Some feedback was shortened to fit';
+/** When whole skills were dropped, say so: the remaining skills are not the complete scorecard. */
+const SKILLS_OMITTED = 'Some skills were left out to fit; this is not the complete scorecard';
+export const NAME_CHARS = 200;
+/** Clip to `n` code points, "..." included; never leaves a lone surrogate (an emoji renders whole or not at all). */
+export function clipChars(s, n) {
+    const cps = Array.from(s);
+    return cps.length <= n ? s : `${cps.slice(0, n - 3).join('')}...`;
+}
+/**
+ * Overview: drop `selected` whole first (never a shortened page, whose next page would skip reps; the view then
+ * loads that assignment's first page itself), then assignments from the end. Measured with `truncated` included.
+ */
+export function fitRoleplayView(data, max = ROLEPLAY_VIEW_MAX_BYTES) {
+    if (jsonBytes(data) <= max)
+        return data;
+    const out = { ...data, selected: null };
+    const noted = () => {
+        const { truncated: _old, ...rest } = out;
+        return out.assignments.length < data.totalAssignments
+            ? { ...rest, truncated: `Showing ${out.assignments.length} of ${data.totalAssignments} assignments` }
+            : rest;
+    };
+    while (out.assignments.length && jsonBytes(noted()) > max)
+        out.assignments = out.assignments.slice(0, -1);
+    return noted();
+}
+/**
+ * Drill results keep every row (paging continues after the rows sent), so an oversized one clips its free-text
+ * names instead: rep, scenario and skill names to 200 characters, then to 60; then the rep's skills from the end.
+ */
+export function fitAssignmentReps(data, max = ROLEPLAY_VIEW_MAX_BYTES) {
+    let out = data;
+    for (const n of [NAME_CHARS, 60]) {
+        if (jsonBytes(out) <= max)
+            return out;
+        out = {
+            ...out,
+            scenarioName: out.scenarioName === null ? null : clipChars(out.scenarioName, n),
+            reps: out.reps.map((r) => ({ ...r, name: r.name === null ? null : clipChars(r.name, n) })),
+        };
+    }
+    return out;
+}
+export function fitRepSessions(data, max = ROLEPLAY_VIEW_MAX_BYTES) {
+    let out = data;
+    for (const n of [NAME_CHARS, 60]) {
+        if (jsonBytes(out) <= max)
+            return out;
+        out = {
+            ...out,
+            scenarioName: out.scenarioName === null ? null : clipChars(out.scenarioName, n),
+            rep: { ...out.rep, name: out.rep.name === null ? null : clipChars(out.rep.name, n) },
+            latestSkills: out.latestSkills && {
+                ...out.latestSkills,
+                skills: out.latestSkills.skills.map((k) => ({ ...k, title: clipChars(k.title, n), skillId: clipChars(k.skillId, n) })),
+            },
+        };
+    }
+    while (out.latestSkills?.skills.length && jsonBytes(out) > max) {
+        out = { ...out, latestSkills: { ...out.latestSkills, skills: out.latestSkills.skills.slice(0, -1) } };
+    }
+    return out;
+}
+const SCORECARD_ITEM_CHARS = 500;
+const SCORECARD_SUMMARY_CHARS = 2000;
+/**
+ * Scorecard: clip every strength and improvement to 500 characters; then, while the FINAL payload (`truncated`
+ * included) is over budget: drop category feedback from the end, strengths and improvements from the end, clip the
+ * summary to 2000 characters and the names to 200, then drop categories from the end.
+ */
+export function fitScorecard(data, max = ROLEPLAY_VIEW_MAX_BYTES) {
+    let changed = false;
+    const clip = (s, n) => {
+        const c = clipChars(s, n);
+        if (c !== s)
+            changed = true;
+        return c;
+    };
+    const ev = data.evaluation;
+    const e = ev && {
+        ...ev,
+        strengths: ev.strengths.map((s) => clip(String(s), SCORECARD_ITEM_CHARS)),
+        improvements: ev.improvements.map((s) => clip(String(s), SCORECARD_ITEM_CHARS)),
+        category_scores: ev.category_scores.map((c) => ({ ...c })),
+    };
+    const out = { ...data, evaluation: e };
+    let omitted = false;
+    const final = () => (changed ? { ...out, truncated: omitted ? SKILLS_OMITTED : SHORTENED } : out);
+    const over = () => jsonBytes(final()) > max;
+    if (e) {
+        for (let i = e.category_scores.length - 1; i >= 0 && over(); i -= 1) {
+            if (e.category_scores[i].feedback !== null) {
+                e.category_scores[i].feedback = null;
+                changed = true;
+            }
+        }
+        while ((e.strengths.length || e.improvements.length) && over()) {
+            if (e.improvements.length >= e.strengths.length)
+                e.improvements = e.improvements.slice(0, -1);
+            else
+                e.strengths = e.strengths.slice(0, -1);
+            changed = true;
+        }
+        if (over() && e.summary)
+            e.summary = clip(e.summary, SCORECARD_SUMMARY_CHARS);
+        if (over()) {
+            e.category_scores = e.category_scores.map((c) => ({
+                ...c,
+                title: c.title === null ? null : clip(c.title, NAME_CHARS),
+                skill_id: c.skill_id === null ? null : clip(c.skill_id, NAME_CHARS),
+            }));
+        }
+        while (e.category_scores.length && over()) {
+            e.category_scores = e.category_scores.slice(0, -1);
+            changed = true;
+            omitted = true;
+        }
+    }
+    if (over()) {
+        out.scenario_name = out.scenario_name === null ? null : clip(out.scenario_name, NAME_CHARS);
+        out.difficulty = out.difficulty === null ? null : clip(out.difficulty, NAME_CHARS);
+        if (e?.summary && over())
+            e.summary = clip(e.summary, NAME_CHARS);
+    }
+    return final();
+}
+// ── runners (D25) ────────────────────────────────────────────────────────────
+const SCOPES = ['instance', 'coach'];
+export function checkCommon(opts) {
+    if (!opts.instanceId)
+        throw createCliError('VALIDATION', 'instanceId is required');
+    if (opts.scope !== undefined && !SCOPES.includes(opts.scope)) {
+        throw createCliError('VALIDATION', `scope must be one of: ${SCOPES.join(', ')}`);
+    }
+    if (opts.status !== undefined && !REP_STATUSES.includes(opts.status)) {
+        throw createCliError('VALIDATION', `status must be one of: ${REP_STATUSES.join(', ')}`);
+    }
+    return { instanceId: opts.instanceId, scope: opts.scope, status: opts.status ?? null };
+}
+function findAssignment(model, assignmentId) {
+    const a = model.assignments.find((x) => x.id === assignmentId);
+    if (!a) {
+        throw createCliError('NOT_FOUND', `No roleplay assignment ${assignmentId} in this ${model.scope === 'instance' ? 'instance' : 'coaching scope'}`);
+    }
+    return a;
+}
+export async function runRoleplayManagerView(opts, deps = {}) {
+    try {
+        const { instanceId, scope, status } = checkCommon(opts);
+        const model = await loadTeamModel(clientFor(opts, deps), instanceId, scope);
+        if (opts.assignmentId)
+            findAssignment(model, opts.assignmentId);
+        const now = new Date();
+        const models = model.assignments.map((a) => deriveAssignment(model, a, now));
+        const base = scoped('overview', instanceId, model);
+        const pick = opts.assignmentId ? models.find((m) => m.assignment.id === opts.assignmentId) : models.length === 1 ? models[0] : undefined;
+        const data = {
+            ...base,
+            generatedAt: now.toISOString(),
+            header: headerOf(models),
+            assignments: models.slice(0, VIEW_MAX_ASSIGNMENTS).map((m) => m.summary),
+            totalAssignments: models.length,
+            selected: pick ? repsPage(pick, base, status, 1) : null,
+            canViewInstance: scope === 'coach' ? null : model.scope === 'instance',
+            ...(models.length > VIEW_MAX_ASSIGNMENTS ? { truncated: `Showing ${VIEW_MAX_ASSIGNMENTS} of ${models.length} assignments` } : {}),
+        };
+        const fitted = fitRoleplayView(data);
+        // The text head names the reps that need the manager across ALL scoped assignments (D16, D18), more than the
+        // 50 shown, so it is computed here and handed to managerViewText beside the data (keyed on the returned object).
+        attention.set(fitted, needsAttention(models));
+        return ok(fitted, model.warnings);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * Text-only context for managerViewText, never sent in structuredContent (7.1 keeps names of reps outside the
+ * shown page out of the view data). buildServer hands toText the same `env.data` object the runner returned.
+ */
+const attention = new WeakMap();
+/** Overdue and needs_coaching reps: status rank, then the assignment's D18 position, then name (max 10). */
+function needsAttention(models) {
+    const all = [];
+    models.forEach((m, pos) => {
+        for (const r of m.reps) {
+            if (r.status !== 'overdue' && r.status !== 'needs_coaching')
+                continue;
+            all.push({ name: r.name ?? `rep ${r.userId}`, status: r.status, scenario: m.assignment.scenarioName ?? m.assignment.id, pos, userId: r.userId });
+        }
+    });
+    all.sort((a, b) => STATUS_RANK[a.status] - STATUS_RANK[b.status] || a.pos - b.pos || a.name.localeCompare(b.name, 'en') || a.userId.localeCompare(b.userId, 'en'));
+    return { reps: all.slice(0, NEEDS_ATTENTION_MAX), total: all.length };
+}
+export function managerViewText(raw) {
+    const d = raw;
+    const h = d.header;
+    const head1 = `AI Roleplay team (${d.scope} scope): ${h.assignments} assignments, ${h.reps} reps, ${h.sessions} sessions, ` +
+        `${h.meanScore === null ? 'no scored sessions' : `mean score ${fmtNum(h.meanScore)} (scored only)`}. ` +
+        'If your host shows the roleplay team view, the user sees it there; otherwise summarise this for the user.';
+    const att = attention.get(d);
+    const head2 = att?.total
+        ? listHead('Needs attention: ', att.reps.map((r) => `${name60(r.name, 'rep')} (${STATUS_TEXT[r.status]}, ${name60(r.scenario, 'assignment')})`), att.total, 800, `Needs attention: ${att.total} reps.`)
+        : '';
+    const body = d.assignments.map((a) => {
+        const c = a.statusCounts;
+        const meta = [a.type, a.dueDate ? `due ${a.dueDate.slice(0, 10)}` : null, `pass ${fmtNum(a.passingScore)}`, a.active ? null : 'paused']
+            .filter(Boolean)
+            .join(', ');
+        return {
+            text: `${a.id} ${name60(a.scenarioName, a.id)} (${meta}): ${a.repCount} reps; ${c.passed} passed, ${c.overdue} overdue, ` +
+                `${c.needs_coaching} needs coaching, ${c.in_progress} in progress, ${c.not_started} not started; ${fmtMean(a.meanScore)}`,
+        };
+    });
+    return roleplayFitText({
+        heads: [
+            { text: head1, maxBytes: 400 },
+            { text: head2, maxBytes: 800 },
+            { text: d.complete ? '' : cappedSentence(d.coverage), maxBytes: 200 },
+        ],
+        body,
+        hidden: d.totalAssignments - d.assignments.length,
+        more: ({ lines, hidden }) => `...and ${lines + hidden} more assignments: ask for one by name or id.`,
+    });
+}
+export async function runRoleplayAssignmentReps(opts, deps = {}) {
+    try {
+        const { instanceId, scope, status } = checkCommon(opts);
+        if (!opts.assignmentId)
+            throw createCliError('VALIDATION', 'assignmentId is required');
+        const page = opts.page ?? 1;
+        if (!Number.isInteger(page) || page < 1)
+            throw createCliError('VALIDATION', 'page must be an integer from 1');
+        const model = await loadTeamModel(clientFor(opts, deps), instanceId, scope);
+        const m = deriveAssignment(model, findAssignment(model, opts.assignmentId), new Date());
+        return ok(fitAssignmentReps(repsPage(m, scoped('assignment-reps', instanceId, model), status, page)), model.warnings);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function assignmentRepsText(raw) {
+    const d = raw;
+    const first = (d.page - 1) * d.pageSize + 1;
+    const range = d.reps.length ? `reps ${first}-${first + d.reps.length - 1} of ${d.totalReps}` : `no reps of ${d.totalReps}`;
+    const head = `${name60(d.scenarioName, d.assignmentId)} (${d.assignmentId}), ${range} (status: ${d.status ? STATUS_TEXT[d.status] : 'all'}):`;
+    const body = d.reps.map((r) => ({
+        text: `${name60(r.name, 'rep')} (${r.userId}): ${STATUS_TEXT[r.status]}, ` +
+            `best ${r.bestScore === null ? 'none' : fmtNum(r.bestScore)}, ${r.sessions} sessions, last ${r.lastSessionAt ? fmtUtc(r.lastSessionAt).slice(0, 10) : 'none'}`,
+    }));
+    const after = Math.max(0, d.totalReps - (first - 1) - d.reps.length);
+    return roleplayFitText({
+        heads: [{ text: head, maxBytes: 300 }],
+        body,
+        hidden: after,
+        more: ({ lines, hidden }) => hidden > 0 ? `...${lines + hidden} more reps: pass page=${d.page + 1}` : `...${lines} more reps not shown`,
+    });
+}
+export async function runRoleplayRepSessions(opts, deps = {}) {
+    try {
+        const { instanceId, scope } = checkCommon(opts);
+        if (!opts.assignmentId)
+            throw createCliError('VALIDATION', 'assignmentId is required');
+        if (!opts.userId)
+            throw createCliError('VALIDATION', 'userId is required');
+        const model = await loadTeamModel(clientFor(opts, deps), instanceId, scope);
+        const a = model.assignments.find((x) => x.id === opts.assignmentId);
+        if (!a || !(a.resolvedUserIds ?? []).includes(opts.userId)) {
+            throw createCliError('NOT_FOUND', `No rep ${opts.userId} on assignment ${opts.assignmentId} in this scope`);
+        }
+        const m = deriveAssignment(model, a, new Date());
+        const rep = m.reps.find((r) => r.userId === opts.userId);
+        const own = m.own
+            .filter((s) => s.userId === opts.userId)
+            .sort((x, y) => new Date(y.timestamp ?? 0).getTime() - new Date(x.timestamp ?? 0).getTime());
+        const sessions = own.slice(0, REP_SESSIONS_MAX).map((s) => {
+            const score = sessionScore(s);
+            return {
+                id: String(s.id),
+                timestamp: s.timestamp ?? null,
+                score,
+                durationMs: finiteOrNull(s.durationMs),
+                evaluationStatus: typeof s.evaluationStatus === 'string' ? s.evaluationStatus : null,
+                meetsPassingScore: score === null ? null : score >= a.passingScore,
+            };
+        });
+        const latest = latestSkills(own);
+        return ok(fitRepSessions({
+            ...scoped('rep-sessions', instanceId, model),
+            assignmentId: a.id,
+            scenarioName: a.scenarioName ?? null,
+            passingScore: a.passingScore,
+            rep,
+            latestSkills: latest
+                ? { sessionId: String(latest.session.id), timestamp: latest.session.timestamp ?? null, skills: latest.skills }
+                : null,
+            sessions,
+            totalSessions: own.length,
+        }), model.warnings);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function repSessionsText(raw) {
+    const d = raw;
+    const r = d.rep;
+    const head1 = `${name60(r.name, 'Rep')} on ${name60(d.scenarioName, d.assignmentId)}: ${STATUS_TEXT[r.status]}, ` +
+        `${r.bestScore === null ? 'no best score' : `best ${fmtNum(r.bestScore)}`} of pass ${fmtNum(d.passingScore)}, ${r.sessions} sessions. ` +
+        'Lines: date time (UTC) score entryId; open one with pitcher_roleplay_session_get.';
+    const skills = (d.latestSkills?.skills ?? []).slice(0, 8).map((k) => `${clipBytes(k.title, 30)} ${fmtNum(k.score)}`);
+    let head2 = '';
+    for (let n = skills.length; n > 0; n -= 1) {
+        const t = `Latest skills: ${skills.slice(0, n).join(', ')}.`;
+        if (byteLen(t) <= 450) {
+            head2 = t;
+            break;
+        }
+    }
+    return roleplayFitText({
+        heads: [
+            { text: head1, maxBytes: 450 },
+            { text: head2, maxBytes: 450 },
+        ],
+        body: d.sessions.map((s) => ({ text: `${fmtUtc(s.timestamp)} ${scoreToken(s.score, null)} ${s.id}` })),
+        hidden: Math.max(0, d.totalSessions - d.sessions.length),
+        more: ({ lines, hidden }) => `...${lines + hidden} older sessions not listed`,
+    });
+}
+/** session_get, fitted and tagged for the view (D4). */
+export function fitScorecardEnvelope(env) {
+    if (!env.ok)
+        return env;
+    return { ...env, data: fitScorecard({ ...env.data, kind: 'scorecard' }) };
+}
+export const runRoleplaySessionScorecard = (opts, deps = {}) => runRoleplaySessionGet(opts, deps).then(fitScorecardEnvelope);
+export function scorecardText(raw) {
+    const d = raw;
+    const ev = d.evaluation;
+    // The overall score is out of 100 on every evaluation; grading_scale is the category scale (legacy: 5).
+    const score = d.overall_score === null ? 'unscored' : `score ${scoreToken(d.overall_score, null).replace('/', ' / ')}`;
+    const head = `Session ${d.id}, ${name60(d.scenario_name, 'roleplay')}, ${d.timestamp ? fmtUtc(d.timestamp).slice(0, 10) : 'unknown date'}: ${score}.`;
+    const body = [];
+    if (ev?.summary)
+        body.push({ text: clipBytes(`Summary: ${ev.summary}`, 900), kind: 'summary' });
+    const list = (label, items) => clipBytes(`${label}: ${items.map((s) => clipBytes(String(s), 200)).join('; ')}`, 1000);
+    if (ev?.strengths.length)
+        body.push({ text: list('Strengths', ev.strengths), kind: 'strengths' });
+    if (ev?.improvements.length)
+        body.push({ text: list('Improvements', ev.improvements), kind: 'improvements' });
+    for (const c of ev?.category_scores ?? []) {
+        const title = clipBytes(c.title || c.skill_id || 'Skill', 30);
+        const s = c.score === null ? 'unscored' : `${fmtNum(normalizeScore(c.score, c.max_score ?? ev?.grading_scale ?? 100))}/100`;
+        body.push({ text: `${title} ${s}${c.feedback ? `: ${clipBytes(c.feedback, 200)}` : ''}`, kind: 'skill' });
+    }
+    return roleplayFitText({
+        // fitScorecard's notice rides as a head: skills it dropped never reach `body`, so `more` cannot count them
+        heads: [
+            { text: head, maxBytes: 300 },
+            { text: d.truncated ? `${d.truncated}.` : '', maxBytes: 120 },
+        ],
+        body,
+        more: ({ lines, kinds }) => kinds.length === 1 && kinds[0] === 'skill' ? `...${lines} skills not shown` : `...${lines} lines not shown (${kinds.join(', ')})`,
+    });
+}
+// ── tools ────────────────────────────────────────────────────────────────────
+export const instanceId = z.string().describe('Instance ID (required)');
+export const statusEnum = z.enum(['passed', 'in_progress', 'not_started', 'overdue', 'needs_coaching']);
+export const scopeEnum = z.enum(['instance', 'coach']);
+const VIEW = 'roleplay-manager';
+export const roleplayManagerTools = [
+    {
+        name: 'pitcher_roleplay_manager_view',
+        title: 'AI Roleplay team view (interactive)',
+        description: 'Interactive AI Roleplay team view for a coaching manager or admin: KPI header, every roleplay assignment with how ' +
+            'many reps passed, are in progress, not started, overdue or need coaching, drill-downs into reps and session ' +
+            'scorecards, and a Reps tab listing each rep once across their assignments (pitcher_roleplay_reps). ' +
+            'In hosts without UI it returns a text summary. Admins see every assignment on the instance, a manager ' +
+            'the assignments they coach. For a plain data answer use pitcher_roleplay_team.',
+        inputShape: {
+            instanceId,
+            assignmentId: z.string().optional().describe('Open this assignment directly (its id from an earlier call)'),
+            status: statusEnum.optional().describe('Preselect the rep status filter of that assignment'),
+            scope: scopeEnum.optional().describe('Omit unless the user asks only for the assignments they coach (then "coach")'),
+        },
+        run: runRoleplayManagerView,
+        toText: managerViewText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'roleplay',
+        ui: { view: VIEW },
+    },
+    {
+        name: 'pitcher_roleplay_assignment_reps',
+        title: 'Assignment reps (roleplay view UI helper)',
+        description: 'UI helper for the roleplay team view: one page of reps for one assignment, with status, best score and sessions. ' +
+            'For a plain data answer prefer pitcher_roleplay_team.',
+        inputShape: {
+            instanceId,
+            assignmentId: z.string().describe('Assignment ID'),
+            status: statusEnum.optional().describe('Only reps with this status'),
+            page: z.number().int().min(1).optional().describe('1-based, 25 reps a page'),
+            scope: scopeEnum.optional().describe('The scope of the view result this drill comes from'),
+        },
+        run: runRoleplayAssignmentReps,
+        toText: assignmentRepsText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'roleplay',
+        ui: { view: VIEW, visibility: ['app'] },
+    },
+    {
+        name: 'pitcher_roleplay_rep_sessions',
+        title: 'AI Roleplay sessions of one rep',
+        description: "One rep's AI Roleplay sessions on one assignment, newest first, with each session's entry id for " +
+            "pitcher_roleplay_session_get, plus the rep's latest skill scores. Works for the rep's coach and for instance or " +
+            'org admins. Take userId and assignmentId from pitcher_roleplay_team. In hosts with UI it opens the roleplay team ' +
+            'view on that rep.',
+        inputShape: {
+            instanceId,
+            assignmentId: z.string().describe('Assignment ID (from pitcher_roleplay_team)'),
+            userId: z.string().describe('Rep user ID (user_id from pitcher_roleplay_team)'),
+            scope: scopeEnum.optional().describe('Omit unless the user asks only for the assignments they coach (then "coach")'),
+        },
+        run: runRoleplayRepSessions,
+        toText: repSessionsText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'roleplay',
+        ui: { view: VIEW, visibility: ['model', 'app'] },
+    },
+    {
+        name: 'pitcher_roleplay_session_scorecard',
+        title: 'Session scorecard (roleplay view UI helper)',
+        description: "UI helper for the roleplay team view: one session's scorecard (score, summary, strengths, improvements, per-skill " +
+            'scores and feedback). Never the transcript. Same access as pitcher_roleplay_session_get.',
+        inputShape: {
+            instanceId,
+            entryId: z.string().describe('Session entry ID'),
+        },
+        run: runRoleplaySessionScorecard,
+        wraps: runRoleplaySessionGet,
+        toText: scorecardText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'roleplay',
+        ui: { view: VIEW, visibility: ['app'] },
+    },
+];