@pitcher/cli-scripts 3.1.1 → 3.3.0

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

@@ -0,0 +1,14 @@
+import type { ToolDescriptor } from '../tools/types.js';
+import type { AppViewDescriptor } from './types.js';
+/**
+ * MCP Apps registry (PIT-10066). Kept apart from `allTools` on purpose: app tools compose several run*
+ * functions and are not CLI commands, so the CLI registry guards (134 tools, one run* each) stay untouched.
+ * A follow-up view adds its descriptor and tools here and nowhere else on the server side.
+ */
+export declare const allAppViews: AppViewDescriptor[];
+/**
+ * App tools carry their group on the descriptor (roleplay manager `roleplay`, DSR engagement `analytics`); the content
+ * picker module is assigned `content` here. `checkDescriptor` runs on every entry: it is the only guard for tools that
+ * set their own group (PIT-10113 confirm tools included). Every app tool must declare `access` explicitly.
+ */
+export declare const allAppTools: ToolDescriptor[];

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

@@ -0,0 +1,25 @@
+import { checkDescriptor, inGroup } from '../groups.js';
+import { contentPickerView, contentPickerTools } from './contentPicker.js';
+import { dsrEngagementView, dsrEngagementTools } from './dsrEngagement.js';
+import { roleplayManagerView, roleplayManagerTools } from './roleplayManager.js';
+import { roleplayRepsTools } from './roleplayReps.js';
+import { roleplayWriteTools } from './roleplayWrites.js';
+import { writeConfirmView } from './writeConfirm.js';
+/**
+ * MCP Apps registry (PIT-10066). Kept apart from `allTools` on purpose: app tools compose several run*
+ * functions and are not CLI commands, so the CLI registry guards (134 tools, one run* each) stay untouched.
+ * A follow-up view adds its descriptor and tools here and nowhere else on the server side.
+ */
+export const allAppViews = [contentPickerView, roleplayManagerView, dsrEngagementView, writeConfirmView];
+/**
+ * App tools carry their group on the descriptor (roleplay manager `roleplay`, DSR engagement `analytics`); the content
+ * picker module is assigned `content` here. `checkDescriptor` runs on every entry: it is the only guard for tools that
+ * set their own group (PIT-10113 confirm tools included). Every app tool must declare `access` explicitly.
+ */
+export const allAppTools = [
+    ...inGroup('content', contentPickerTools),
+    ...roleplayManagerTools,
+    ...roleplayRepsTools, // PIT-10116: the Reps tab of the roleplay manager view
+    ...dsrEngagementTools,
+    ...roleplayWriteTools,
+].map(checkDescriptor);

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

