@pitcher/cli-scripts 3.1.0 → 3.2.0

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/metadataTemplate.js

@@ -25,8 +25,9 @@ export const metadataTemplateTools = [
         name: 'pitcher_metadata_template_upsert',
         title: 'Upsert a metadata template',
         description: "Upsert an instance's metadata-field schema. Merges the incoming sections by section 'label' — a " +
-            'section whose label matches an existing one is replaced, other sections are preserved. Cannot remove ' +
-            'a section or field. Pass exactly one of sections or sectionsFile. Requires an instance- or org-admin key.',
+            'section whose label matches an existing one is REPLACED WHOLE (fields left out of it are removed), other ' +
+            'sections are preserved. Cannot remove a whole section. Pass exactly one of sections or sectionsFile. ' +
+            'Requires an instance- or org-admin key.',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
             sections: z.string().optional().describe('Sections JSON array (inline)'),

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

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

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

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { ROLEPLAY_DIFFICULTIES, ROLEPLAY_GROUP_BY, ROLEPLAY_SESSION_SORT, runRoleplayKpis, runRoleplayRepSummary, runRoleplayScenariosList, runRoleplaySessionGet, runRoleplaySessions, runRoleplayTeam, } from '../../commands/roleplay.js';
+const instanceId = z.string().describe('Instance ID (required)');
+/** The shared roleplay_statements filters. Dates have NO default window: omitted means all time. */
+const filters = {
+    instanceId,
+    startDate: z.string().optional().describe('Window start, ISO date. Omitted = all time (no default window)'),
+    endDate: z.string().optional().describe('Window end, ISO date. Omitted = all time (no default window)'),
+    rep: z.string().optional().describe('Rep name or email contains (case-insensitive)'),
+    scenario: z.string().optional().describe('Scenario or persona name contains (case-insensitive)'),
+    difficulty: z.enum(ROLEPLAY_DIFFICULTIES).optional().describe('Scenario difficulty'),
+};
+const UNSCORED = 'A session without a score (score null: the AI evaluation failed or is pending) is UNSCORED, never 0: ' +
+    'never count it in an average or as a fail.';
+const CH_SOURCE = 'Reads the AI Roleplay analytics replica (ClickHouse roleplay_statements, the Admin Analytics tab). ' +
+    'Dates are optional and there is no default window: omitted means all time.';
+const ADMIN_ONLY = 'Instance or org admins only; anyone else gets an AUTH error, and a coaching manager should use pitcher_roleplay_team.';
+export const roleplayTools = [
+    {
+        name: 'pitcher_roleplay_kpis',
+        title: 'AI Roleplay KPIs',
+        description: 'AI Roleplay totals for an instance: total, scored and unscored sessions, the mean score of SCORED sessions, ' +
+            `mean duration and active reps, with optional rep/scenario/difficulty filters. ${UNSCORED} ${CH_SOURCE} ${ADMIN_ONLY}`,
+        inputShape: filters,
+        run: runRoleplayKpis,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_sessions',
+        title: 'AI Roleplay sessions',
+        description: 'AI Roleplay session list for an instance, newest first: entry_id, session_at, rep_name, who (rep email), ' +
+            'scenario_name, persona_name, difficulty, score, evaluated, rating, duration_ms. Default 20 rows, max 100 per ' +
+            `page; total_count/has_more say when there are more. ${UNSCORED} ${CH_SOURCE} ${ADMIN_ONLY} ` +
+            'Open one session with pitcher_roleplay_session_get (its entry_id).',
+        inputShape: {
+            ...filters,
+            sortBy: z.enum(ROLEPLAY_SESSION_SORT).optional().describe('Sort field (default session_at)'),
+            sortOrder: z.enum(['asc', 'desc']).optional().describe('Sort direction (default desc); unscored sessions sort last'),
+            page: z.number().int().optional().describe('Page number (default 1)'),
+            limit: z.number().int().optional().describe('Rows per page (default 20, max 100)'),
+        },
+        run: runRoleplaySessions,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_rep_summary',
+        title: 'AI Roleplay per-rep or per-scenario summary',
+        description: 'Per-rep (groupBy rep, keyed on the rep email) or per-scenario (groupBy scenario) session counts, scored ' +
+            'counts, mean score of scored sessions and last session, up to 50 groups with the most sessions. Exact up to ' +
+            '5000 sessions in the window (read newest first); `complete: false` means the figures cover only the newest ' +
+            `5000, so narrow the dates. ${UNSCORED} ${CH_SOURCE} ${ADMIN_ONLY}`,
+        inputShape: {
+            ...filters,
+            groupBy: z.enum(ROLEPLAY_GROUP_BY).optional().describe('Group by rep (default) or scenario'),
+        },
+        run: runRoleplayRepSummary,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_team',
+        title: 'AI Roleplay assignment completion',
+        description: 'Roleplay assignment completion per rep, as the AI Roleplay manager app shows it: per assignment its passing ' +
+            'score and due date, each rep\'s status (passed, in_progress, not_started, overdue, needs_coaching), sessions, ' +
+            'scored sessions, best and mean score, trend, last session, plus per-skill mean scores. Instance or org admins ' +
+            'get every roleplay assignment on the instance (scope "instance"); a coaching manager gets the assignments ' +
+            'they coach (scope "coach"). Works for any member (an empty list when they coach nobody). ' +
+            `${UNSCORED} Reads Postgres appsDB through next-core (cch-assignment, cch-session-result), not ClickHouse. ` +
+            'The server returns at most the newest 1000 sessions; `complete: false` says the cap was hit. ' +
+            'Up to 50 assignments and 100 reps each; filter with assignmentId or status.',
+        inputShape: {
+            instanceId,
+            assignmentId: z.string().optional().describe('Only this assignment (its id from an earlier call)'),
+            status: z
+                .enum(['passed', 'in_progress', 'not_started', 'overdue', 'needs_coaching'])
+                .optional()
+                .describe('Only reps with this status'),
+        },
+        run: runRoleplayTeam,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_session_get',
+        title: 'AI Roleplay session detail',
+        description: 'One AI Roleplay session: scenario, difficulty, time, duration, overall score (null = unscored, never 0), ' +
+            'evaluation status, and the evaluation summary, strengths, improvements and per-skill scores with feedback. ' +
+            'Never the transcript, messages or recordings. Opens to the rep, a coach of that rep, or an instance or org ' +
+            'admin; anyone else gets an AUTH error. Reads Postgres appsDB (cch-session-result) through next-core. ' +
+            'Takes entryId = entry_id from pitcher_roleplay_sessions.',
+        inputShape: {
+            instanceId,
+            entryId: z.string().describe('Session entry ID (entry_id from pitcher_roleplay_sessions)'),
+        },
+        run: runRoleplaySessionGet,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_scenarios_list',
+        title: 'AI Roleplay scenarios',
+        description: 'The AI Roleplay scenario catalog of an instance: id, kind, name, persona title, description, difficulty, ' +
+            'active, time limit and the skills it is graded on (title and weight). Never a prompt. Any member. ' +
+            'Reads the instance config (appsDB cch-config) through next-core.',
+        inputShape: { instanceId },
+        run: runRoleplayScenariosList,
+        readOnly: true,
+    },
+];

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PitcherAG/web.git",
+    "directory": "packages/libs/cli-scripts"
+  },
   "keywords": [
     "pitcher",
     "cli",