@pitcher/cli-scripts 3.1.1 → 3.3.0

package/dist/src/core/dsr-visits.js

@@ -0,0 +1,191 @@
+/**
+ * One DSR viewer's event timeline (`/analytics/canvas-details/sessions`) → visits, and per visit the
+ * sections, files and pages viewed with their time (PIT-9589). The visit rule is the Sharing
+ * Analytics app's (`packages/apps/canvas-analytics/src/lib/reconstructSessions.ts`): a visit opens
+ * on an `Entered` of the canvas itself and is keyed by its `event_pair_id`; its engaged time is the
+ * sum of its focus segments (canvas Entered → Exited). Change them together.
+ *
+ * Item time: the sum of the item's `Exited` durations (`forhowlong`, seconds) in the visit. An
+ * `Entered` with no `Exited` (the unload beacon was dropped, PIT-5833) or an `Exited` reporting 0 is
+ * estimated from the gap to the next event of the visit, as the app's timeline does, and flagged
+ * `estimated`.
+ */
+const ITEM_TYPES = { Section: 'section', File: 'file', Page: 'page' };
+// The page index is the LAST path segment, `<fileId>/page/<n>` or the older `<fileId>/<n>`, 0-based.
+const PAGE_INDEX_SUFFIX = /\/(?:page\/)?(\d+)$/;
+const ms = (ts) => new Date(ts).getTime();
+const seconds = (from, to) => Math.max(0, Math.round((ms(to) - ms(from)) / 1000));
+function sortPriority(e, anchorId) {
+    const isAnchor = e.entity_id === anchorId;
+    if (!isAnchor && e.action === 'Exited')
+        return 1;
+    if (isAnchor && e.action === 'Exited')
+        return 2;
+    if (isAnchor && e.action === 'Entered')
+        return 3;
+    if (!isAnchor && e.action === 'Entered')
+        return 4;
+    return 5;
+}
+/** `reconstructSessions`' grouping: events from an anchor `Entered` until the next one, by pair key. */
+export function groupVisits(events, anchorId) {
+    const sorted = [...events].sort((a, b) => a.timestamp.localeCompare(b.timestamp) || sortPriority(a, anchorId) - sortPriority(b, anchorId));
+    const groups = new Map();
+    let key = null;
+    let legacy = 0;
+    for (const e of sorted) {
+        if (e.entity_id === anchorId && e.action === 'Entered') {
+            key = e.event_pair_id ? `pair:${e.event_pair_id}` : `legacy:${++legacy}`;
+        }
+        if (!key)
+            continue;
+        const g = groups.get(key);
+        if (g)
+            g.push(e);
+        else
+            groups.set(key, [e]);
+    }
+    return Array.from(groups.values()).filter((g) => g.length > 0);
+}
+/** `computeEngagementDuration`: the wall-clock of each canvas focus segment, summed. */
+export function engagedSeconds(events, anchorId) {
+    let total = 0;
+    let start = null;
+    let last = null;
+    const flush = (end) => {
+        if (start && end)
+            total += seconds(start, end);
+        start = null;
+        last = null;
+    };
+    for (const e of events) {
+        if (e.entity_id === anchorId) {
+            if (e.action === 'Entered') {
+                flush(last);
+                start = e.timestamp;
+                last = e.timestamp;
+            }
+            else if (e.action === 'Exited') {
+                flush(e.timestamp);
+            }
+        }
+        else if (start) {
+            last = e.timestamp;
+        }
+    }
+    flush(last);
+    return total;
+}
+function itemsOf(events, anchorId) {
+    const items = new Map();
+    const open = new Map(); // entity → indexes of unmatched Entered
+    const item = (e) => {
+        const type = ITEM_TYPES[e.original_event_name];
+        if (!type || e.entity_id === anchorId)
+            return null;
+        let it = items.get(e.entity_id);
+        if (!it) {
+            const pageIdx = type === 'page' ? PAGE_INDEX_SUFFIX.exec(e.entity_id) : null;
+            it = {
+                type,
+                id: e.entity_id,
+                name: e.entity_name || e.entity_type || e.entity_id,
+                ...(pageIdx ? { page_number: Number(pageIdx[1]) + 1 } : {}),
+                views: 0,
+                seconds: 0,
+                estimated: false,
+            };
+            items.set(e.entity_id, it);
+        }
+        return it;
+    };
+    const gapToNext = (i) => (i + 1 < events.length ? seconds(events[i].timestamp, events[i + 1].timestamp) : 0);
+    events.forEach((e, i) => {
+        const it = item(e);
+        if (!it)
+            return;
+        if (e.action === 'Entered') {
+            it.views += 1;
+            open.set(e.entity_id, [...(open.get(e.entity_id) ?? []), i]);
+        }
+        else if (e.action === 'Exited') {
+            const pending = open.get(e.entity_id) ?? [];
+            const enteredAt = pending.shift();
+            open.set(e.entity_id, pending);
+            if (enteredAt === undefined)
+                it.views = Math.max(it.views, 1); // an Exited-only view (adblock): still a view
+            const reported = typeof e.duration === 'number' && e.duration > 0 ? e.duration : 0;
+            if (reported > 0) {
+                it.seconds += reported;
+            }
+            else if (enteredAt !== undefined) {
+                it.seconds += seconds(events[enteredAt].timestamp, e.timestamp);
+                it.estimated = true;
+            }
+        }
+    });
+    // Entered with no Exited in the visit: the gap to the next event.
+    for (const [id, pending] of open) {
+        const it = items.get(id);
+        for (const i of pending) {
+            it.seconds += gapToNext(i);
+            it.estimated = true;
+        }
+    }
+    return Array.from(items.values());
+}
+export function summarizeVisits(events, canvasId) {
+    return groupVisits(events, canvasId).map((g, i) => ({
+        visit: i + 1,
+        started_at: g[0].timestamp,
+        ended_at: g[g.length - 1].timestamp,
+        engaged_seconds: engagedSeconds(g, canvasId),
+        items: itemsOf(g, canvasId),
+    }));
+}
+/** RFC 4180 cell; a leading = + - @ is prefixed with ' so a spreadsheet never runs it as a formula. */
+export function csvCell(v) {
+    let s = v == null ? '' : String(v);
+    if (/^[=+\-@\t\r]/.test(s))
+        s = `'${s}`;
+    return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+export const VISITS_CSV_HEADER = [
+    'viewer',
+    'visit',
+    'visit_started_at',
+    'visit_engaged_seconds',
+    'item_type',
+    'item_name',
+    'page_number',
+    'item_id',
+    'views',
+    'seconds',
+    'estimated',
+];
+export function visitsToCsv(viewers) {
+    const lines = [VISITS_CSV_HEADER.join(',')];
+    for (const { viewer, visits } of viewers) {
+        for (const v of visits) {
+            const items = v.items.length ? v.items : [null];
+            for (const it of items) {
+                lines.push([
+                    viewer,
+                    v.visit,
+                    v.started_at,
+                    v.engaged_seconds,
+                    it?.type ?? '',
+                    it?.name ?? '',
+                    it?.page_number ?? '',
+                    it?.id ?? '',
+                    it?.views ?? '',
+                    it?.seconds ?? '',
+                    it ? String(it.estimated) : '',
+                ]
+                    .map(csvCell)
+                    .join(','));
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/src/core/envelope.d.ts

@@ -6,6 +6,7 @@ export interface Envelope<T> {
         code: ErrorCodeName;
         exitCode: number;
         message: string;
+        backendStatus?: number;
     };
     warnings?: string[];
 }

package/dist/src/core/envelope.js

@@ -4,7 +4,12 @@ export function ok(data, warnings) {
 export function fail(error, warnings) {
     return {
         ok: false,
-        error: { code: error.code, exitCode: error.exitCode, message: error.message },
+        error: {
+            code: error.code,
+            exitCode: error.exitCode,
+            message: error.message,
+            ...(error.backendStatus ? { backendStatus: error.backendStatus } : {}),
+        },
         ...(warnings?.length ? { warnings } : {}),
     };
 }

package/dist/src/core/errors.d.ts

@@ -13,6 +13,8 @@ export interface CliError {
     code: ErrorCodeName;
     exitCode: number;
     message: string;
+    /** HTTP status of the backend's error answer, when the failure came from a backend response (PIT-10114 audit). */
+    backendStatus?: number;
 }
-export declare function createCliError(code: ErrorCodeName, message: string): CliError;
+export declare function createCliError(code: ErrorCodeName, message: string, backendStatus?: number): CliError;
 export declare function isCliError(e: unknown): e is CliError;

package/dist/src/core/errors.js

@@ -7,8 +7,8 @@ export const ERROR_CODES = {
     NOT_FOUND: 5,
     CONFLICT: 6,
 };
-export function createCliError(code, message) {
-    return { __cliError: true, code, exitCode: ERROR_CODES[code], message };
+export function createCliError(code, message, backendStatus) {
+    return { __cliError: true, code, exitCode: ERROR_CODES[code], message, ...(backendStatus ? { backendStatus } : {}) };
 }
 export function isCliError(e) {
     if (typeof e !== 'object' || e === null)

package/dist/src/core/http.js

@@ -242,15 +242,17 @@ export function toCliError(e) {
     const apiMessage = extractApiMessage(data, err.message || 'Request failed');
     const status = err.response?.status;
     if (typeof status === 'number') {
+        // backendStatus: the backend answered (PIT-10114). A backend 4xx also maps to VALIDATION, so the code alone
+        // cannot tell a local check from a backend answer.
         if (status === 401 || status === 403)
-            return createCliError('AUTH', apiMessage);
+            return createCliError('AUTH', apiMessage, status);
         if (status === 404)
-            return createCliError('NOT_FOUND', apiMessage);
+            return createCliError('NOT_FOUND', apiMessage, status);
         if (status === 409)
-            return createCliError('CONFLICT', apiMessage);
+            return createCliError('CONFLICT', apiMessage, status);
         if (status >= 400 && status < 500)
-            return createCliError('VALIDATION', apiMessage);
-        return createCliError('NETWORK', apiMessage);
+            return createCliError('VALIDATION', apiMessage, status);
+        return createCliError('NETWORK', apiMessage, status);
     }
     if (err.isAxiosError)
         return createCliError('NETWORK', apiMessage);

package/dist/src/core/ld.js

@@ -423,7 +423,8 @@ export function toLdCliError(e) {
                     : s && s >= 400 && s < 500
                         ? 'VALIDATION'
                         : 'NETWORK';
-        return createCliError(code, msg);
+        // the L&D backend answered: keep its status for the PIT-10114 audit (`backendStatus`)
+        return createCliError(code, msg, typeof s === 'number' ? s : undefined);
     }
     return toCliError(e);
 }

package/dist/src/core/me.d.ts

@@ -0,0 +1,3 @@
+import type { AxiosInstance } from 'axios';
+/** The caller's Pitcher user id (Django `GET /api/v1/users/me/`), as a string. PIT-10113: the actor of a confirmed write. */
+export declare function getMeId(client: AxiosInstance): Promise<string>;

package/dist/src/core/me.js

@@ -0,0 +1,10 @@
+import { createCliError } from './errors.js';
+/** The caller's Pitcher user id (Django `GET /api/v1/users/me/`), as a string. PIT-10113: the actor of a confirmed write. */
+export async function getMeId(client) {
+    const res = await client.get('/api/v1/users/me/');
+    const id = res.data?.id;
+    const s = typeof id === 'number' ? String(id) : typeof id === 'string' ? id : '';
+    if (!/^[0-9]{1,9}$/.test(s))
+        throw createCliError('AUTH', 'could not read your Pitcher user id');
+    return s;
+}

package/dist/src/core/roleplay-stats.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The AI Roleplay manager-app's per-rep rules, ported 1:1 so the MCP team tool and the manager
+ * app give the same answer on the same data (PIT-9200). Sources, in ng-production-apps
+ * `pitcher-coach/manager-app/src/`: `lib/session-score.ts` (reading a score), `lib/stats.ts`
+ * (best, mean, trend, `normalizeScore`), `lib/status.ts` (`deriveStatus`),
+ * `hooks/useManagerData.ts` (`getAssignmentSessions`, `getRepStats`),
+ * `components/SkillBreakdown.tsx` (`latestSkills`) and `lib/api.ts` (`loadAssignmentProgress`,
+ * ported as `loadTeamModel` in `commands/roleplay.ts`). Since PIT-9971 status, session count, best
+ * score and last session come from the server's pass progress when it is known. Change them together.
+ *
+ * The one rule every aggregate here obeys: a session is unscored iff `overallScore` is not a
+ * finite number. An unscored session is never read as 0.
+ */
+export interface RoleplaySessionLike {
+    userId?: string;
+    scenarioId?: string;
+    timestamp?: string;
+    overallScore?: number | null;
+    durationMs?: number | null;
+    evaluation?: {
+        grading_scale?: number | string | null;
+        category_scores?: Array<{
+            id?: string;
+            skillId?: string;
+            title?: string;
+            score?: number;
+            max_score?: number | string | null;
+        }>;
+    } | null;
+}
+export interface RoleplayAssignmentLike {
+    scenarioId: string;
+    type: 'mandatory' | 'optional' | string;
+    passingScore: number;
+    dueDate: string | null;
+    createdAt: string;
+    resolvedUserIds: string[];
+}
+export type RepStatus = 'passed' | 'in_progress' | 'not_started' | 'overdue' | 'needs_coaching';
+/** next-core's pass progress for one (assignment, rep) pair over ALL its sessions (PIT-9971). */
+export interface AssignmentProgressLike {
+    passed: boolean;
+    passSource: 'stored' | 'live' | null;
+    attempts: number;
+    bestScore: number | null;
+    latestAt: string | null;
+}
+/** The session's score, or null when it has none (`toFiniteOrNull`). */
+export declare function sessionScore(session: RoleplaySessionLike): number | null;
+/** Mean of the finite values, rounded, or null when none are finite (`meanOfFinite`). */
+export declare function meanOfFinite(values: readonly (number | null | undefined)[]): number | null;
+/** Largest finite value, or null (`maxOfFinite`). */
+export declare function maxOfFinite(values: readonly (number | null | undefined)[]): number | null;
+/** Earliest-to-latest window delta over the scored entries only (`scoreTrend`). */
+export declare function scoreTrend(scores: readonly (number | null | undefined)[], windowFor: (scoredCount: number) => number): number | null;
+export declare const avgScore: (sessions: RoleplaySessionLike[]) => number | null;
+export declare const bestScore: (sessions: RoleplaySessionLike[]) => number | null;
+export declare const scoredCount: (sessions: RoleplaySessionLike[]) => number;
+/** Up to 3 sessions per end, capped at half the scored series (`calcTrend`). */
+export declare function calcTrend(sessions: RoleplaySessionLike[]): number | null;
+/**
+ * `deriveStatus`: the raw best score is compared with `passingScore` as stored, as the manager app
+ * does. `overallScore` is 0..100 on every evaluation, legacy ones included (their `grading_scale` of 5
+ * applies to the category scores only), so never normalise it here.
+ * With `progress`, passed and started come from the server; only `needs_coaching` (a judgement
+ * on the recent trend) reads the capped list. Without it, everything comes from the list.
+ */
+export declare function deriveStatus(sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date, progress?: AssignmentProgressLike | null): RepStatus;
+/** `getAssignmentSessions`: same scenario, a rep of the assignment, on or after it was created. */
+export declare function assignmentSessions<T extends RoleplaySessionLike>(sessions: T[], assignment: RoleplayAssignmentLike): T[];
+export interface RepStats {
+    user_id: string;
+    sessions: number;
+    scored_sessions: number;
+    best_score: number | null;
+    avg_score: number | null;
+    trend: number | null;
+    status: RepStatus;
+    last_session_at: string | null;
+    total_duration_ms: number;
+    /** Progress counts more attempts than the list holds: avg_score, scored_sessions and trend cover recent sessions only. */
+    recent_only: boolean;
+    pass_source: 'stored' | 'live' | null;
+}
+/**
+ * `getRepStats` for one rep of one assignment, without the raw sessions. With `progress`, sessions,
+ * best score and last session come from the server; average, scored count and trend stay on the list.
+ */
+export declare function repStats(userId: string, sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date, progress?: AssignmentProgressLike | null): RepStats;
+/** A grading scale: a finite positive number, or a string `Number()` turns into one; else null (D28). */
+export declare function scaleOrNull(v: unknown): number | null;
+/** `normalizeScore` (manager-app `lib/stats.ts`): a score on `max` as 0..100; no usable max = as is. */
+export declare function normalizeScore(score: number, max?: number | null): number;
+export interface LatestSkill {
+    skillId: string;
+    title: string;
+    score: number;
+}
+/**
+ * The Rep panel's skills (`SkillBreakdown`): the NEWEST session with at least one category score,
+ * scored or not, its categories normalised on `max_score ?? grading_scale ?? 100`, weakest first.
+ * Categories without a finite score are skipped; null when none remain. Never averaged across
+ * sessions, so 5-point and 100-point evaluations are never mixed.
+ */
+export declare function latestSkills<T extends RoleplaySessionLike>(sessions: T[]): {
+    session: T;
+    skills: LatestSkill[];
+} | null;
+export interface SkillAverage {
+    skill_id: string;
+    title: string;
+    avg_score: number | null;
+    scored_sessions: number;
+}
+/**
+ * Per-skill means over the sessions' `evaluation.category_scores`, keyed by `skillId` (the
+ * Skills Registry id). A legacy category without one falls back to its own `id`, which is stable
+ * within one scenario; an entry with neither, or with no finite score, is skipped.
+ */
+export declare function skillAverages(sessions: RoleplaySessionLike[]): SkillAverage[];

package/dist/src/core/roleplay-stats.js

@@ -0,0 +1,171 @@
+/**
+ * The AI Roleplay manager-app's per-rep rules, ported 1:1 so the MCP team tool and the manager
+ * app give the same answer on the same data (PIT-9200). Sources, in ng-production-apps
+ * `pitcher-coach/manager-app/src/`: `lib/session-score.ts` (reading a score), `lib/stats.ts`
+ * (best, mean, trend, `normalizeScore`), `lib/status.ts` (`deriveStatus`),
+ * `hooks/useManagerData.ts` (`getAssignmentSessions`, `getRepStats`),
+ * `components/SkillBreakdown.tsx` (`latestSkills`) and `lib/api.ts` (`loadAssignmentProgress`,
+ * ported as `loadTeamModel` in `commands/roleplay.ts`). Since PIT-9971 status, session count, best
+ * score and last session come from the server's pass progress when it is known. Change them together.
+ *
+ * The one rule every aggregate here obeys: a session is unscored iff `overallScore` is not a
+ * finite number. An unscored session is never read as 0.
+ */
+/** The session's score, or null when it has none (`toFiniteOrNull`). */
+export function sessionScore(session) {
+    const v = session.overallScore;
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+/** Mean of the finite values, rounded, or null when none are finite (`meanOfFinite`). */
+export function meanOfFinite(values) {
+    const finite = values.filter((n) => typeof n === 'number' && Number.isFinite(n));
+    if (finite.length === 0)
+        return null;
+    return Math.round(finite.reduce((a, b) => a + b, 0) / finite.length);
+}
+/** Largest finite value, or null (`maxOfFinite`). */
+export function maxOfFinite(values) {
+    const finite = values.filter((n) => typeof n === 'number' && Number.isFinite(n));
+    return finite.length === 0 ? null : Math.max(...finite);
+}
+/** Earliest-to-latest window delta over the scored entries only (`scoreTrend`). */
+export function scoreTrend(scores, windowFor) {
+    const finite = scores.filter((n) => typeof n === 'number' && Number.isFinite(n));
+    if (finite.length < 2)
+        return null;
+    const n = Math.min(windowFor(finite.length), finite.length);
+    if (n < 1)
+        return null;
+    const mean = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length;
+    return Math.round(mean(finite.slice(-n)) - mean(finite.slice(0, n)));
+}
+const byTimestamp = (a, b) => new Date(a.timestamp ?? 0).getTime() - new Date(b.timestamp ?? 0).getTime();
+export const avgScore = (sessions) => meanOfFinite(sessions.map(sessionScore));
+export const bestScore = (sessions) => maxOfFinite(sessions.map(sessionScore));
+export const scoredCount = (sessions) => sessions.filter((s) => sessionScore(s) !== null).length;
+/** Up to 3 sessions per end, capped at half the scored series (`calcTrend`). */
+export function calcTrend(sessions) {
+    const sorted = [...sessions].sort(byTimestamp);
+    return scoreTrend(sorted.map(sessionScore), (count) => Math.min(3, Math.floor(count / 2)));
+}
+/**
+ * `deriveStatus`: the raw best score is compared with `passingScore` as stored, as the manager app
+ * does. `overallScore` is 0..100 on every evaluation, legacy ones included (their `grading_scale` of 5
+ * applies to the category scores only), so never normalise it here.
+ * With `progress`, passed and started come from the server; only `needs_coaching` (a judgement
+ * on the recent trend) reads the capped list. Without it, everything comes from the list.
+ */
+export function deriveStatus(sessions, assignment, now = new Date(), progress) {
+    const isOverdue = assignment.type === 'mandatory' && !!assignment.dueDate && new Date(assignment.dueDate) < now;
+    if (progress) {
+        if (progress.passed)
+            return 'passed';
+        if (progress.attempts === 0)
+            return isOverdue ? 'overdue' : 'not_started';
+        if (isOverdue)
+            return 'overdue';
+        const trend = calcTrend(sessions);
+        if (scoredCount(sessions) >= 3 && trend != null && trend <= 0)
+            return 'needs_coaching';
+        return 'in_progress';
+    }
+    if (sessions.length === 0)
+        return isOverdue ? 'overdue' : 'not_started';
+    const best = bestScore(sessions);
+    if (best != null && best >= assignment.passingScore)
+        return 'passed';
+    if (isOverdue)
+        return 'overdue';
+    const trend = calcTrend(sessions);
+    if (scoredCount(sessions) >= 3 && trend != null && trend <= 0)
+        return 'needs_coaching';
+    return 'in_progress';
+}
+/** `getAssignmentSessions`: same scenario, a rep of the assignment, on or after it was created. */
+export function assignmentSessions(sessions, assignment) {
+    const createdAt = new Date(assignment.createdAt).getTime();
+    return sessions.filter((s) => s.scenarioId === assignment.scenarioId &&
+        typeof s.userId === 'string' &&
+        assignment.resolvedUserIds.includes(s.userId) &&
+        new Date(s.timestamp ?? 0).getTime() >= createdAt);
+}
+/**
+ * `getRepStats` for one rep of one assignment, without the raw sessions. With `progress`, sessions,
+ * best score and last session come from the server; average, scored count and trend stay on the list.
+ */
+export function repStats(userId, sessions, assignment, now = new Date(), progress) {
+    const own = sessions.filter((s) => s.userId === userId).sort(byTimestamp);
+    const lastListed = own.length > 0 ? (own[own.length - 1].timestamp ?? null) : null;
+    return {
+        user_id: userId,
+        sessions: progress ? progress.attempts : own.length,
+        scored_sessions: scoredCount(own),
+        best_score: progress ? progress.bestScore : bestScore(own),
+        avg_score: avgScore(own),
+        trend: calcTrend(own),
+        status: deriveStatus(own, assignment, now, progress),
+        last_session_at: progress ? progress.latestAt : lastListed,
+        total_duration_ms: own.reduce((sum, s) => sum + (s.durationMs ?? 0), 0),
+        recent_only: !!progress && progress.attempts > own.length,
+        pass_source: progress?.passSource ?? null,
+    };
+}
+/** A grading scale: a finite positive number, or a string `Number()` turns into one; else null (D28). */
+export function scaleOrNull(v) {
+    const n = typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : Number.NaN;
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+/** `normalizeScore` (manager-app `lib/stats.ts`): a score on `max` as 0..100; no usable max = as is. */
+export function normalizeScore(score, max) {
+    if (!max || max <= 0)
+        return score;
+    return Math.min(100, Math.round((score / max) * 100));
+}
+/**
+ * The Rep panel's skills (`SkillBreakdown`): the NEWEST session with at least one category score,
+ * scored or not, its categories normalised on `max_score ?? grading_scale ?? 100`, weakest first.
+ * Categories without a finite score are skipped; null when none remain. Never averaged across
+ * sessions, so 5-point and 100-point evaluations are never mixed.
+ */
+export function latestSkills(sessions) {
+    const session = [...sessions].sort((a, b) => byTimestamp(b, a)).find((s) => s.evaluation?.category_scores?.length);
+    if (!session)
+        return null;
+    const scale = scaleOrNull(session.evaluation?.grading_scale);
+    const skills = [];
+    for (const c of session.evaluation?.category_scores ?? []) {
+        const key = c.skillId || c.title;
+        if (!key || typeof c.score !== 'number' || !Number.isFinite(c.score))
+            continue;
+        skills.push({ skillId: key, title: c.title ?? key, score: normalizeScore(c.score, scaleOrNull(c.max_score) ?? scale ?? 100) });
+    }
+    if (skills.length === 0)
+        return null;
+    return { session, skills: skills.sort((a, b) => a.score - b.score) };
+}
+/**
+ * Per-skill means over the sessions' `evaluation.category_scores`, keyed by `skillId` (the
+ * Skills Registry id). A legacy category without one falls back to its own `id`, which is stable
+ * within one scenario; an entry with neither, or with no finite score, is skipped.
+ */
+export function skillAverages(sessions) {
+    const bySkill = new Map();
+    for (const s of sessions) {
+        if (sessionScore(s) === null)
+            continue;
+        for (const c of s.evaluation?.category_scores ?? []) {
+            const key = c.skillId || c.id;
+            if (!key || typeof c.score !== 'number' || !Number.isFinite(c.score))
+                continue;
+            const entry = bySkill.get(key) ?? { title: c.title ?? key, scores: [] };
+            entry.scores.push(c.score);
+            bySkill.set(key, entry);
+        }
+    }
+    return Array.from(bySkill.entries()).map(([skill_id, { title, scores }]) => ({
+        skill_id,
+        title,
+        avg_score: meanOfFinite(scores),
+        scored_sessions: scores.length,
+    }));
+}

package/dist/src/mcp/apps/confirm/define.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import type { ToolGroup } from '../../groups.js';
+import type { InjectedAuth, ToolDescriptor } from '../../tools/types.js';
+import { type CommitResult, type Proposal, type ProposalClaims, type ProposalPreview } from './types.js';
+export declare const WRITE_CONFIRM_VIEW = "write-confirm";
+/** Every commit carries the hash-bound, display-only summary first (spec 6.4a). */
+export declare const confirmTextShape: z.ZodString;
+export interface CommitArgsBase {
+    confirmText: string;
+    instanceId: string;
+    [key: string]: unknown;
+}
+export interface ConfirmedWriteDef<P, A extends CommitArgsBase, R> {
+    /** stable action id bound into the token, e.g. 'roleplay.comment.create' */
+    action: string;
+    group: ToolGroup;
+    propose: {
+        name: string;
+        title: string;
+        description: string;
+        inputShape: Record<string, z.ZodType>;
+    };
+    /** argsShape must start with `confirmText` (JSON Schema property order, for hosts that show the schema) */
+    commit: {
+        name: string;
+        title: string;
+        description: string;
+        argsShape: Record<string, z.ZodType>;
+    };
+    /** Canonical commit args: ONLY the keys of commit.argsShape, every default materialized. Pure and idempotent. */
+    normalize(args: Record<string, unknown>): A;
+    /** Validate + read; returns the commit args and the human preview. Throws CliError on refusal. */
+    prepare(input: P, auth: InjectedAuth, deps?: unknown): Promise<{
+        args: A;
+        actorUserId: string;
+        preview: ProposalPreview;
+    }>;
+    /** The write. Sends `Idempotency-Key: idempotencyKey`. Called only after the token verified. */
+    execute(args: A, idempotencyKey: string, auth: InjectedAuth, deps?: unknown): Promise<{
+        result: R;
+        replayed: boolean;
+    }>;
+    resultText(r: R, status: CommitResult['status']): string;
+    /** the commit (and propose) arg the confirm view may edit; it re-proposes with the new value */
+    editableArg?: keyof A & string;
+    /** propose text budget; tests only (default PROPOSAL_TEXT_MAX_BYTES) */
+    textMaxBytes?: number;
+}
+/** Copies exactly the shape's keys out of the handler's merged object (never a spread: injected keys stay out). */
+export declare function pickArgs(opts: Record<string, unknown>, shape: Record<string, z.ZodType>): Record<string, unknown>;
+/** Control characters removed (a third-party string never adds a line to a preview). */
+export declare function stripControls(s: string): string;
+/** A third-party string as a preview shows it: controls removed, at most `max` characters (never a split code point). */
+export declare function previewName(s: unknown, max?: number): string;
+/** "a, b and N more": at most `max` names, the rest counted (never cut mid-name). */
+export declare function nameList(names: string[], max: number): string;
+/** The proposal id seeds one key: `mcp-<action>-<jti>` (ASCII, at most 80 characters). */
+export declare const idempotencyKeyOf: (c: Pick<ProposalClaims, "action" | "jti">) => string;
+/** The commit call as the host_prompt tail prints it: confirmText first, the rest canonical, proposalToken last. */
+export declare function printCommitArgs(args: Record<string, unknown>, proposalToken: string): string;
+/** The propose tool's model text (spec 8.2). The body appears once: as a line in app mode, inside the call otherwise. */
+export declare function proposalText(p: Proposal): string;
+/** The commit tool's model text (spec 8.3). */
+export declare function commitText(status: CommitResult['status'], resultText: string): string;
+/** The propose + commit descriptors of one confirmed write (spec 6.4). Both are `access: 'write'` (PIT-10114 rule 3). */
+export declare function defineConfirmedWrite<P, A extends CommitArgsBase, R>(def: ConfirmedWriteDef<P, A, R>): [ToolDescriptor, ToolDescriptor];