@pitcher/cli-scripts 3.2.0 → 3.3.0

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

@@ -0,0 +1,509 @@
+import { z } from 'zod';
+import { deleteCoachComment, fetchPathRecords, fetchPaths, getOwnCoachBundle, postCoachComment, postPathAssignment, } from '../../commands/roleplay.js';
+import { runGroupsList } from '../../commands/groups.js';
+import { runUsersGet, runUsersList } from '../../commands/users.js';
+import { createCliError, isCliError } from '../../core/errors.js';
+import { clientFor, toCliError } from '../../core/http.js';
+import { getMeId } from '../../core/me.js';
+import { confirmTextShape, defineConfirmedWrite, nameList, previewName, stripControls } from './confirm/define.js';
+import { CONFIRM_TEXT_MAX } from './confirm/types.js';
+const instanceId = z.string().describe('Instance ID (required)');
+const COMMENT_MAX = 5000; // ROLEPLAY_MAX_COMMENT_LEN, next-core coach-product.const.ts
+const USER_ID = /^[0-9]{1,9}$/; // path-schema.ts userId
+const NAMES_SHOWN = 25;
+const GROUPS_SHOWN = 20;
+const GROUP_PAGES_MAX = 10;
+const USER_PAGES_MAX = 20;
+const LOOKUP_CONCURRENCY = 5;
+const COMMIT_WORDING = 'ONLY after the user explicitly confirmed it. Pass exactly the proposal arguments and proposalToken; any change is ' +
+    'refused. A repeat returns the first result and never saves twice.';
+const client = (auth, deps) => clientFor(auth, (deps ?? {}));
+const asError = (e) => (isCliError(e) ? e : toCliError(e));
+const str = (v) => (typeof v === 'string' ? v : v === undefined || v === null ? '' : String(v));
+/** `items` mapped with at most `limit` calls in flight, in order. */
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
+/** A display name for a user id: Django's `name`, else the email, else "user <id>". */
+async function userName(auth, deps, id) {
+    const env = await runUsersGet({ ...auth, id }, (deps ?? {}));
+    const u = (env.ok ? env.data : undefined);
+    return previewName(str(u?.name).trim() || str(u?.email).trim() || `user ${id}`);
+}
+function dayOf(iso) {
+    const s = str(iso);
+    return /^\d{4}-\d{2}-\d{2}/.test(s) ? s.slice(0, 10) : 'unknown date';
+}
+/** Cut each list's shown names until the text fits CONFIRM_TEXT_MAX; never mid-name (spec 6.4a rule 5). */
+function fitConfirm(build, start) {
+    for (let shown = start; shown >= 0; shown -= 1) {
+        const t = build(shown);
+        if (t.length <= CONFIRM_TEXT_MAX)
+            return t;
+    }
+    return build(0).slice(0, CONFIRM_TEXT_MAX);
+}
+/** The caller's coached roleplay assignment and rep, or AUTH (spec 10.1 step 3). */
+function coachedAssignment(assignments, assignmentId, repUserId) {
+    // the coach bundle is requested with the default roleplay product, so practice rarely occurs; same filter as team
+    const a = (assignments ?? []).filter((x) => x.contentType !== 'practice').find((x) => x.id === assignmentId);
+    if (!a)
+        throw createCliError('AUTH', `You do not coach anyone on assignment ${assignmentId}`);
+    if (!(a.resolvedUserIds ?? []).map(String).includes(repUserId)) {
+        throw createCliError('AUTH', 'You do not coach this rep on this assignment');
+    }
+    return a;
+}
+const repNameOf = (a, repUserId) => previewName(a.resolvedUserNames?.[repUserId] || `rep ${repUserId}`);
+const scenarioOf = (a) => previewName(a.scenarioName || a.scenarioId || a.id);
+export const [commentPropose, commentCommit] = defineConfirmedWrite({
+    action: 'roleplay.comment.create',
+    group: 'roleplay',
+    propose: {
+        name: 'pitcher_roleplay_comment_propose',
+        title: 'Propose a coaching comment',
+        description: 'Prepare a coaching comment from you (a coaching manager) to one rep on one of their AI Roleplay assignments, ' +
+            'optionally about one session. Saves nothing: the user reviews the exact text in a confirm view before ' +
+            'pitcher_roleplay_comment_commit saves it. Take assignmentId and repUserId (user_id) from pitcher_roleplay_team ' +
+            'and sessionEntryId from pitcher_roleplay_sessions. Only a coach of that rep can comment, and only on an ' +
+            "assignment they coach the rep on; instance admins who are not the rep's coach cannot. The rep sees the comment " +
+            "under the user's own name.",
+        inputShape: {
+            instanceId,
+            assignmentId: z.string().describe('Roleplay assignment id (id from pitcher_roleplay_team)'),
+            repUserId: z.string().describe("The rep's user id (user_id from pitcher_roleplay_team)"),
+            sessionEntryId: z.string().optional().describe('One session of that rep (entry_id); omit for a general comment'),
+            comment: z.string().min(1).max(COMMENT_MAX).describe('The comment text, as the rep will read it (plain text, max 5000)'),
+        },
+    },
+    commit: {
+        name: 'pitcher_roleplay_comment_commit',
+        title: 'Post a coaching comment',
+        description: `Save a comment proposed by pitcher_roleplay_comment_propose, ${COMMIT_WORDING}`,
+        argsShape: {
+            confirmText: confirmTextShape,
+            instanceId,
+            assignmentId: z.string(),
+            repUserId: z.string(),
+            sessionEntryId: z.string().nullable(),
+            comment: z.string().min(1).max(COMMENT_MAX),
+        },
+    },
+    editableArg: 'comment',
+    normalize: (a) => ({
+        confirmText: str(a.confirmText).trim(),
+        instanceId: str(a.instanceId),
+        assignmentId: str(a.assignmentId),
+        repUserId: str(a.repUserId),
+        sessionEntryId: a.sessionEntryId === undefined || a.sessionEntryId === null || a.sessionEntryId === '' ? null : str(a.sessionEntryId),
+        comment: str(a.comment).trim(),
+    }),
+    async prepare(input, auth, deps) {
+        const inst = str(input.instanceId);
+        const assignmentId = str(input.assignmentId);
+        const repUserId = str(input.repUserId);
+        const sessionEntryId = str(input.sessionEntryId) || null;
+        const comment = str(input.comment).trim();
+        if (!comment)
+            throw createCliError('VALIDATION', 'comment is empty');
+        if (comment.length > COMMENT_MAX)
+            throw createCliError('VALIDATION', `at most ${COMMENT_MAX} characters`);
+        const c = client(auth, deps);
+        const [actorUserId, bundle, session] = await Promise.all([
+            getMeId(c),
+            getOwnCoachBundle(c, inst),
+            sessionEntryId
+                ? c
+                    .get(`/core/api/protected/roleplay/coach/sessions/${encodeURIComponent(sessionEntryId)}`, {
+                    params: { instance_id: inst },
+                    headers: { 'x-instance-id': inst },
+                })
+                    .then((r) => (r.data ?? {}).data ?? {})
+                : Promise.resolve(null),
+        ]);
+        const assignment = coachedAssignment(bundle.assignments, assignmentId, repUserId);
+        const rep = repNameOf(assignment, repUserId);
+        const scenario = scenarioOf(assignment);
+        const warnings = [];
+        const fields = [
+            { label: 'Rep', value: rep },
+            { label: 'Assignment', value: assignment.dueDate ? `${scenario} (due ${dayOf(assignment.dueDate)})` : scenario },
+        ];
+        let sessionDay = '';
+        if (session) {
+            // a consistency check on rep-written data; the route's authority is the coach check and the args hash
+            if (str(session.userId) !== repUserId)
+                throw createCliError('VALIDATION', `session ${sessionEntryId} belongs to another rep`);
+            if (session.scenarioId && session.scenarioId !== assignment.scenarioId) {
+                warnings.push('This session is from another scenario than the assignment.');
+            }
+            sessionDay = dayOf(session.timestamp);
+            const score = typeof session.overallScore === 'number' && Number.isFinite(session.overallScore) ? `${session.overallScore}` : 'unscored';
+            fields.push({ label: 'Session', value: `${previewName(session.scenarioName || scenario)}, ${sessionDay}, score ${score}` });
+        }
+        const confirmText = `Post a coaching comment from you to ${rep} on '${scenario}'${sessionDay ? ` about the session of ${sessionDay}` : ''}. ` +
+            `${rep} sees it under your name.`;
+        const preview = {
+            title: 'Post a coaching comment',
+            summary: `A coaching comment to ${rep} on '${scenario}'.`,
+            fields,
+            body: { label: 'Comment', text: comment, editable: true, maxLength: COMMENT_MAX, argKey: 'comment' },
+            notices: [`${rep} sees this comment under your name and is asked to acknowledge it.`],
+            warnings,
+            confirmLabel: 'Post comment',
+        };
+        return {
+            actorUserId,
+            preview,
+            args: { confirmText, instanceId: inst, assignmentId, repUserId, sessionEntryId, comment },
+        };
+    },
+    async execute(args, key, auth, deps) {
+        const { body, replayed } = await postCoachComment(client(auth, deps), args, key);
+        return {
+            replayed,
+            result: {
+                id: str(body.id),
+                repUserId: args.repUserId,
+                assignmentId: args.assignmentId,
+                sessionEntryId: args.sessionEntryId,
+                timestamp: typeof body.data?.timestamp === 'string' ? body.data.timestamp : null,
+            },
+        };
+    },
+    resultText: (r) => `comment ${r.id} posted for rep ${r.repUserId} on assignment ${r.assignmentId}.`,
+});
+export const [commentDeletePropose, commentDeleteCommit] = defineConfirmedWrite({
+    action: 'roleplay.comment.delete',
+    group: 'roleplay',
+    propose: {
+        name: 'pitcher_roleplay_comment_delete_propose',
+        title: 'Propose deleting a coaching comment',
+        description: 'Prepare deleting one of YOUR OWN AI Roleplay coaching comments (the undo for a mistaken post). Saves nothing: the ' +
+            'user confirms in a confirm view before pitcher_roleplay_comment_delete_commit deletes it. You can delete only ' +
+            'comments you wrote; the rep no longer sees a deleted comment.',
+        inputShape: { instanceId, commentId: z.string().describe('The comment id (the id a comment commit returned)') },
+    },
+    commit: {
+        name: 'pitcher_roleplay_comment_delete_commit',
+        title: 'Delete a coaching comment',
+        description: `Delete a comment proposed by pitcher_roleplay_comment_delete_propose, ${COMMIT_WORDING}`,
+        argsShape: { confirmText: confirmTextShape, instanceId, commentId: z.string() },
+    },
+    normalize: (a) => ({ confirmText: str(a.confirmText).trim(), instanceId: str(a.instanceId), commentId: str(a.commentId) }),
+    async prepare(input, auth, deps) {
+        const inst = str(input.instanceId);
+        const commentId = str(input.commentId);
+        const c = client(auth, deps);
+        const [actorUserId, bundle] = await Promise.all([getMeId(c), getOwnCoachBundle(c, inst)]);
+        const row = (bundle.comments ?? []).find((x) => x.id === commentId);
+        if (!row)
+            throw createCliError('NOT_FOUND', `comment ${commentId} not found among the comments you can see (or already deleted)`);
+        if (str(row.managerId) !== actorUserId)
+            throw createCliError('AUTH', 'You can delete only your own comments');
+        const repUserId = str(row.repUserId);
+        const assignment = (bundle.assignments ?? []).find((a) => a.id === str(row.assignmentId));
+        const rep = assignment ? repNameOf(assignment, repUserId) : previewName(`rep ${repUserId}`);
+        const scenario = assignment ? scenarioOf(assignment) : previewName(str(row.assignmentId));
+        const text = stripControls(str(row.comment));
+        const confirmText = `Delete your comment to ${rep} on '${scenario}': '${previewName(text, 120)}'.`;
+        return {
+            actorUserId,
+            args: { confirmText, instanceId: inst, commentId },
+            preview: {
+                title: 'Delete a coaching comment',
+                summary: `Delete your comment to ${rep} on '${scenario}'.`,
+                fields: [
+                    { label: 'Rep', value: rep },
+                    { label: 'Assignment', value: scenario },
+                    { label: 'Comment', value: previewName(text) },
+                ],
+                notices: ['The rep no longer sees this comment.'],
+                warnings: [],
+                confirmLabel: 'Delete comment',
+            },
+        };
+    },
+    async execute(args, key, auth, deps) {
+        const { replayed } = await deleteCoachComment(client(auth, deps), args, key);
+        return { replayed, result: { id: args.commentId, deleted: true } };
+    },
+    resultText: (r) => `comment ${r.id} deleted.`,
+});
+const sortedUnique = (v) => (Array.isArray(v) ? [...new Set(v.map(str))].sort() : []);
+/** next-core's `isoDate` (path-schema.ts): YYYY-MM-DD that prints back as itself. */
+function isRealDate(v) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(v))
+        return false;
+    const d = new Date(`${v}T00:00:00Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === v;
+}
+/** The paths-route refusals, worded for the user (spec 10.2 step 3). */
+function pathsError(e) {
+    const err = asError(e);
+    if (err.code === 'NOT_FOUND') {
+        return createCliError('NOT_FOUND', 'Learning paths are not enabled on this instance, or you are not a member of it', err.backendStatus);
+    }
+    if (err.backendStatus === 503)
+        return createCliError('NETWORK', 'Learning paths are temporarily unavailable', 503);
+    if (err.code === 'AUTH') {
+        return createCliError('AUTH', 'Only instance admins and editors, and org admins, can assign paths', err.backendStatus);
+    }
+    return err;
+}
+/** Group names by id, paging the instance's groups until every id is found (W9: unknown ids are refused). */
+async function groupNames(auth, deps, inst, ids) {
+    const found = new Map();
+    if (ids.length === 0)
+        return found;
+    const wanted = new Set(ids);
+    // bounded (spec W9: at most 10 pages of 500); past the bound an id is "not verified", never "not a group"
+    let more = false;
+    for (let page = 1; page <= GROUP_PAGES_MAX && found.size < wanted.size; page += 1) {
+        const env = await runGroupsList({ ...auth, instanceId: inst, pageSize: 500, page }, (deps ?? {}));
+        if (!env.ok)
+            throw createCliError(env.error.code, env.error.message, env.error.backendStatus);
+        for (const g of env.data.results) {
+            const id = str(g.id);
+            if (wanted.has(id))
+                found.set(id, previewName(str(g.name) || id));
+        }
+        more = !!env.data.pagination.next;
+        if (!more)
+            break;
+    }
+    const unknown = ids.filter((id) => !found.has(id));
+    if (unknown.length && more) {
+        throw createCliError('VALIDATION', `could not find these groups in the first ${GROUP_PAGES_MAX * 500} groups of this instance: ${unknown.join(', ')}`);
+    }
+    if (unknown.length)
+        throw createCliError('VALIDATION', `not groups of this instance: ${unknown.join(', ')}`);
+    return found;
+}
+/**
+ * Managers who are reps (spec 10.2 step 6a, K11 as amended 2026-11-11): Django has no `rep` instance role (`admin`,
+ * `editor`, `member`, and an unknown role is a 400), so a rep is an instance `member` who is not an org admin, as
+ * next-core's `sqlIsPathRep` decides. Advisory: any failure returns null and the warning is skipped.
+ */
+async function membersAmong(auth, deps, inst, managerIds) {
+    try {
+        const wanted = new Set(managerIds);
+        const out = new Map();
+        for (let page = 1; page <= USER_PAGES_MAX; page += 1) {
+            const env = await runUsersList({ ...auth, instanceId: inst, instanceRole: 'member', pageSize: 500, page }, (deps ?? {}));
+            if (!env.ok)
+                return null;
+            for (const u of env.data.results) {
+                const id = str(u.id);
+                if (wanted.has(id) && u.role !== 'admin')
+                    out.set(id, previewName(str(u.name) || str(u.email) || `user ${id}`));
+            }
+            if (!env.data.pagination.next)
+                return out;
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+export const [pathPropose, pathCommit] = defineConfirmedWrite({
+    action: 'roleplay.path_assignment.create',
+    group: 'roleplay',
+    propose: {
+        name: 'pitcher_roleplay_path_assignment_propose',
+        title: 'Propose a learning path assignment',
+        description: 'Prepare assigning a published AI Roleplay learning path to reps and/or content-distribution groups, with the ' +
+            'managers who coach it and an optional due date. Saves nothing until the user confirms in a confirm view and ' +
+            'pitcher_roleplay_path_assignment_commit runs. Instance admins and editors and org admins only; learning paths ' +
+            'must be enabled on the instance. Find pathId with pitcher_roleplay_paths_list, groupIds with pitcher_groups_list ' +
+            'and user ids with pitcher_users_list. Every manager named here can see, comment on and evaluate the roleplay ' +
+            'sessions and recordings of every rep on the assignment, including reps who join its groups later, until the ' +
+            'assignment is deleted. Only an admin may name themselves.',
+        inputShape: {
+            instanceId,
+            pathId: z.string().describe('Published path id (from pitcher_roleplay_paths_list)'),
+            groupIds: z.array(z.string()).max(200).optional().describe('Content-distribution group ids; their reps get the path'),
+            recipientUserIds: z.array(z.string()).max(500).optional().describe('Rep user ids (reps only)'),
+            managerIds: z.array(z.string()).min(1).max(200).describe('User ids of the managers who coach this assignment (at least one)'),
+            dueDate: z.string().optional().describe('Due date YYYY-MM-DD; omit for none'),
+            mandatory: z.boolean().optional().describe('Mark the path mandatory (default false)'),
+        },
+    },
+    commit: {
+        name: 'pitcher_roleplay_path_assignment_commit',
+        title: 'Assign a learning path',
+        description: `Save a path assignment proposed by pitcher_roleplay_path_assignment_propose, ${COMMIT_WORDING}`,
+        argsShape: {
+            confirmText: confirmTextShape,
+            instanceId,
+            pathId: z.string(),
+            groupIds: z.array(z.string()),
+            recipientUserIds: z.array(z.string()),
+            managerIds: z.array(z.string()),
+            mandatory: z.boolean(),
+            dueDate: z.string().nullable(),
+        },
+    },
+    normalize: (a) => ({
+        confirmText: str(a.confirmText).trim(),
+        instanceId: str(a.instanceId),
+        pathId: str(a.pathId),
+        groupIds: sortedUnique(a.groupIds),
+        recipientUserIds: sortedUnique(a.recipientUserIds),
+        managerIds: sortedUnique(a.managerIds),
+        mandatory: a.mandatory === true,
+        dueDate: a.dueDate === undefined || a.dueDate === null || a.dueDate === '' ? null : str(a.dueDate),
+    }),
+    async prepare(input, auth, deps) {
+        const inst = str(input.instanceId);
+        const pathId = str(input.pathId);
+        const groupIds = sortedUnique(input.groupIds);
+        const recipientUserIds = sortedUnique(input.recipientUserIds);
+        const managerIds = sortedUnique(input.managerIds);
+        const dueDate = str(input.dueDate) || null;
+        const mandatory = input.mandatory === true;
+        // local checks first: no call for a request the route would refuse anyway
+        if (groupIds.length === 0 && recipientUserIds.length === 0)
+            throw createCliError('VALIDATION', 'name at least one group or rep');
+        const badIds = [...recipientUserIds, ...managerIds].filter((id) => !USER_ID.test(id));
+        if (badIds.length)
+            throw createCliError('VALIDATION', `not user ids: ${badIds.join(', ')}`);
+        if (dueDate !== null && !isRealDate(dueDate))
+            throw createCliError('VALIDATION', 'dueDate must be a real date, YYYY-MM-DD');
+        const c = client(auth, deps);
+        const [actorUserId, paths, groups, managerNames, repNames, records, members] = await Promise.all([
+            getMeId(c),
+            fetchPaths(c, inst, 'published').catch((e) => {
+                throw pathsError(e);
+            }),
+            groupNames(auth, deps, inst, groupIds),
+            mapLimit(managerIds.slice(0, NAMES_SHOWN), LOOKUP_CONCURRENCY, (id) => userName(auth, deps, id)),
+            mapLimit(recipientUserIds.slice(0, NAMES_SHOWN), LOOKUP_CONCURRENCY, (id) => userName(auth, deps, id)),
+            fetchPathRecords(c, inst).catch((e) => {
+                throw pathsError(e);
+            }),
+            membersAmong(auth, deps, inst, managerIds),
+        ]);
+        const path = paths.find((p) => str(p.id) === pathId);
+        if (!path)
+            throw createCliError('VALIDATION', `path ${pathId} is not a published path on this instance`);
+        const warnings = [];
+        const notices = [];
+        if (dueDate !== null && dueDate < new Date().toISOString().slice(0, 10))
+            warnings.push(`The due date ${dueDate} is in the past.`);
+        const overlap = records.filter((r) => str(r.pathId) === pathId && r.active !== false).length;
+        if (overlap > 0)
+            warnings.push(`This path already has ${overlap} active assignments on this instance; reps on both keep one path.`);
+        if (managerIds.includes(actorUserId)) {
+            // an admin's view carries the membership keys (path-views.ts); an editor's does not
+            if (records.length === 0) {
+                notices.push('You are named as a manager. Only an admin may do this; if you are an editor, saving fails.');
+            }
+            else if (!records.some((r) => 'resolvedUserIds' in r)) {
+                throw createCliError('AUTH', 'Only an admin may name themselves as a manager');
+            }
+        }
+        const managerName = (id) => {
+            const i = managerIds.indexOf(id);
+            return i >= 0 && i < managerNames.length ? managerNames[i] : previewName(`user ${id}`);
+        };
+        for (const id of managerIds) {
+            if (recipientUserIds.includes(id) || members?.has(id)) {
+                warnings.push(`${members?.get(id) ?? managerName(id)} is a rep; naming them as manager gives them access to the other reps' sessions and recordings.`);
+            }
+        }
+        const pathName = previewName(str(path.name) || pathId);
+        const version = typeof path.version === 'number' ? path.version : 0;
+        const stages = Array.isArray(path.stages) ? path.stages.length : 0;
+        const steps = Array.isArray(path.steps) ? path.steps.length : 0;
+        const groupList = groupIds.map((id) => groups.get(id));
+        const allManagers = [...managerNames, ...Array(Math.max(0, managerIds.length - managerNames.length)).fill('')];
+        const managersShown = (n) => nameList(allManagers.slice(0, managerNames.length), n).concat(managerIds.length > managerNames.length && n >= managerNames.length ? ` and ${managerIds.length - managerNames.length} more` : '');
+        const repsShown = (n) => {
+            if (recipientUserIds.length === 0)
+                return '';
+            const shown = repNames.slice(0, Math.min(n, repNames.length));
+            const more = recipientUserIds.length - shown.length;
+            return shown.length ? `: ${shown.join(', ')}${more ? `, and ${more} more` : ''}` : '';
+        };
+        const due = dueDate ? `Due ${dueDate}` : "Due 'no due date'";
+        const confirmText = fitConfirm((n) => {
+            const audience = [
+                groupList.length ? `groups ${nameList(groupList, n)}` : '',
+                recipientUserIds.length ? `${recipientUserIds.length} reps${repsShown(Math.min(n, 10))}` : '',
+            ]
+                .filter(Boolean)
+                .join(' and ');
+            return (`Assign '${pathName}' (v${version}) to ${audience}. Managers ${managersShown(n)} get access to see, comment on and ` +
+                'evaluate the roleplay sessions and recordings of every rep on it, including reps who join these groups later, ' +
+                `until it is deleted. ${due}${mandatory ? ', mandatory' : ''}.`);
+        }, Math.max(groupList.length, managerNames.length, 10));
+        const fields = [
+            { label: 'Path', value: `${pathName} (v${version}), ${stages} stages, ${steps} steps` },
+            { label: 'Groups', value: groupList.length ? nameList(groupList, GROUPS_SHOWN) : 'None' },
+            {
+                label: 'Reps',
+                value: recipientUserIds.length
+                    ? `${repNames.join(', ')}${recipientUserIds.length > repNames.length ? ` and ${recipientUserIds.length - repNames.length} more` : ''}`
+                    : 'None',
+            },
+            {
+                label: 'Managers',
+                value: `${managerNames.join(', ')}${managerIds.length > managerNames.length ? ` and ${managerIds.length - managerNames.length} more` : ''}`,
+            },
+            { label: 'Due date', value: dueDate ?? 'None' },
+            { label: 'Mandatory', value: mandatory ? 'Yes' : 'No' },
+        ];
+        notices.unshift('The managers listed above will be able to see, comment on and evaluate the roleplay sessions and recordings of ' +
+            'every rep on this assignment, including reps added to these groups later, until the assignment is deleted (or ' +
+            'the rep leaves these groups, or paths are turned off). Deactivating it does not remove this access.', 'Reps in these groups get the path while they are members, including reps who join later. The current rep count is shown after saving.');
+        return {
+            actorUserId,
+            args: { confirmText, instanceId: inst, pathId, groupIds, recipientUserIds, managerIds, mandatory, dueDate },
+            preview: { title: 'Assign a learning path', summary: `Assign '${pathName}' to the groups and reps below.`, fields, notices, warnings, confirmLabel: 'Assign path' },
+        };
+    },
+    async execute(args, key, auth, deps) {
+        const { body, replayed } = await postPathAssignment(client(auth, deps), args.instanceId, args, key);
+        const record = body.record ?? {};
+        const snapshot = (record.pathSnapshot ?? {});
+        const resolved = record.resolvedUserIds;
+        const warnings = (Array.isArray(body.warnings) ? body.warnings : []).map((w) => {
+            const x = w;
+            return x.code === 'overlapping_record' ? `${str(x.count)} reps already had this path from another assignment` : str(x.code);
+        });
+        return {
+            replayed,
+            result: {
+                id: str(record.id),
+                pathName: str(snapshot.name),
+                groupNames: Array.isArray(record.groupNames) ? record.groupNames.map(str) : [],
+                resolvedReps: Array.isArray(resolved) ? resolved.length : null,
+                dueDate: args.dueDate,
+                mandatory: args.mandatory,
+                warnings,
+            },
+        };
+    },
+    resultText: (r) => `path '${r.pathName}' assigned (assignment ${r.id})${r.resolvedReps !== null ? ` to ${r.resolvedReps} reps` : ''}` +
+        `${r.warnings.length ? `; ${r.warnings.join('; ')}` : ''}.`,
+});
+/** The six confirm tools (PIT-10113), registered in `apps/registry.ts` with the write-confirm view. */
+export const roleplayWriteTools = [
+    commentPropose,
+    commentCommit,
+    commentDeletePropose,
+    commentDeleteCommit,
+    pathPropose,
+    pathCommit,
+];

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

