@pitcher/cli-scripts 3.1.1 → 3.2.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/roleplay-stats.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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), `lib/status.ts` (`deriveStatus`) and `hooks/useManagerData.ts`
+ * (`getAssignmentSessions`, `getRepStats`). 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?: {
+        category_scores?: Array<{
+            id?: string;
+            skillId?: string;
+            title?: string;
+            score?: number;
+        }>;
+    } | 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';
+/** 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 (legacy
+ * evaluations may grade on a 5-point scale; the manager app does not normalise either).
+ */
+export declare function deriveStatus(sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date): 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;
+}
+/** `getRepStats` for one rep of one assignment, without the raw sessions. */
+export declare function repStats(userId: string, sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date): RepStats;
+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,114 @@
+/**
+ * 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), `lib/status.ts` (`deriveStatus`) and `hooks/useManagerData.ts`
+ * (`getAssignmentSessions`, `getRepStats`). 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 (legacy
+ * evaluations may grade on a 5-point scale; the manager app does not normalise either).
+ */
+export function deriveStatus(sessions, assignment, now = new Date()) {
+    const isOverdue = assignment.type === 'mandatory' && !!assignment.dueDate && new Date(assignment.dueDate) < now;
+    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. */
+export function repStats(userId, sessions, assignment, now = new Date()) {
+    const own = sessions.filter((s) => s.userId === userId).sort(byTimestamp);
+    return {
+        user_id: userId,
+        sessions: own.length,
+        scored_sessions: scoredCount(own),
+        best_score: bestScore(own),
+        avg_score: avgScore(own),
+        trend: calcTrend(own),
+        status: deriveStatus(own, assignment, now),
+        last_session_at: own.length > 0 ? (own[own.length - 1].timestamp ?? null) : null,
+        total_duration_ms: own.reduce((sum, s) => sum + (s.durationMs ?? 0), 0),
+    };
+}
+/**
+ * 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/registry.js

@@ -15,6 +15,7 @@ import { metadataTemplateTools } from './tools/metadataTemplate.js';
 import { ldTools } from './tools/ld.js';
 import { orgTools } from './tools/org.js';
 import { publishAppTools } from './tools/publishApp.js';
+import { roleplayTools } from './tools/roleplay.js';
 import { rolesTools } from './tools/roles.js';
 import { searchTools } from './tools/search.js';
 import { sharedLinksTools } from './tools/sharedLinks.js';
@@ -39,6 +40,7 @@ export const allTools = [
     ...rolesTools,
     ...orgTools,
     ...analyticsTools,
+    ...roleplayTools,
     ...membershipsTools,
     ...groupsTools,
     ...metadataTemplateTools,

package/dist/src/mcp/renderPolicy.d.ts

@@ -1 +1 @@
-export declare const ANALYTICS_RENDER_POLICY = "When answering Pitcher content-analytics questions (the pitcher_analytics_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.\n\nRendering tiers (evaluate top-down, stop at the first match):\n- A single fact / yes-no / \"who/what/how many is the single X\" (e.g. \"which canvas did I view?\", \"how many viewers?\") -> 1-2 sentences with the number inline. No table, no chart.\n- A ranking request (\"top\", \"most\", \"best\", \"rank\", or \"list the highest/lowest ...\") about content, files, users, or canvases -> a markdown TABLE of the ranked rows (default the top 5-8); columns = only the metric(s) asked for. Treat \"what's my top content?\" as a ranking (a table), NOT a single-item sentence. Lead with a one-line takeaway, then the table.\n- \"over time\" / \"trend\" / \"by week/month\" -> ONE line/area chart artifact (this rule wins over the generic comparison rule below for time series).\n- An explicit visualization request (\"show a chart\", \"chart\", \"visualize\", \"graph\", \"plot\") OR a comparison across a non-time dimension -> ONE focused chart as a single self-contained HTML artifact, only the asked-for series.\n- A broad overview (\"how's everything / my content / adoption doing\", \"give me the picture\", \"dashboard\", QBR) -> a multi-panel dashboard artifact. This is the ceiling \u2014 use it rarely, only for genuinely broad asks.\n\nGuardrails (every tier):\n1. Words first \u2014 even with a chart, lead with a one-sentence answer to the literal question.\n2. Mask names, emails, and user IDs by default (User A/B/...). Reveal an identity only when the analytics tool actually returned it for the authenticated role (the verbs are role-gated); never infer authorization from the user's wording.\n3. If data is empty or trivially small, say so in prose \u2014 do not render an empty chart.\n4. If results are capped/truncated, state the cap (\"top 15 of 118\").\n5. Never show a \"vs prior period\" delta unless the data actually contains prior-period numbers.\n6. Cite the source verb (\"via analytics popularity\").\n\nDo not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.";
+export declare const ANALYTICS_RENDER_POLICY = "When answering Pitcher content-analytics or AI Roleplay questions (the pitcher_analytics_* and pitcher_roleplay_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.\n\nRendering tiers (evaluate top-down, stop at the first match):\n- A single fact / yes-no / \"who/what/how many is the single X\" (e.g. \"which canvas did I view?\", \"how many viewers?\") -> 1-2 sentences with the number inline. No table, no chart.\n- A ranking request (\"top\", \"most\", \"best\", \"rank\", or \"list the highest/lowest ...\") about content, files, users, or canvases -> a markdown TABLE of the ranked rows (default the top 5-8); columns = only the metric(s) asked for. Treat \"what's my top content?\" as a ranking (a table), NOT a single-item sentence. Lead with a one-line takeaway, then the table.\n- \"over time\" / \"trend\" / \"by week/month\" -> ONE line/area chart artifact (this rule wins over the generic comparison rule below for time series).\n- An explicit visualization request (\"show a chart\", \"chart\", \"visualize\", \"graph\", \"plot\") OR a comparison across a non-time dimension -> ONE focused chart as a single self-contained HTML artifact, only the asked-for series.\n- A broad overview (\"how's everything / my content / adoption doing\", \"give me the picture\", \"dashboard\", QBR) -> a multi-panel dashboard artifact. This is the ceiling \u2014 use it rarely, only for genuinely broad asks.\n\nGuardrails (every tier):\n1. Words first \u2014 even with a chart, lead with a one-sentence answer to the literal question.\n2. Mask names, emails, and user IDs by default (User A/B/...). Reveal an identity only when the analytics tool actually returned it for the authenticated role (the verbs are role-gated); never infer authorization from the user's wording.\n3. If data is empty or trivially small, say so in prose \u2014 do not render an empty chart.\n4. If results are capped/truncated, state the cap (\"top 15 of 118\").\n5. Never show a \"vs prior period\" delta unless the data actually contains prior-period numbers.\n6. Cite the source verb (\"via analytics popularity\").\n7. AI Roleplay: a session with no score (null) is unscored, never a 0; never fold it into an average, a pass rate or a ranking.\n\nDo not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.";

package/dist/src/mcp/renderPolicy.js

@@ -3,7 +3,7 @@
 // question gets a right-sized reply (a sentence, a table, one chart, or — rarely — a dashboard)
 // instead of a rigid full dashboard on every question. This constant is the single source of truth;
 // the Docs Portal spec (Product/Specs/2026-07-24-analytics-answer-rendering-policy.md) mirrors it.
-export const ANALYTICS_RENDER_POLICY = `When answering Pitcher content-analytics questions (the pitcher_analytics_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.
+export const ANALYTICS_RENDER_POLICY = `When answering Pitcher content-analytics or AI Roleplay questions (the pitcher_analytics_* and pitcher_roleplay_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.
 
 Rendering tiers (evaluate top-down, stop at the first match):
 - A single fact / yes-no / "who/what/how many is the single X" (e.g. "which canvas did I view?", "how many viewers?") -> 1-2 sentences with the number inline. No table, no chart.
@@ -19,5 +19,6 @@ Guardrails (every tier):
 4. If results are capped/truncated, state the cap ("top 15 of 118").
 5. Never show a "vs prior period" delta unless the data actually contains prior-period numbers.
 6. Cite the source verb ("via analytics popularity").
+7. AI Roleplay: a session with no score (null) is unscored, never a 0; never fold it into an average, a pass rate or a ranking.
 
 Do not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.`;

package/dist/src/mcp/resources/analyticsCatalog.d.ts

@@ -1,3 +1,3 @@
 import type { ResourceDescriptor } from './types.js';
-export declare const ANALYTICS_CATALOG = "# Pitcher analytics catalog\n\nTen read-only verbs, each an MCP tool named `pitcher_analytics_<verb>`. Pick the verb that matches the\nquestion, then call its tool. All are read-only; org scope + auth come from the server's API key (never a\ntool input) \u2014 you only pass `instanceId` (and, where noted, `canvasId`/`userEmail`).\n\n## Key tiers\n- **org-admin key required:** org, popularity, users, files, canvases\n- **instance-admin or org-admin:** instance\n- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions\n\n## Time model\n- **Rollup (no window):** org, instance \u2014 lifetime/current totals.\n- **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, `users` with\n  `stats: true`, files, canvases \u2014 omit dates to get the last 30 days. (`users` without `stats` is a\n  full roster with no window.)\n- **Date-range, server default window:** viewers, sessions \u2014 omit dates and the service picks the window.\n\n## Verbs\n\n| Verb (tool) | Returns | Time | Key | Example question |\n|---|---|---|---|---|\n| `org` | Organization-wide rollup totals (Django) | rollup | org-admin | \"How is the whole org doing overall?\" |\n| `instance` | Single-instance rollup totals (Django) | rollup | instance-admin | \"Totals for this one workspace?\" |\n| `kpi` | KPI metrics for an instance (members, active users, \u2026) | date-range | member | \"How many active users last month?\" |\n| `engagement` | Per-DSR/content engagement rows (capped list + summary) | date-range | member | \"Which content is being engaged with?\" |\n| `popularity` | Most-viewed canvases, ranked (view-analysis) | date-range | org-admin | \"Top 10 most-viewed decks this quarter?\" |\n| `users` | User roster, or active-user stats with `stats: true` | roster: none / stats: date-range | org-admin | \"Who are my active users this month?\" |\n| `files` | File usage analytics (views/opens/engagement per file) | date-range | org-admin | \"Which files get opened the most?\" |\n| `canvases` | Per-section canvas engagement list | date-range | org-admin | \"How are my canvas sections performing?\" |\n| `viewers` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | \"Who viewed this DSR, and how much?\" |\n| `sessions` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | \"What did this viewer do inside the DSR?\" |\n\n## Shaping\nRow-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:\n`summary` + `rows` (default 20, max 100 \u2014 raise with `limit`) + `total_count`/`returned`/`has_more`,\nand a `truncated` note when more rows exist. `kpi` and `sessions` return the raw payload (a KPI scalar set\nand an uncapped event timeline, respectively) \u2014 never truncated.\n\n## DSR drill-down\nFor \"who viewed X and what did they do\": call `viewers` (with `canvasId`) to list viewers, then `sessions`\n(with the same `canvasId` + the viewer's `userEmail`) to see that viewer's event timeline.\nA session is one `Entered` of the queried id itself (a canvas or a section), paired by `event_pair_id`; an\n`Entered` with an empty `event_pair_id` counts as one session on its own.\n`session_count` is counted the same way as the overview's `total_sessions`. `canvases` lists sections, and their\nids are valid `canvasId` inputs for `viewers` and `sessions`.\n\n## Notes\n- `popularity` maps to the canvases view-analysis endpoint (there is no separate popularity route).\n- Results can include user identities/emails \u2014 treat as customer data and handle per policy.\n";
+export declare const ANALYTICS_CATALOG = "# Pitcher analytics catalog\n\nFourteen read-only verbs, each an MCP tool named `pitcher_analytics_<verb>`. Pick the verb that matches the\nquestion, then call its tool. All are read-only; org scope + auth come from the server's API key (never a\ntool input) \u2014 you only pass `instanceId` (and, where noted, `canvasId`/`userEmail`).\n\n## Key tiers\n- **org-admin key required:** org, popularity, users, files, canvases\n- **instance-admin or org-admin:** instance\n- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions, viewer_visits\n- **instance editor, instance admin or org admin:** file_users, file_pages, canvas_users\n\n## Time model\n- **Rollup (no window):** org, instance \u2014 lifetime/current totals.\n- **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, `users` with\n  `stats: true`, files, canvases \u2014 omit dates to get the last 30 days. (`users` without `stats` is a\n  full roster with no window.) Also file_users, file_pages, canvas_users.\n- **Date-range, server default window:** viewers, sessions, viewer_visits \u2014 omit dates and the service picks the window.\n\n## Verbs\n\n| Verb (tool) | Returns | Time | Key | Example question |\n|---|---|---|---|---|\n| `org` | Organization-wide rollup totals (Django) | rollup | org-admin | \"How is the whole org doing overall?\" |\n| `instance` | Single-instance rollup totals (Django) | rollup | instance-admin | \"Totals for this one workspace?\" |\n| `kpi` | KPI metrics for an instance (members, active users, \u2026) | date-range | member | \"How many active users last month?\" |\n| `engagement` | Per-DSR/content engagement rows (capped list + summary) | date-range | member | \"Which content is being engaged with?\" |\n| `popularity` | Most-viewed canvases, ranked (view-analysis) | date-range | org-admin | \"Top 10 most-viewed decks this quarter?\" |\n| `users` | User roster, or active-user stats with `stats: true` | roster: none / stats: date-range | org-admin | \"Who are my active users this month?\" |\n| `files` | File usage analytics (views/opens/engagement per file) | date-range | org-admin | \"Which files get opened the most?\" |\n| `canvases` | Per-section canvas engagement list | date-range | org-admin | \"How are my canvas sections performing?\" |\n| `viewers` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | \"Who viewed this DSR, and how much?\" |\n| `sessions` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | \"What did this viewer do inside the DSR?\" |\n| `file_users` | Who opened ONE file: opens, seconds, days active per user | date-range | editor | \"Who opened the pricing PDF, and for how long?\" |\n| `file_pages` | Time per page of ONE file (one user with a single `userEmails`) | date-range | editor | \"Which pages of this file do reps spend time on?\" |\n| `canvas_users` | Per user and canvas: visits, seconds; with `canvasId`, seconds per page (section) | date-range | editor | \"Which reps presented this deck, and which slides?\" |\n| `viewer_visits` | Per DSR viewer and visit: sections, files and pages with seconds; `format: csv` to export | date-range | member | \"Export who looked at which pages of this DSR\" |\n\n## Shaping\nRow-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:\n`summary` + `rows` (default 20, max 100 \u2014 raise with `limit`) + `total_count`/`returned`/`has_more`,\nand a `truncated` note when more rows exist. `kpi` and `sessions` return the raw payload (a KPI scalar set\nand an uncapped event timeline, respectively) \u2014 never truncated.\n\n## DSR drill-down\nFor \"who viewed X and what did they do\": call `viewers` (with `canvasId`) to list viewers, then `sessions`\n(with the same `canvasId` + the viewer's `userEmail`) to see that viewer's event timeline.\nA session is one `Entered` of the queried id itself (a canvas or a section), paired by `event_pair_id`; an\n`Entered` with an empty `event_pair_id` counts as one session on its own.\n`session_count` is counted the same way as the overview's `total_sessions`. `canvases` lists sections, and their\nids are valid `canvasId` inputs for `viewers` and `sessions`.\n\n`viewer_visits` does both steps for up to 25 viewers at once and returns per-visit, per-page time; use it for\n\"which pages did each viewer look at\", and `format: \"csv\"` when the user wants a file.\n\n## Per-user usage\n\"Which files did this user open\" is `files` with `userEmails`; \"who opened this file\" is `file_users`; time per page\nof a file is `file_pages`; reps' canvas usage is `canvas_users` (internal users only \u2014 external DSR viewers are\n`viewers` / `viewer_visits`).\n\n## AI Roleplay\nRoleplay results are separate tools (`pitcher_roleplay_*`): kpis, sessions and rep_summary for instance or org admins,\nteam (assignment completion; admins see every assignment, coaching managers their own), session_get and\nscenarios_list. A session with no score is unscored, never 0.\n\n## Notes\n- `popularity` maps to the canvases view-analysis endpoint (there is no separate popularity route).\n- Results can include user identities/emails \u2014 treat as customer data and handle per policy.\n";
 export declare const analyticsCatalogResource: ResourceDescriptor;

package/dist/src/mcp/resources/analyticsCatalog.js

@@ -1,25 +1,26 @@
 // A model-facing catalog of the analytics verbs exposed as pitcher_analytics_* tools. It exists so a
 // host can read ONE resource to learn which verb answers which question, the time model each uses, and
-// the key tier each needs — instead of guessing from 10 tool descriptions. Distilled from the analytics
+// the key tier each needs — instead of guessing from 14 tool descriptions. Distilled from the analytics
 // runner contracts in src/commands/analytics.ts (the authoritative source); keep in sync on route/gate
 // changes. Definitions mirror the platform analytics vocabulary.
 export const ANALYTICS_CATALOG = `# Pitcher analytics catalog
 
-Ten read-only verbs, each an MCP tool named \`pitcher_analytics_<verb>\`. Pick the verb that matches the
+Fourteen read-only verbs, each an MCP tool named \`pitcher_analytics_<verb>\`. Pick the verb that matches the
 question, then call its tool. All are read-only; org scope + auth come from the server's API key (never a
 tool input) — you only pass \`instanceId\` (and, where noted, \`canvasId\`/\`userEmail\`).
 
 ## Key tiers
 - **org-admin key required:** org, popularity, users, files, canvases
 - **instance-admin or org-admin:** instance
-- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions
+- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions, viewer_visits
+- **instance editor, instance admin or org admin:** file_users, file_pages, canvas_users
 
 ## Time model
 - **Rollup (no window):** org, instance — lifetime/current totals.
 - **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, \`users\` with
   \`stats: true\`, files, canvases — omit dates to get the last 30 days. (\`users\` without \`stats\` is a
-  full roster with no window.)
-- **Date-range, server default window:** viewers, sessions — omit dates and the service picks the window.
+  full roster with no window.) Also file_users, file_pages, canvas_users.
+- **Date-range, server default window:** viewers, sessions, viewer_visits — omit dates and the service picks the window.
 
 ## Verbs
 
@@ -35,6 +36,10 @@ tool input) — you only pass \`instanceId\` (and, where noted, \`canvasId\`/\`u
 | \`canvases\` | Per-section canvas engagement list | date-range | org-admin | "How are my canvas sections performing?" |
 | \`viewers\` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | "Who viewed this DSR, and how much?" |
 | \`sessions\` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | "What did this viewer do inside the DSR?" |
+| \`file_users\` | Who opened ONE file: opens, seconds, days active per user | date-range | editor | "Who opened the pricing PDF, and for how long?" |
+| \`file_pages\` | Time per page of ONE file (one user with a single \`userEmails\`) | date-range | editor | "Which pages of this file do reps spend time on?" |
+| \`canvas_users\` | Per user and canvas: visits, seconds; with \`canvasId\`, seconds per page (section) | date-range | editor | "Which reps presented this deck, and which slides?" |
+| \`viewer_visits\` | Per DSR viewer and visit: sections, files and pages with seconds; \`format: csv\` to export | date-range | member | "Export who looked at which pages of this DSR" |
 
 ## Shaping
 Row-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:
@@ -50,6 +55,19 @@ A session is one \`Entered\` of the queried id itself (a canvas or a section), p
 \`session_count\` is counted the same way as the overview's \`total_sessions\`. \`canvases\` lists sections, and their
 ids are valid \`canvasId\` inputs for \`viewers\` and \`sessions\`.
 
+\`viewer_visits\` does both steps for up to 25 viewers at once and returns per-visit, per-page time; use it for
+"which pages did each viewer look at", and \`format: "csv"\` when the user wants a file.
+
+## Per-user usage
+"Which files did this user open" is \`files\` with \`userEmails\`; "who opened this file" is \`file_users\`; time per page
+of a file is \`file_pages\`; reps' canvas usage is \`canvas_users\` (internal users only — external DSR viewers are
+\`viewers\` / \`viewer_visits\`).
+
+## AI Roleplay
+Roleplay results are separate tools (\`pitcher_roleplay_*\`): kpis, sessions and rep_summary for instance or org admins,
+team (assignment completion; admins see every assignment, coaching managers their own), session_get and
+scenarios_list. A session with no score is unscored, never 0.
+
 ## Notes
 - \`popularity\` maps to the canvases view-analysis endpoint (there is no separate popularity route).
 - Results can include user identities/emails — treat as customer data and handle per policy.

package/dist/src/mcp/tools/analytics.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { KPI_TYPES } from '../../core/kpiTypes.js';
-import { runAnalyticsOrg, runAnalyticsInstance, runAnalyticsKpi, runAnalyticsEngagement, runAnalyticsPopularity, runAnalyticsUsers, runAnalyticsFiles, runAnalyticsCanvases, runAnalyticsViewers, runAnalyticsSessions, } from '../../commands/analytics.js';
+import { runAnalyticsOrg, runAnalyticsInstance, runAnalyticsKpi, runAnalyticsEngagement, runAnalyticsPopularity, runAnalyticsUsers, runAnalyticsFiles, runAnalyticsCanvases, runAnalyticsViewers, runAnalyticsSessions, runAnalyticsFileUsers, runAnalyticsFilePages, runAnalyticsCanvasUsers, runAnalyticsViewerVisits, } from '../../commands/analytics.js';
 export const analyticsTools = [
     {
         name: 'pitcher_analytics_org',
@@ -23,7 +23,7 @@ export const analyticsTools = [
         title: 'Instance KPI metrics',
         description: 'Read KPI metrics for an instance from the clickhouse analytics service (PIT-7647). ' +
             'Access follows the signed-in user’s own role; activity-metric types need start/end dates ' +
-            '(inventory counts like total-members do not).',
+            '(inventory counts like total-members do not). Every value and growth figure is a number.',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
             type: z.enum(KPI_TYPES).describe('KPI type'),
@@ -97,7 +97,9 @@ export const analyticsTools = [
         name: 'pitcher_analytics_files',
         title: 'File usage analytics',
         description: 'File usage analytics for an instance (views/opens/engagement per file), summarized and capped to ' +
-            '`limit`. Requires an org-admin key. Defaults to a 30-day window when dates are omitted.',
+            '`limit`. Requires an org-admin key. Defaults to a 30-day window when dates are omitted. ' +
+            'Pass userEmails to answer "which files did this user open"; for "who opened this file" use ' +
+            'pitcher_analytics_file_users.',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
             startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
@@ -173,4 +175,87 @@ export const analyticsTools = [
         run: runAnalyticsSessions,
         readOnly: true,
     },
+    {
+        name: 'pitcher_analytics_file_users',
+        title: 'Who opened a file',
+        description: 'Who opened ONE file in an instance: per user (email, name, role) the opens, seconds, days active and the ' +
+            'last day opened, sorted by opens and capped to `limit` (total_count/has_more state the cap). Internal users ' +
+            'only. pageNumber (0-based) narrows to one page of the file. Needs an instance editor, instance admin or org ' +
+            'admin. Defaults to a 30-day window. For time per page use pitcher_analytics_file_pages.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            fileId: z.string().describe('File ID (required)'),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            pageNumber: z.number().int().min(0).optional().describe('Only this page of the file (0-based)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            userEmails: z.string().optional().describe('Comma-separated user emails to scope by'),
+            limit: z.number().int().optional().describe('Max rows to return (default 20, max 100)'),
+        },
+        run: runAnalyticsFileUsers,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_file_pages',
+        title: 'Time per page of a file',
+        description: 'Time per page of ONE file: per page (1-based page_number) the internal opens, internal seconds and mean ' +
+            'seconds, plus external (DSR) views. Pass a single userEmails value for one user\'s time per page. Every page ' +
+            'is returned. Needs an instance editor, instance admin or org admin. Defaults to a 30-day window.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            fileId: z.string().describe('File ID (required)'),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            userEmails: z.string().optional().describe('Comma-separated user emails to scope by (one email: that user)'),
+        },
+        run: runAnalyticsFilePages,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_canvas_users',
+        title: 'Per-user canvas usage',
+        description: 'Per-user canvas usage in an instance: one row per user and canvas (who, canvas_id, canvas_name, views = ' +
+            'visits, total_seconds, last_viewed_at), most visits first, `limit` rows per page with total_count/has_more. ' +
+            'With canvasId, each row also lists the pages (sections) of that canvas the user viewed with their seconds. ' +
+            'Internal users only (external DSR viewers: pitcher_analytics_viewer_visits); presentation time only, not ' +
+            'editing. Needs an instance editor, instance admin or org admin. Defaults to a 30-day window.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            canvasId: z.string().optional().describe("One canvas: adds each user's seconds per page (section)"),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            userEmails: z.string().optional().describe('Comma-separated user emails to scope by'),
+            page: z.number().int().optional().describe('Page number (default 1)'),
+            limit: z.number().int().optional().describe('Rows per page (default 20, max 100)'),
+        },
+        run: runAnalyticsCanvasUsers,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_viewer_visits',
+        title: 'DSR viewer visits and page time',
+        description: 'Per viewer of a DSR canvas: each visit (start, engaged seconds) and in it the sections, files and pages ' +
+            'viewed with views and seconds (`estimated: true` where an exit event was missing and the time is ' +
+            'inferred). One viewer (userEmail, verbatim from pitcher_analytics_viewers) or the most recently active ' +
+            'viewers (limit, default 10, max 25; viewers_total and truncated state the cap). format "csv" returns the ' +
+            'same as CSV text in `csv` (one row per viewer, visit and item) with a suggested filename, for export: hand ' +
+            'it to the user as a file. Works for any member. The server applies its own default window.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            canvasId: z.string().describe('DSR canvas ID (required)'),
+            userEmail: z
+                .string()
+                .optional()
+                .describe('One viewer: normalized_email (or email) from pitcher_analytics_viewers, VERBATIM'),
+            viewerType: z.string().optional().describe("Viewer type when listing: all, internal, external (default 'all')"),
+            startDate: z.string().optional().describe('Window start, ISO date (server default applies if omitted)'),
+            endDate: z.string().optional().describe('Window end, ISO date (server default applies if omitted)'),
+            limit: z.number().int().optional().describe('Viewers to read when no userEmail (default 10, max 25)'),
+            format: z.enum(['json', 'csv']).optional().describe('json (default) or csv for an export'),
+        },
+        run: runAnalyticsViewerVisits,
+        readOnly: true,
+    },
 ];

package/dist/src/mcp/tools/roleplay.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDescriptor } from './types.js';
+export declare const roleplayTools: ToolDescriptor[];