@pitcher/cli-scripts 3.1.1 → 3.3.0

package/dist/src/commands/roleplay.d.ts

@@ -0,0 +1,236 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+import { type AssignmentProgressLike, type RepStatus, type RoleplayAssignmentLike, type RoleplaySessionLike } from '../core/roleplay-stats.js';
+/**
+ * AI Roleplay reads (PIT-9200, Phase 1: read-only). Two sources:
+ * - clickhouse-api `/analytics/roleplay/{kpis,sessions}` (the `roleplay_statements` replica,
+ *   instance or org admins only): `kpis`, `sessions`, `rep-summary`;
+ * - next-core `/core/api/protected/roleplay/coach/*` and appsDB (`cch-*` rows in Postgres):
+ *   `team`, `session`, `scenarios`.
+ * A session with no score is unscored, never 0. Practice Studio takes (`manager-video-practice`)
+ * never appear: the coach routes exclude them by default and `team` drops practice assignments.
+ */
+export interface RoleplayDeps {
+    client?: AxiosInstance;
+}
+export declare const ROLEPLAY_DIFFICULTIES: readonly ["easy", "medium", "hard"];
+export declare const ROLEPLAY_SESSION_SORT: readonly ["session_at", "rep_name", "score", "duration_ms"];
+export declare const ROLEPLAY_GROUP_BY: readonly ["rep", "scenario"];
+export declare const REP_STATUSES: readonly RepStatus[];
+/** rep-summary reads at most this many pages of this size (5000 sessions), newest first. */
+export declare const REP_SUMMARY_PAGE_SIZE = 1000;
+export declare const REP_SUMMARY_MAX_PAGES = 5;
+export declare const REP_SUMMARY_MAX_GROUPS = 50;
+/** next-core's coach/data returns at most this many sessions, newest first, and no total. */
+export declare const COACH_DATA_SESSION_CAP = 1000;
+export declare const TEAM_MAX_ASSIGNMENTS = 50;
+export declare const TEAM_MAX_REPS_PER_ASSIGNMENT = 100;
+/**
+ * Pass progress (PIT-9971) is read in pages of 2000 (assignment, rep) pairs. Above this many pages the
+ * tools use no progress at all (the manager app allows 100,000 pages; one tool call stays bounded).
+ */
+export declare const PROGRESS_MAX_PAGES = 10;
+export interface RoleplayFilterOpts extends CommonOpts {
+    instanceId?: string;
+    startDate?: string;
+    endDate?: string;
+    rep?: string;
+    scenario?: string;
+    difficulty?: string;
+}
+export declare const finiteOrNull: (v: unknown) => number | null;
+/** Totals for the window: sessions, scored/unscored, mean score over SCORED sessions only, active reps. */
+export declare function runRoleplayKpis(opts: RoleplayFilterOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+declare const SESSION_FIELDS: readonly ["entry_id", "session_at", "rep_name", "who", "scenario_name", "persona_name", "difficulty", "score", "evaluated", "rating", "duration_ms"];
+export type RoleplaySessionRow = Record<(typeof SESSION_FIELDS)[number], unknown>;
+/** The row allowlist: nothing else from the replica (provider, recording flags, rubric) leaves. */
+export declare function pickSessionRow(row: Record<string, unknown>): RoleplaySessionRow;
+export interface RoleplaySessionsOpts extends RoleplayFilterOpts {
+    sortBy?: string;
+    sortOrder?: string;
+    limit?: number;
+    page?: number;
+}
+export declare function runRoleplaySessions(opts: RoleplaySessionsOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export interface RoleplayRepSummaryOpts extends RoleplayFilterOpts {
+    groupBy?: string;
+}
+/**
+ * Per-rep (keyed on the rep email `who`) or per-scenario (keyed on `scenario_id`) aggregates over
+ * the sessions list, read in pages of 1000 (newest first) up to 5000. `complete: false` when the
+ * window holds more than that; then the figures cover the newest 5000 only.
+ */
+export declare function runRoleplayRepSummary(opts: RoleplayRepSummaryOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export interface CoachAssignment extends RoleplayAssignmentLike {
+    id: string;
+    scenarioName?: string;
+    active?: boolean;
+    contentType?: string;
+    resolvedUserNames?: Record<string, string>;
+}
+/** A bundle session row: coach/data spreads the appsDB data and adds the entry `id` (transcript stripped). */
+export type CoachSession = RoleplaySessionLike & {
+    id: string;
+    sessionType?: string;
+    evaluationStatus?: string;
+};
+type ProgressEntry = {
+    assignmentId?: unknown;
+    repUserId?: unknown;
+} & Partial<Record<keyof AssignmentProgressLike, unknown>>;
+interface ProgressPage {
+    page: number;
+    pageSize: number;
+    totalPairs: number;
+    hasMore: boolean;
+}
+/** A `cch-manager-comment` row as coach/data returns it: the appsDB data plus the entry `id` (soft-deleted rows excluded). */
+export type CoachComment = Record<string, unknown> & {
+    id: string;
+    managerId?: string | number;
+    managerName?: string;
+    repUserId?: string | number;
+    assignmentId?: string;
+    sessionEntryId?: string | null;
+    comment?: string;
+};
+export interface CoachBundle {
+    scope?: 'instance' | 'coach';
+    assignments?: CoachAssignment[];
+    sessions?: CoachSession[];
+    comments?: CoachComment[];
+    assignmentProgress?: ProgressEntry[];
+    assignmentProgressPage?: ProgressPage;
+}
+export interface RoleplayTeamOpts extends CommonOpts {
+    instanceId?: string;
+    assignmentId?: string;
+    status?: string;
+}
+export type CoachScope = 'instance' | 'coach';
+/** The caller's OWN coaching scope (coach/data without `scope`): what a coach may comment on (PIT-10113). */
+export declare function getOwnCoachBundle(client: AxiosInstance, instanceId: string): Promise<CoachBundle>;
+/** The manager app's progress map key (`useManagerData.ts`). */
+export declare const progressKey: (assignmentId: string, repUserId: string) => string;
+export interface Coverage {
+    sessionsCapped: boolean;
+    progress: 'full' | 'none';
+    /** (assignment, rep) pairs of the roleplay model with no progress entry when progress is full, else 0. */
+    pairsWithoutProgress: number;
+}
+export interface TeamModel {
+    /** The scope the server applied (an older next-core that ignores scope=instance answers 'coach'). */
+    scope: CoachScope;
+    /** The scope this load asked for first: 'coach' when the caller passed scopePref 'coach'. */
+    requested: CoachScope;
+    coverage: Coverage;
+    warnings: string[];
+    /** contentType !== 'practice', D18 order. */
+    assignments: CoachAssignment[];
+    /** sessionType !== 'manager-video-practice'. */
+    sessions: CoachSession[];
+    progress: ReadonlyMap<string, AssignmentProgressLike> | null;
+}
+/** D18 rep order: the reps who need the manager first. */
+export declare const STATUS_RANK: Record<RepStatus, number>;
+/** D18 assignment order: active first, then due date ascending (none last), then scenario name, then id. */
+export declare function compareAssignments(a: CoachAssignment, b: CoachAssignment): number;
+/** D18 rep order: status rank, then name (no name last), then user id. */
+export declare function compareReps(a: {
+    status: RepStatus;
+    name: string | null;
+    user_id: string;
+}, b: {
+    status: RepStatus;
+    name: string | null;
+    user_id: string;
+}): number;
+/**
+ * The one team derivation shared by `roleplay team` and the roleplay manager view (PIT-10068): the
+ * coach bundle, its pass progress, the roleplay filters and the D18 order, so the text tool and the
+ * view always cut the same 50 assignments.
+ */
+export declare function loadTeamModel(client: AxiosInstance, instanceId: string, scopePref?: CoachScope): Promise<TeamModel>;
+/**
+ * Assignment completion per rep, ported from the manager app: an admin gets every roleplay
+ * assignment on the instance (`scope=instance`), anyone else the assignments they coach.
+ * Statuses, session counts and best scores follow `deriveStatus` / `repStats` with the server's
+ * pass progress when it loads (PIT-9971); assignments and reps in D18 order (`loadTeamModel`).
+ * Raw sessions, evaluations and comments never leave.
+ */
+export declare function runRoleplayTeam(opts: RoleplayTeamOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export interface RoleplaySessionGetOpts extends CommonOpts {
+    instanceId?: string;
+    entryId?: string;
+}
+/**
+ * The allowlist, shared by `roleplay session` and the manager view's scorecard. Never the transcript,
+ * messages, contact name, graded snapshot, voice session, recording or audio ids, or any
+ * video-evaluation field. The two scales (`grading_scale`, `max_score`) are numbers only (PIT-10068):
+ * legacy evaluations grade on 5, and a skill score is meaningless without its scale.
+ */
+export declare function pickSessionDetail(id: string, data: Record<string, unknown>): Record<string, unknown>;
+export declare function runRoleplaySessionGet(opts: RoleplaySessionGetOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+/** The trimmed catalog: never the persona prompt or the evaluation prompt. */
+export declare function pickScenario(s: Record<string, unknown>): Record<string, unknown>;
+export declare function runRoleplayScenariosList(opts: CommonOpts & {
+    instanceId?: string;
+}, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export declare const ROLEPLAY_PATH_STATUSES: readonly ["published", "draft", "all"];
+export interface RoleplayPathRow {
+    id: string;
+    name: string;
+    status: string;
+    version: number;
+    stages: number;
+    steps: number;
+    default_passing_score: number | null;
+    updated_at: string | null;
+}
+/** The trimmed path: counts, never the stage/step bodies. */
+export declare function pickPath(p: Record<string, unknown>): RoleplayPathRow;
+/** next-core `GET roleplay/paths` (builder roles; 404 when paths are off or the caller is not a member). */
+export declare function fetchPaths(client: AxiosInstance, instanceId: string, status?: (typeof ROLEPLAY_PATH_STATUSES)[number]): Promise<Record<string, unknown>[]>;
+export declare function runRoleplayPathsList(opts: CommonOpts & {
+    instanceId?: string;
+    status?: string;
+}, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+/** next-core `GET roleplay/path-assignments`: the records in the caller's view (admins get the membership keys). */
+export declare function fetchPathRecords(client: AxiosInstance, instanceId: string): Promise<Record<string, unknown>[]>;
+export declare function postCoachComment(client: AxiosInstance, args: {
+    instanceId: string;
+    assignmentId: string;
+    repUserId: string;
+    sessionEntryId: string | null;
+    comment: string;
+}, idempotencyKey: string): Promise<{
+    body: {
+        id?: string;
+        data?: Record<string, unknown>;
+    };
+    replayed: boolean;
+}>;
+export declare function deleteCoachComment(client: AxiosInstance, args: {
+    instanceId: string;
+    commentId: string;
+}, idempotencyKey: string): Promise<{
+    replayed: boolean;
+}>;
+export declare function postPathAssignment(client: AxiosInstance, instanceId: string, body: {
+    pathId: string;
+    groupIds: string[];
+    recipientUserIds: string[];
+    managerIds: string[];
+    mandatory: boolean;
+    dueDate: string | null;
+}, idempotencyKey: string): Promise<{
+    body: {
+        record?: Record<string, unknown>;
+        warnings?: unknown[];
+    };
+    replayed: boolean;
+}>;
+export declare function createRoleplayCommand(): Command;
+export {};