@@ -0,0 +1,41 @@
+/**
+ * Model-facing text helpers shared by the MCP Apps views (PIT-10068 7.3, reused by PIT-10067 7.3). Every size is
+ * in UTF-8 BYTES, never characters: a CJK name is 3 bytes a character, and the hosts' text limits are bytes.
+ */
+/** Default budget of one tool's model text, in bytes. */
+export declare const APP_TEXT_MAX_BYTES = 4096;
+/** Default bytes kept free for the "more" line. */
+export declare const MORE_RESERVED_BYTES = 120;
+export declare const byteLen: (s: string) => number;
+export declare const jsonBytes: (v: unknown) => number;
+/** Clip to at most `maxBytes` UTF-8 bytes, "..." included, never splitting a code point. */
+export declare function clipBytes(s: string, maxBytes: number): string;
+export interface FitTextInput {
+    heads: {
+        text: string;
+        maxBytes: number;
+    }[];
+    body: {
+        text: string;
+        kind?: string;
+    }[];
+    /** Items that never entered the body (sessions beyond 50, viewers on later pages). */
+    hidden?: number;
+    more: (d: {
+        lines: number;
+        hidden: number;
+        kinds: string[];
+    }) => string;
+    /** Whole-text budget. Default APP_TEXT_MAX_BYTES. */
+    maxBytes?: number;
+    /** Bytes kept free for the `more` line, which is clipped to fit them. Default MORE_RESERVED_BYTES. */
+    reserve?: number;
+}
+/**
+ * Heads (each clipped to its own cap), then body lines in order while the running size plus the bytes reserved
+ * for the `more` line fits `maxBytes`; `more` when anything was left out. A body line enters whole or not at all.
+ * Every head has a cap, so the total never exceeds the budget and the 8 KB clamp in result.ts never triggers.
+ */
+export declare function fitText({ heads, body, hidden, more, maxBytes, reserve, }: FitTextInput): string;
+/** A list head: entries dropped from the end until it fits, with "and N more"; `fallback` when none fits. */
+export declare function listHead(prefix: string, entries: string[], total: number, maxBytes: number, fallback: string): string;

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