@@ -0,0 +1,228 @@
+import type { AxiosInstance } from 'axios';
+import { z } from 'zod';
+import { type CoachAssignment, type CoachScope, type CoachSession, type Coverage, type TeamModel } from '../../commands/roleplay.js';
+import { type Envelope } from '../../core/envelope.js';
+import { type CommonOpts } from '../../core/http.js';
+import { type LatestSkill, type RepStatus } from '../../core/roleplay-stats.js';
+import type { ToolDescriptor } from '../tools/types.js';
+import { type FitTextInput } from './text.js';
+import type { AppViewDescriptor } from './types.js';
+export type { Coverage } from '../../commands/roleplay.js';
+export type { LatestSkill, RepStatus } from '../../core/roleplay-stats.js';
+/**
+ * MCP Apps AI Roleplay manager view (PIT-10068): a KPI header and the assignment grid, then drills into one
+ * assignment's reps, one rep's sessions and one session's scorecard. Read-only. Every tool derives from
+ * `loadTeamModel`, the loader `pitcher_roleplay_team` uses, so the view and the text tool never disagree.
+ * The runners live here, not in commands/roleplay.ts: registry.test.ts requires every `run*` of a command
+ * module to back exactly one `allTools` tool, and app tools are not in `allTools` (D25).
+ */
+export declare const roleplayManagerView: AppViewDescriptor;
+/** structuredContent budget per result (the picker's, PIT-10066 D14). */
+export declare const ROLEPLAY_VIEW_MAX_BYTES = 120000;
+/** Model-facing text budget per result, in UTF-8 bytes. */
+export declare const ROLEPLAY_TEXT_MAX_BYTES = 4096;
+export declare const REPS_PAGE_SIZE = 25;
+export declare const REP_SESSIONS_MAX = 50;
+export declare const VIEW_MAX_ASSIGNMENTS = 50;
+export type StatusCounts = Record<RepStatus, number>;
+export type ResultKind = 'overview' | 'assignment-reps' | 'rep-sessions' | 'scorecard' | 'reps' | 'rep-assignments';
+export interface ScopedResult<K extends ResultKind = ResultKind> {
+    kind: K;
+    instanceId: string;
+    scope: CoachScope;
+    coverage: Coverage;
+    /** !coverage.sessionsCapped (D8); an empty bundle is complete. */
+    complete: boolean;
+}
+/** Over ALL scoped assignments, not only the 50 shown. */
+export interface ManagerHeader {
+    assignments: number;
+    reps: number;
+    sessions: number;
+    scoredSessions: number;
+    /**
+     * Raw mean of listed scored assignment sessions, as pitcher_roleplay_team and the manager app compute it (D21).
+     * `overallScore` is 0..100 on every row, legacy 5-point evaluations included (their `grading_scale` applies to
+     * the category scores only), so this never mixes scales.
+     */
+    meanScore: number | null;
+    passedPairs: number;
+    repAssignmentPairs: number;
+    statusCounts: StatusCounts;
+}
+export interface AssignmentSummary {
+    id: string;
+    scenarioName: string | null;
+    type: string;
+    passingScore: number;
+    dueDate: string | null;
+    active: boolean;
+    repCount: number;
+    sessions: number;
+    meanScore: number | null;
+    statusCounts: StatusCounts;
+}
+export interface RepRow {
+    userId: string;
+    name: string | null;
+    status: RepStatus;
+    sessions: number;
+    scoredSessions: number;
+    bestScore: number | null;
+    avgScore: number | null;
+    trend: number | null;
+    lastSessionAt: string | null;
+    recentOnly: boolean;
+    passSource: 'stored' | 'live' | null;
+}
+export interface AssignmentRepsData extends ScopedResult<'assignment-reps'> {
+    assignmentId: string;
+    scenarioName: string | null;
+    status: RepStatus | null;
+    page: number;
+    pageSize: number;
+    totalReps: number;
+    hasMore: boolean;
+    reps: RepRow[];
+}
+export interface ManagerViewData extends ScopedResult<'overview'> {
+    generatedAt: string;
+    header: ManagerHeader;
+    assignments: AssignmentSummary[];
+    totalAssignments: number;
+    /** The input assignmentId, else the only assignment when there is exactly one, else null. */
+    selected: AssignmentRepsData | null;
+    /** The instance attempt was made: true = the server applied scope instance. null = not tried (scope 'coach' sent). */
+    canViewInstance: boolean | null;
+    truncated?: string;
+}
+export interface RepSessionRow {
+    id: string;
+    timestamp: string | null;
+    score: number | null;
+    durationMs: number | null;
+    evaluationStatus: string | null;
+    meetsPassingScore: boolean | null;
+}
+export interface RepSessionsData extends ScopedResult<'rep-sessions'> {
+    assignmentId: string;
+    scenarioName: string | null;
+    passingScore: number;
+    rep: RepRow;
+    latestSkills: {
+        sessionId: string;
+        timestamp: string | null;
+        skills: LatestSkill[];
+    } | null;
+    sessions: RepSessionRow[];
+    totalSessions: number;
+}
+export interface ScorecardCategory {
+    skill_id: string | null;
+    title: string | null;
+    score: number | null;
+    max_score: number | null;
+    feedback: string | null;
+}
+/** pickSessionDetail output, fitted. */
+export interface ScorecardData {
+    kind: 'scorecard';
+    id: string;
+    scenario_name: string | null;
+    difficulty: string | null;
+    timestamp: string | null;
+    duration_ms: number | null;
+    overall_score: number | null;
+    scored: boolean;
+    evaluation_status: string | null;
+    evaluation: {
+        summary: string | null;
+        strengths: string[];
+        improvements: string[];
+        grading_scale: number | null;
+        category_scores: ScorecardCategory[];
+    } | null;
+    truncated?: string;
+}
+/** The roleplay text budget over the shared helper (also used by roleplayReps.ts). */
+export declare const roleplayFitText: (input: FitTextInput) => string;
+/** One decimal, no trailing ".0" (66.66666 -> "66.7"). */
+export declare const fmtNum: (x: number) => string;
+export declare const inRange: (x: number | null) => x is number;
+/** "62/100", "unscored", or the whole token "invalid" when the score or the scale is outside 0..9999. */
+export declare function scoreToken(score: number | null, scale: number | null): string;
+/** "2026-11-02 14:05" in UTC (ASCII), or the fixed "unknown-date --:--". */
+export declare function fmtUtc(ts: string | null | undefined): string;
+export declare const name60: (s: string | null | undefined, fallback: string) => string;
+export declare const STATUS_TEXT: Record<RepStatus, string>;
+/** 8.2 row 9 (also the capped head of the overview text). */
+export declare function cappedSentence(coverage: Coverage): string;
+export declare const emptyCounts: () => StatusCounts;
+export interface AssignmentModel {
+    assignment: CoachAssignment;
+    own: CoachSession[];
+    reps: RepRow[];
+    summary: AssignmentSummary;
+}
+export declare function deriveAssignment(model: TeamModel, a: CoachAssignment, now: Date): AssignmentModel;
+export declare function scoped<K extends ResultKind>(kind: K, instanceId: string, model: TeamModel): ScopedResult<K>;
+export declare const NAME_CHARS = 200;
+/** Clip to `n` code points, "..." included; never leaves a lone surrogate (an emoji renders whole or not at all). */
+export declare function clipChars(s: string, n: number): string;
+/**
+ * Overview: drop `selected` whole first (never a shortened page, whose next page would skip reps; the view then
+ * loads that assignment's first page itself), then assignments from the end. Measured with `truncated` included.
+ */
+export declare function fitRoleplayView(data: ManagerViewData, max?: number): ManagerViewData;
+/**
+ * Drill results keep every row (paging continues after the rows sent), so an oversized one clips its free-text
+ * names instead: rep, scenario and skill names to 200 characters, then to 60; then the rep's skills from the end.
+ */
+export declare function fitAssignmentReps(data: AssignmentRepsData, max?: number): AssignmentRepsData;
+export declare function fitRepSessions(data: RepSessionsData, max?: number): RepSessionsData;
+/**
+ * Scorecard: clip every strength and improvement to 500 characters; then, while the FINAL payload (`truncated`
+ * included) is over budget: drop category feedback from the end, strengths and improvements from the end, clip the
+ * summary to 2000 characters and the names to 200, then drop categories from the end.
+ */
+export declare function fitScorecard(data: ScorecardData, max?: number): ScorecardData;
+export interface ViewOpts extends CommonOpts {
+    instanceId?: string;
+    assignmentId?: string;
+    userId?: string;
+    status?: string;
+    page?: number;
+    scope?: string;
+    entryId?: string;
+}
+export type Deps = {
+    client?: AxiosInstance;
+};
+export declare function checkCommon(opts: ViewOpts): {
+    instanceId: string;
+    scope?: CoachScope;
+    status: RepStatus | null;
+};
+export declare function runRoleplayManagerView(opts: ViewOpts, deps?: Deps): Promise<Envelope<ManagerViewData>>;
+export declare function managerViewText(raw: unknown): string;
+export declare function runRoleplayAssignmentReps(opts: ViewOpts, deps?: Deps): Promise<Envelope<AssignmentRepsData>>;
+export declare function assignmentRepsText(raw: unknown): string;
+export declare function runRoleplayRepSessions(opts: ViewOpts, deps?: Deps): Promise<Envelope<RepSessionsData>>;
+export declare function repSessionsText(raw: unknown): string;
+/** session_get, fitted and tagged for the view (D4). */
+export declare function fitScorecardEnvelope(env: Envelope<unknown>): Envelope<ScorecardData>;
+export declare const runRoleplaySessionScorecard: (opts: ViewOpts, deps?: Deps) => Promise<Envelope<ScorecardData>>;
+export declare function scorecardText(raw: unknown): string;
+export declare const instanceId: z.ZodString;
+export declare const statusEnum: z.ZodEnum<{
+    passed: "passed";
+    in_progress: "in_progress";
+    not_started: "not_started";
+    overdue: "overdue";
+    needs_coaching: "needs_coaching";
+}>;
+export declare const scopeEnum: z.ZodEnum<{
+    instance: "instance";
+    coach: "coach";
+}>;
+export declare const roleplayManagerTools: ToolDescriptor[];