@pitcher/cli-scripts 3.2.0 → 3.3.0

package/dist/src/mcp/apps/roleplayReps.d.ts

@@ -0,0 +1,79 @@
+import { type Envelope } from '../../core/envelope.js';
+import { type LatestSkill, type RepStatus } from '../../core/roleplay-stats.js';
+import type { ToolDescriptor } from '../tools/types.js';
+import { type AssignmentModel, type Deps, type ScopedResult, type StatusCounts, type ViewOpts } from './roleplayManager.js';
+/**
+ * PIT-10116: the Reps tab of the roleplay manager view. Each rep once, across all of their scoped assignments,
+ * aggregated from the SAME per-(assignment, rep) rows the Assignment panel shows (`deriveAssignment`), so the two
+ * never disagree. Read-only; no rule here decides a status, a session count or a score.
+ */
+export declare const REPS_LIST_PAGE_SIZE = 25;
+export declare const REP_ASSIGNMENTS_MAX = 200;
+/** fitRepAssignments dropped skills to fit: the Skills list is not the whole latest evaluation. */
+export declare const SKILLS_OMITTED = "Some skills were left out to fit";
+/** One rep across all of their scoped assignments. */
+export interface RepSummaryRow {
+    userId: string;
+    name: string | null;
+    status: RepStatus;
+    assignments: number;
+    passed: number;
+    sessions: number;
+    bestScore: number | null;
+    lastSessionAt: string | null;
+    recentOnly: boolean;
+}
+export interface RepsPageData extends ScopedResult<'reps'> {
+    generatedAt: string;
+    status: RepStatus | null;
+    page: number;
+    pageSize: number;
+    totalReps: number;
+    filteredReps: number;
+    statusCounts: StatusCounts;
+    hasMore: boolean;
+    reps: RepSummaryRow[];
+    canViewInstance: boolean | null;
+}
+export interface RepAssignmentRow {
+    assignmentId: string;
+    scenarioName: string | null;
+    type: string;
+    passingScore: number;
+    dueDate: string | null;
+    active: boolean;
+    status: RepStatus;
+    sessions: number;
+    bestScore: number | null;
+    avgScore: number | null;
+    lastSessionAt: string | null;
+    recentOnly: boolean;
+}
+export interface RepAssignmentsData extends ScopedResult<'rep-assignments'> {
+    rep: RepSummaryRow;
+    status: RepStatus | null;
+    assignments: RepAssignmentRow[];
+    totalAssignments: number;
+    latestSkills: {
+        sessionId: string;
+        timestamp: string | null;
+        skills: LatestSkill[];
+    } | null;
+    canViewInstance: boolean | null;
+    truncated?: string;
+}
+/** Pair rows (`deriveAssignment` per scoped assignment, in D18 order) to one row per user id, most urgent first. */
+export declare function aggregateReps(models: AssignmentModel[]): RepSummaryRow[];
+/** Rows are never dropped (paging continues after them): names are clipped instead, to 200 then 60 characters. */
+export declare function fitRepsPage(data: RepsPageData, max?: number): RepsPageData;
+/** Names (rep, scenarios, skills) to 200 then 60 characters; then skills from the end; then rows, stated. */
+export declare function fitRepAssignments(data: RepAssignmentsData, max?: number): RepAssignmentsData;
+export declare function runRoleplayReps(opts: ViewOpts, deps?: Deps): Promise<Envelope<RepsPageData>>;
+export declare function runRoleplayRepAssignments(opts: ViewOpts, deps?: Deps): Promise<Envelope<RepAssignmentsData>>;
+/** "62", "none", or the whole token "invalid" outside 0..9999. */
+export declare const bestToken: (x: number | null) => string;
+/** A list line, at most 137 B for user ids up to 20 bytes (spec 7.3 item 1.3). */
+export declare const repLine: (r: RepSummaryRow) => string;
+export declare function repsText(raw: unknown): string;
+export declare function repAssignmentsText(raw: unknown): string;
+export declare const roleplayRepsTools: ToolDescriptor[];

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