@@ -0,0 +1,58 @@
+/**
+ * Model-facing text helpers shared by the MCP Apps views (PIT-10068 7.3, reused by PIT-10067 7.3). Every size is
+ * in UTF-8 BYTES, never characters: a CJK name is 3 bytes a character, and the hosts' text limits are bytes.
+ */
+/** Default budget of one tool's model text, in bytes. */
+export const APP_TEXT_MAX_BYTES = 4096;
+/** Default bytes kept free for the "more" line. */
+export const MORE_RESERVED_BYTES = 120;
+export const byteLen = (s) => Buffer.byteLength(s, 'utf8');
+export const jsonBytes = (v) => byteLen(JSON.stringify(v));
+/** Clip to at most `maxBytes` UTF-8 bytes, "..." included, never splitting a code point. */
+export function clipBytes(s, maxBytes) {
+    if (byteLen(s) <= maxBytes)
+        return s;
+    let out = '';
+    let used = 0;
+    for (const cp of Array.from(s)) {
+        const b = byteLen(cp);
+        if (used + b + 3 > maxBytes)
+            break;
+        out += cp;
+        used += b;
+    }
+    return `${out}...`;
+}
+/**
+ * Heads (each clipped to its own cap), then body lines in order while the running size plus the bytes reserved
+ * for the `more` line fits `maxBytes`; `more` when anything was left out. A body line enters whole or not at all.
+ * Every head has a cap, so the total never exceeds the budget and the 8 KB clamp in result.ts never triggers.
+ */
+export function fitText({ heads, body, hidden = 0, more, maxBytes = APP_TEXT_MAX_BYTES, reserve = MORE_RESERVED_BYTES, }) {
+    const lines = heads.filter((h) => h.text).map((h) => clipBytes(h.text, h.maxBytes));
+    let used = lines.reduce((n, l, i) => n + byteLen(l) + (i ? 1 : 0), 0);
+    let i = 0;
+    for (; i < body.length; i += 1) {
+        const add = byteLen(body[i].text) + (lines.length ? 1 : 0);
+        if (used + add + reserve > maxBytes)
+            break;
+        lines.push(body[i].text);
+        used += add;
+    }
+    const left = body.slice(i);
+    if (left.length + hidden > 0) {
+        const kinds = Array.from(new Set(left.map((l) => l.kind).filter((k) => !!k)));
+        lines.push(clipBytes(more({ lines: left.length, hidden, kinds }), reserve - 1));
+    }
+    return lines.join('\n');
+}
+/** A list head: entries dropped from the end until it fits, with "and N more"; `fallback` when none fits. */
+export function listHead(prefix, entries, total, maxBytes, fallback) {
+    for (let n = entries.length; n >= 0; n -= 1) {
+        const rest = total - n;
+        const text = `${prefix}${entries.slice(0, n).join('; ')}${rest > 0 ? `${n ? '; ' : ''}and ${rest} more` : ''}.`;
+        if (byteLen(text) <= maxBytes)
+            return text;
+    }
+    return clipBytes(fallback, maxBytes);
+}

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

@@ -0,0 +1,23 @@
+import type { McpRunContext } from '../server.js';
+/** Content-Security-Policy origins a view may load from (ext-apps `_meta.ui.csp`). */
+export interface AppCsp {
+    resourceDomains?: string[];
+    connectDomains?: string[];
+}
+/** One MCP Apps view, served as the `ui://pitcher/<name>.html` resource (PIT-10066). */
+export interface AppViewDescriptor {
+    name: string;
+    title: string;
+    description: string;
+    /** CSP for this view, from the per-request context. Default: block all external origins. */
+    csp?: (ctx: McpRunContext) => AppCsp;
+    /** Sandbox permissions the view asks for (host may refuse; the view feature-detects). */
+    permissions?: {
+        clipboardWrite?: Record<string, never>;
+    };
+    /** Ask the host to draw a border around the view. Default true. */
+    prefersBorder?: boolean;
+}
+export declare const appViewUri: (name: string) => string;
+/** Origin of the org domain the request runs against, for img-src. [] when the context has no url (local). */
+export declare function orgOrigin(ctx: McpRunContext): string[];

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

@@ -0,0 +1,12 @@
+export const appViewUri = (name) => `ui://pitcher/${name}.html`;
+/** Origin of the org domain the request runs against, for img-src. [] when the context has no url (local). */
+export function orgOrigin(ctx) {
+    if (!ctx.url)
+        return [];
+    try {
+        return [new URL(ctx.url).origin];
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { AppViewDescriptor } from './types.js';
+/** PIT-10113: the Pitcher-owned confirm view every confirmed write renders in MCP Apps hosts. */
+export declare const writeConfirmView: AppViewDescriptor;

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

@@ -0,0 +1,8 @@
+import { WRITE_CONFIRM_VIEW } from './confirm/define.js';
+/** PIT-10113: the Pitcher-owned confirm view every confirmed write renders in MCP Apps hosts. */
+export const writeConfirmView = {
+    name: WRITE_CONFIRM_VIEW,
+    title: 'Pitcher confirm',
+    description: 'Review and confirm a Pitcher change before it is saved.',
+    // csp omitted: block all external origins (text only)
+};