@@ -0,0 +1,328 @@
+import { z } from 'zod';
+import { compareReps, finiteOrNull, loadTeamModel, 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 } from '../../core/roleplay-stats.js';
+import { cappedSentence, checkCommon, clipChars, deriveAssignment, emptyCounts, fmtNum, fmtUtc, inRange, instanceId, name60, NAME_CHARS, ROLEPLAY_VIEW_MAX_BYTES, roleplayFitText, scoped, scopeEnum, STATUS_TEXT, statusEnum, } from './roleplayManager.js';
+import { byteLen, clipBytes, jsonBytes } from './text.js';
+/**
+ * PIT-10116: the Reps tab of the roleplay manager view. Each rep once, across all of their scoped assignments,
+ * aggregated from the SAME per-(assignment, rep) rows the Assignment panel shows (`deriveAssignment`), so the two
+ * never disagree. Read-only; no rule here decides a status, a session count or a score.
+ */
+export const REPS_LIST_PAGE_SIZE = 25;
+export const REP_ASSIGNMENTS_MAX = 200;
+/** fitRepAssignments dropped skills to fit: the Skills list is not the whole latest evaluation. */
+export const SKILLS_OMITTED = 'Some skills were left out to fit';
+// ── aggregation ──────────────────────────────────────────────────────────────
+const timeOf = (iso) => {
+    if (!iso)
+        return null;
+    const t = Date.parse(iso);
+    return Number.isNaN(t) ? null : t;
+};
+/** The later of two timestamps by instant; an unparseable value never wins over a parseable one. */
+function laterOf(a, b) {
+    const ta = timeOf(a);
+    const tb = timeOf(b);
+    if (tb === null)
+        return a ?? b;
+    if (ta === null)
+        return b;
+    return tb > ta ? b : a;
+}
+/** Pair rows (`deriveAssignment` per scoped assignment, in D18 order) to one row per user id, most urgent first. */
+export function aggregateReps(models) {
+    const byId = new Map();
+    for (const m of models) {
+        for (const r of m.reps) {
+            const cur = byId.get(r.userId);
+            if (!cur) {
+                byId.set(r.userId, {
+                    userId: r.userId,
+                    name: r.name,
+                    status: r.status,
+                    assignments: 1,
+                    passed: r.status === 'passed' ? 1 : 0,
+                    sessions: r.sessions,
+                    bestScore: finiteOrNull(r.bestScore),
+                    lastSessionAt: r.lastSessionAt,
+                    recentOnly: r.recentOnly,
+                });
+                continue;
+            }
+            cur.name ?? (cur.name = r.name);
+            if (STATUS_RANK[r.status] < STATUS_RANK[cur.status])
+                cur.status = r.status;
+            cur.assignments += 1;
+            if (r.status === 'passed')
+                cur.passed += 1;
+            cur.sessions += r.sessions;
+            const best = finiteOrNull(r.bestScore);
+            if (best !== null && (cur.bestScore === null || best > cur.bestScore))
+                cur.bestScore = best;
+            cur.lastSessionAt = laterOf(cur.lastSessionAt, r.lastSessionAt);
+            cur.recentOnly || (cur.recentOnly = r.recentOnly);
+        }
+    }
+    return Array.from(byId.values()).sort((a, b) => compareReps({ status: a.status, name: a.name, user_id: a.userId }, { status: b.status, name: b.name, user_id: b.userId }));
+}
+const canViewInstanceOf = (scope, model) => scope === 'coach' ? null : model.scope === 'instance';
+// ── fitting ──────────────────────────────────────────────────────────────────
+/** Rows are never dropped (paging continues after them): names are clipped instead, to 200 then 60 characters. */
+export function fitRepsPage(data, max = ROLEPLAY_VIEW_MAX_BYTES) {
+    let out = data;
+    for (const n of [NAME_CHARS, 60]) {
+        if (jsonBytes(out) <= max)
+            return out;
+        out = { ...out, reps: out.reps.map((r) => ({ ...r, name: r.name === null ? null : clipChars(r.name, n) })) };
+    }
+    return out;
+}
+/** Names (rep, scenarios, skills) to 200 then 60 characters; then skills from the end; then rows, stated. */
+export function fitRepAssignments(data, max = ROLEPLAY_VIEW_MAX_BYTES) {
+    let out = data;
+    for (const n of [NAME_CHARS, 60]) {
+        if (jsonBytes(out) <= max)
+            return out;
+        out = {
+            ...out,
+            rep: { ...out.rep, name: out.rep.name === null ? null : clipChars(out.rep.name, n) },
+            assignments: out.assignments.map((a) => ({ ...a, scenarioName: a.scenarioName === null ? null : clipChars(a.scenarioName, n) })),
+            latestSkills: out.latestSkills && {
+                ...out.latestSkills,
+                skills: out.latestSkills.skills.map((k) => ({ ...k, title: clipChars(k.title, n), skillId: clipChars(k.skillId, n) })),
+            },
+        };
+    }
+    // Dropped skills are stated, as fitScorecard does: the remaining ones are not the whole latest evaluation.
+    const skillsBefore = out.latestSkills?.skills.length ?? 0;
+    const skillsNote = (o) => ((o.latestSkills?.skills.length ?? 0) < skillsBefore ? SKILLS_OMITTED : null);
+    while (out.latestSkills?.skills.length && jsonBytes({ ...out, truncated: SKILLS_OMITTED }) > max) {
+        out = { ...out, latestSkills: { ...out.latestSkills, skills: out.latestSkills.skills.slice(0, -1) } };
+    }
+    const noted = (rows) => {
+        const { truncated: _old, ...rest } = out;
+        const notes = [rows.length < data.totalAssignments ? `Showing ${rows.length} of ${data.totalAssignments} assignments` : null, skillsNote(out)];
+        const truncated = notes.filter(Boolean).join('; ');
+        return truncated ? { ...rest, assignments: rows, truncated } : { ...rest, assignments: rows };
+    };
+    let rows = out.assignments;
+    while (rows.length && jsonBytes(noted(rows)) > max)
+        rows = rows.slice(0, -1);
+    return noted(rows);
+}
+// ── runners ──────────────────────────────────────────────────────────────────
+export async function runRoleplayReps(opts, deps = {}) {
+    try {
+        const { instanceId: iid, scope, status } = checkCommon(opts);
+        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), iid, scope);
+        const now = new Date();
+        const all = aggregateReps(model.assignments.map((a) => deriveAssignment(model, a, now)));
+        const statusCounts = emptyCounts();
+        for (const r of all)
+            statusCounts[r.status] += 1;
+        const filtered = status ? all.filter((r) => r.status === status) : all;
+        const start = (page - 1) * REPS_LIST_PAGE_SIZE;
+        const reps = filtered.slice(start, start + REPS_LIST_PAGE_SIZE);
+        return ok(fitRepsPage({
+            ...scoped('reps', iid, model),
+            generatedAt: now.toISOString(),
+            status,
+            page,
+            pageSize: REPS_LIST_PAGE_SIZE,
+            totalReps: all.length,
+            filteredReps: filtered.length,
+            statusCounts,
+            hasMore: start + reps.length < filtered.length,
+            reps,
+            canViewInstance: canViewInstanceOf(scope, model),
+        }), model.warnings);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runRoleplayRepAssignments(opts, deps = {}) {
+    try {
+        const { instanceId: iid, scope, status } = checkCommon(opts);
+        if (!opts.userId)
+            throw createCliError('VALIDATION', 'userId is required');
+        const userId = opts.userId;
+        const model = await loadTeamModel(clientFor(opts, deps), iid, scope);
+        const now = new Date();
+        const mine = model.assignments.filter((a) => (a.resolvedUserIds ?? []).includes(userId));
+        if (mine.length === 0) {
+            throw createCliError('NOT_FOUND', `No rep ${userId} on roleplay assignments in this ${model.scope === 'instance' ? 'instance' : 'coaching scope'}`);
+        }
+        const models = mine.map((a) => deriveAssignment(model, a, now));
+        // Only this rep's pairs: the models also hold every other rep on these assignments.
+        const rep = aggregateReps(models.map((m) => ({ ...m, reps: m.reps.filter((x) => x.userId === userId) })))[0];
+        const rows = models
+            .map((m, pos) => ({ m, pos, r: m.reps.find((x) => x.userId === userId) }))
+            .sort((x, y) => STATUS_RANK[x.r.status] - STATUS_RANK[y.r.status] || x.pos - y.pos)
+            .map(({ m, r }) => ({
+            assignmentId: m.assignment.id,
+            scenarioName: m.assignment.scenarioName ?? null,
+            type: m.assignment.type,
+            passingScore: m.assignment.passingScore,
+            dueDate: m.assignment.dueDate ?? null,
+            active: m.assignment.active !== false,
+            status: r.status,
+            sessions: r.sessions,
+            bestScore: r.bestScore,
+            avgScore: r.avgScore,
+            lastSessionAt: r.lastSessionAt,
+            recentOnly: r.recentOnly,
+        }));
+        const shown = status ? rows.filter((r) => r.status === status) : rows;
+        // T12: the newest evaluated session among the rep's sessions on THEIR scoped assignments only.
+        const own = mine.flatMap((a) => assignmentSessions(model.sessions, a)).filter((s) => s.userId === userId);
+        const latest = latestSkills(own);
+        const capped = shown.slice(0, REP_ASSIGNMENTS_MAX);
+        return ok(fitRepAssignments({
+            ...scoped('rep-assignments', iid, model),
+            rep,
+            status,
+            assignments: capped,
+            totalAssignments: shown.length,
+            latestSkills: latest
+                ? { sessionId: String(latest.session.id), timestamp: latest.session.timestamp ?? null, skills: latest.skills }
+                : null,
+            canViewInstance: canViewInstanceOf(scope, model),
+            ...(capped.length < shown.length ? { truncated: `Showing ${capped.length} of ${shown.length} assignments` } : {}),
+        }), model.warnings);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+// ── text (spec 7.3) ──────────────────────────────────────────────────────────
+/** "62", "none", or the whole token "invalid" outside 0..9999. */
+export const bestToken = (x) => (x === null ? 'none' : inRange(x) ? fmtNum(x) : 'invalid');
+const dateToken = (ts) => (ts && timeOf(ts) !== null ? fmtUtc(ts).slice(0, 10) : 'none');
+const scopeText = (d) => d.scope === 'coach' ? 'coach scope; counts cover assignments you coach only' : 'instance scope';
+/** A list line, at most 137 B for user ids up to 20 bytes (spec 7.3 item 1.3). */
+export const repLine = (r) => `${clipBytes(r.name || 'Rep', 32)} (${r.userId}): ${STATUS_TEXT[r.status]}, ${r.passed}/${r.assignments} passed, ` +
+    `best ${bestToken(r.bestScore)}, ${r.sessions} sessions, last ${dateToken(r.lastSessionAt)}`;
+export function repsText(raw) {
+    const d = raw;
+    const c = d.statusCounts;
+    const first = (d.page - 1) * d.pageSize + 1;
+    const range = d.reps.length ? `Reps ${first}-${first + d.reps.length - 1} of ${d.filteredReps}` : `No reps of ${d.filteredReps}`;
+    const head1 = `AI Roleplay reps (${scopeText(d)}): ${d.totalReps} reps; ${c.overdue} overdue, ${c.needs_coaching} needs coaching, ` +
+        `${c.in_progress} in progress, ${c.not_started} not started, ${c.passed} all passed. ` +
+        `${range} (status: ${d.status ? STATUS_TEXT[d.status] : 'all'}), most urgent first. ` +
+        'Line: name (userId): status, passed/assignments, best, sessions summed over assignments, last session (UTC).';
+    const hidden = Math.max(0, d.filteredReps - (first - 1) - d.reps.length);
+    return roleplayFitText({
+        heads: [
+            { text: head1, maxBytes: 385 },
+            { text: d.complete ? '' : cappedSentence(d.coverage), maxBytes: 120 },
+        ],
+        body: d.reps.map((r) => ({ text: repLine(r) })),
+        hidden,
+        more: ({ lines, hidden: h }) => lines > 0
+            ? `...${lines + h} more reps; this page was shortened, ask with a status filter`
+            : `...${h} more reps: pass page=${d.page + 1}${d.status ? ` with status=${d.status}` : ''}${d.scope === 'coach' ? ' and scope=coach' : ''}`,
+    });
+}
+const STATUS_ORDER = ['overdue', 'needs_coaching', 'in_progress', 'not_started', 'passed'];
+export function repAssignmentsText(raw) {
+    const d = raw;
+    const r = d.rep;
+    const head1 = `${name60(r.name, 'Rep')} (${r.userId}): ${r.passed} of ${r.assignments} assignments passed` +
+        `${d.scope === 'coach' ? ' (coach scope: assignments you coach only)' : ''}, most urgent ${STATUS_TEXT[r.status]}, ` +
+        `${r.sessions} sessions across assignments, best ${bestToken(r.bestScore)}, last ${dateToken(r.lastSessionAt)}` +
+        `${d.status ? `; listing status ${STATUS_TEXT[d.status]} only` : ''}. ` +
+        (d.status && d.assignments.length === 0
+            ? `No assignment of this rep has status ${STATUS_TEXT[d.status]}.`
+            : 'Lines: assignmentId scenario: status, best of pass, sessions, last (UTC); open one with pitcher_roleplay_rep_sessions.');
+    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;
+        }
+    }
+    const body = d.assignments.map((a) => ({
+        kind: a.status,
+        text: `${a.assignmentId} ${clipBytes(a.scenarioName || a.assignmentId, 40)}: ${STATUS_TEXT[a.status]}, best ${bestToken(a.bestScore)} ` +
+            `of pass ${bestToken(a.passingScore)}, ${a.sessions} sessions, last ${dateToken(a.lastSessionAt)}` +
+            `${a.dueDate ? `, due ${a.dueDate.slice(0, 10)}` : ''}${a.active ? '' : ', paused'}`,
+    }));
+    const hidden = Math.max(0, d.totalAssignments - d.assignments.length);
+    // Rows are in rank order, so hidden rows can only have the last sent row's status or a later one.
+    const last = d.assignments[d.assignments.length - 1]?.status;
+    const hiddenStatuses = hidden > 0 ? STATUS_ORDER.filter((s) => !last || STATUS_RANK[s] >= STATUS_RANK[last]) : [];
+    return roleplayFitText({
+        heads: [
+            { text: head1, maxBytes: 450 },
+            { text: head2, maxBytes: 450 },
+            { text: d.complete ? '' : cappedSentence(d.coverage), maxBytes: 200 },
+            { text: d.truncated ? `${d.truncated}.` : '', maxBytes: 120 },
+        ],
+        body,
+        hidden,
+        more: ({ lines, hidden: h, kinds }) => {
+            // Filtered: every row left out has that status, so no other call reaches them (spec 7.3 item 2.5, stated limit).
+            if (d.status)
+                return `...${lines + h} more with status ${d.status} not listed`;
+            const left = STATUS_ORDER.filter((s) => kinds.includes(s) || hiddenStatuses.includes(s));
+            return `...${lines + h} more (least urgent): call with status=${left.join('|')}`;
+        },
+    });
+}
+// ── tools ────────────────────────────────────────────────────────────────────
+const VIEW = 'roleplay-manager';
+export const roleplayRepsTools = [
+    {
+        name: 'pitcher_roleplay_reps',
+        title: 'AI Roleplay reps (interactive)',
+        description: 'Each rep in the AI Roleplay team view, once, across all of their roleplay assignments: assignments passed (x of y), ' +
+            'the most urgent status across those assignments, sessions summed across those assignments (a session can count ' +
+            'toward two), best score and last session, most urgent first, ' +
+            '25 reps a page with a status filter. Admins see every rep on an instance assignment; a coaching manager the reps ' +
+            'on the assignments they coach, with only those assignments counted. In hosts with UI it opens the roleplay team ' +
+            "view on its Reps tab. For one rep's assignments use pitcher_roleplay_rep_assignments with the userId.",
+        inputShape: {
+            instanceId,
+            status: statusEnum.optional().describe('Only reps whose most urgent status is this'),
+            page: z.number().int().min(1).optional().describe('1-based, 25 reps a page'),
+            scope: scopeEnum.optional().describe('Omit unless the user asks only for the reps they coach (then "coach")'),
+        },
+        run: runRoleplayReps,
+        toText: repsText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'roleplay',
+        ui: { view: VIEW },
+    },
+    {
+        name: 'pitcher_roleplay_rep_assignments',
+        title: 'AI Roleplay assignments of one rep',
+        description: "One rep's AI Roleplay assignments in the team view: per assignment its status, best score, sessions and last " +
+            "session, most urgent first, plus the rep's latest skill scores. Works for the rep's coach (only the assignments " +
+            'they coach) and for instance or org admins. Take userId from pitcher_roleplay_reps or pitcher_roleplay_team. For ' +
+            'the sessions of one assignment use pitcher_roleplay_rep_sessions. In hosts with UI it opens the roleplay team view ' +
+            'on that rep.',
+        inputShape: {
+            instanceId,
+            userId: z.string().describe('Rep user ID (userId from pitcher_roleplay_reps or user_id from pitcher_roleplay_team)'),
+            status: statusEnum.optional().describe("Only this rep's assignments with this status"),
+            scope: scopeEnum.optional().describe('Omit unless the user asks only for the reps they coach (then "coach")'),
+        },
+        run: runRoleplayRepAssignments,
+        toText: repAssignmentsText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'roleplay',
+        ui: { view: VIEW },
+    },
+];

package/dist/src/mcp/apps/roleplayWrites.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDescriptor } from '../tools/types.js';
+export declare const commentPropose: ToolDescriptor, commentCommit: ToolDescriptor;
+export declare const commentDeletePropose: ToolDescriptor, commentDeleteCommit: ToolDescriptor;
+export declare const pathPropose: ToolDescriptor, pathCommit: ToolDescriptor;
+/** The six confirm tools (PIT-10113), registered in `apps/registry.ts` with the write-confirm view. */
+export declare const roleplayWriteTools: ToolDescriptor[];