@pitcher/cli-scripts 3.1.1 → 3.3.0

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

@@ -0,0 +1,737 @@
+import { z } from 'zod';
+import { aggregateFiles, compressRanges, dedupeIdentities, densePages, fmtDuration, naiveDate, naiveMinute, pageCountFor, realNames, toHeader, toViewerRow, ULID, unavailableOf, classifyItem, fileFallbackName, } from '../../core/dsr-engagement.js';
+import { summarizeVisits } from '../../core/dsr-visits.js';
+import { ok, fail } from '../../core/envelope.js';
+import { createCliError, isCliError } from '../../core/errors.js';
+import { clickhouseClientFor, toCliError } from '../../core/http.js';
+import { byteLen, clipBytes, fitText, jsonBytes, listHead } from './text.js';
+import { orgOrigin } from './types.js';
+/**
+ * MCP Apps DSR engagement view (PIT-10067): who opened a DSR canvas, one viewer's visit timeline, and time per page
+ * of each file, plus a Content tab over a stated sample of the most recently active viewers. Read-only. Every read
+ * runs with the caller's own credential through clickhouse-api, which re-checks canvas access per call (the canvas
+ * fetch is the gate), so a user sees exactly the viewers Sharing Analytics shows them. The runners live here, not
+ * in commands/analytics.ts: registry.test.ts pins one `run*` per CLI tool, and app tools are not CLI tools.
+ */
+export const dsrEngagementView = {
+    name: 'dsr-engagement',
+    title: 'Pitcher DSR engagement',
+    description: 'Who opened a DSR, their visits, and time per page of each file.',
+    csp: (ctx) => ({ resourceDomains: orgOrigin(ctx) }), // file thumbnails only, as the picker
+};
+/** structuredContent budget per result (the picker's, PIT-10066 D14). */
+export const DSR_VIEW_MAX_BYTES = 120000;
+/** Model-facing text budget per result, in UTF-8 bytes. */
+export const DSR_TEXT_MAX_BYTES = 4096;
+/** The "more" line's floor reserve (7.3); each text sizes it up to its own longest continuation. */
+const DSR_MORE_MIN_RESERVE = 160;
+export const VIEWERS_PAGE_SIZE = 25;
+export const VIEWER_VISITS_MAX = 50;
+export const VISIT_ITEMS_MAX = 60;
+export const FILE_META_MAX = 200;
+const FILE_META_CHUNK = 50; // the thumbnails route's own 1..50 cap
+const FILE_META_CONCURRENCY = 2;
+export const CONTENT_MAX_VIEWERS = 15;
+export const CONTENT_CONCURRENCY = 3;
+export const CONTENT_DEADLINE_MS = 20000;
+const CONTENT_META_MIN_REMAINING_MS = 2000;
+export const VIEWER_DEADLINE_MS = 25000;
+const VIEWER_META_MAX_ELAPSED_MS = 10000;
+const TEXT_VISITS_IN_OVERVIEW = 10;
+const VIEWER_TYPES = ['external', 'internal', 'all'];
+const WINDOWS = ['30d', '90d', '365d'];
+const SORTS = ['last_active', 'total_engagement_time', 'session_count'];
+const WINDOW_DAYS = { '30d': 30, '90d': 90, '365d': 365 };
+/** `today (UTC) - N days` as YYYY-MM-DD; null for 365d, which sends no dates (the route's default). */
+export function windowStart(w, nowMs) {
+    if (w === '365d')
+        return null;
+    const d = new Date(nowMs);
+    return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) - WINDOW_DAYS[w] * 86400000)
+        .toISOString()
+        .slice(0, 10);
+}
+function scopeOf(opts, nowMs) {
+    if (!opts.instanceId)
+        throw createCliError('VALIDATION', 'instanceId is required');
+    if (!opts.canvasId)
+        throw createCliError('VALIDATION', 'canvasId is required');
+    const viewerType = (opts.viewerType ?? 'external');
+    if (!VIEWER_TYPES.includes(viewerType))
+        throw createCliError('VALIDATION', `viewerType must be one of: ${VIEWER_TYPES.join(', ')}`);
+    const window = (opts.window ?? '30d');
+    if (!WINDOWS.includes(window))
+        throw createCliError('VALIDATION', `window must be one of: ${WINDOWS.join(', ')}`);
+    return { instanceId: opts.instanceId, canvasId: opts.canvasId, viewerType, window, startDate: windowStart(window, nowMs) };
+}
+function identityOf(v, label) {
+    if (typeof v !== 'string' || v.length < 1 || v.length > 1024) {
+        throw createCliError('VALIDATION', `${label} must be 1 to 1024 characters`);
+    }
+    return v;
+}
+const clockOf = (deps) => deps.now ?? Date.now;
+const abortOf = (deps) => deps.abortAfter ?? ((ms) => AbortSignal.timeout(ms));
+const deadlineError = () => createCliError('NETWORK', 'Timed out loading DSR engagement data; try again');
+/** A request cut by the run's deadline rejects as axios `canceled`: say what happened instead (PR 6010 review). */
+const underDeadline = (p, signal) => p.catch((e) => {
+    throw signal.aborted ? deadlineError() : e;
+});
+/** Run `fn` over `items` with at most `n` in flight; never rejects. A falsy `canStart()` settles the rest unstarted. */
+async function pool(items, n, fn, canStart = () => true) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            if (!canStart()) {
+                out[i] = { status: 'rejected', reason: deadlineError() };
+                continue;
+            }
+            try {
+                out[i] = { status: 'fulfilled', value: await fn(items[i]) };
+            }
+            catch (reason) {
+                out[i] = { status: 'rejected', reason };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
+    return out;
+}
+async function readViewers(client, scope, q = {}) {
+    const page = q.page ?? 1;
+    const params = {
+        instance_id: scope.instanceId,
+        canvas_id: scope.canvasId,
+        viewer_type: scope.viewerType,
+        page,
+        page_size: VIEWERS_PAGE_SIZE,
+        sort_by: q.sortBy ?? 'last_active',
+        sort_order: 'desc',
+    };
+    if (q.search)
+        params.search = q.search;
+    if (scope.startDate)
+        params.start_date = scope.startDate;
+    const res = await client.get('/analytics/canvas-details/viewers', { params, ...(q.signal ? { signal: q.signal } : {}) });
+    const native = (res.data && typeof res.data === 'object' ? res.data : {});
+    const list = (native.viewers ?? {});
+    const rows = (Array.isArray(list.items) ? list.items : []).map((r) => toViewerRow((r ?? {})));
+    const total = Math.max(Number(list.total) || 0, rows.length);
+    return {
+        native,
+        page: { rows, total, page, hasMore: (page - 1) * VIEWERS_PAGE_SIZE + rows.length < total },
+        unavailable: unavailableOf(native),
+    };
+}
+async function readTimeline(client, scope, identity, signal) {
+    const params = { instance_id: scope.instanceId, canvas_id: scope.canvasId, user_email: identity };
+    if (scope.startDate)
+        params.start_date = scope.startDate;
+    const res = await client.get('/analytics/canvas-details/sessions', { params, signal });
+    const events = ((res.data ?? {}).events ?? []);
+    const list = Array.isArray(events) ? events : [];
+    const names = realNames(list);
+    return { key: identity, visits: summarizeVisits(list, scope.canvasId), names, canvasName: names[scope.canvasId] ?? null };
+}
+/**
+ * Thumbnail and page metadata for up to FILE_META_MAX ULID files (in the given order), 50 per call to the
+ * clickhouse-api thumbnails route (Django `files/?id__in` as the caller, so only readable files come back), two
+ * calls in flight. A failed chunk leaves its files without meta, silently.
+ */
+async function readFileMeta(client, instanceId, fileIds, signal) {
+    const ids = Array.from(new Set(fileIds)).filter((id) => ULID.test(id));
+    const take = ids.slice(0, FILE_META_MAX);
+    const chunks = [];
+    for (let i = 0; i < take.length; i += FILE_META_CHUNK)
+        chunks.push(take.slice(i, i + FILE_META_CHUNK));
+    const settled = await pool(chunks, FILE_META_CONCURRENCY, (chunk) => client.get('/analytics/canvas-details/thumbnails', { params: { file_ids: chunk.join(','), instance_id: instanceId }, signal }), () => !signal.aborted);
+    const meta = new Map();
+    for (const s of settled) {
+        if (s.status !== 'fulfilled')
+            continue;
+        const files = (s.value?.data ?? {}).files;
+        for (const f of Array.isArray(files) ? files : []) {
+            const r = (f ?? {});
+            if (typeof r.id !== 'string')
+                continue;
+            meta.set(r.id, {
+                thumbnailUrl: typeof r.thumbnail_url === 'string' && r.thumbnail_url ? r.thumbnail_url : null,
+                contentType: typeof r.content_type === 'string' ? r.content_type : null,
+                contentLength: typeof r.content_length === 'number' ? r.content_length : null,
+                thumbCount: Array.isArray(r.content_thumbnails) ? r.content_thumbnails.length : 0,
+            });
+        }
+    }
+    return { meta, truncated: ids.length - take.length };
+}
+// ── shaping ──────────────────────────────────────────────────────────────────
+function toFileStat(f, meta) {
+    const { pageCount, dense } = pageCountFor(meta, f.observed);
+    const { pages, pagesTruncated } = densePages(f.observed, pageCount, dense);
+    return {
+        fileId: f.fileId,
+        name: f.name,
+        seconds: f.seconds,
+        views: f.views,
+        ...(f.viewers !== undefined ? { viewers: f.viewers } : {}),
+        estimated: f.estimated,
+        pageCount,
+        dense,
+        pages,
+        ...(pagesTruncated ? { pagesTruncated } : {}),
+        thumbnailUrl: meta?.thumbnailUrl ?? null,
+        contentType: meta?.contentType ?? null,
+    };
+}
+function visitView(v, names) {
+    const fileName = (id) => names[id] ?? fileFallbackName(id);
+    const items = v.items.map((it) => {
+        const c = classifyItem(it);
+        const base = { id: it.id, views: it.views, seconds: it.seconds, estimated: it.estimated };
+        if (c.kind === 'section')
+            return { type: 'section', name: names[it.id] ?? it.name, ...base };
+        if (c.kind === 'file')
+            return { type: 'file', name: fileName(c.fileId), fileId: c.fileId, ...base };
+        return { type: 'page', name: fileName(c.fileId), fileId: c.fileId, page: c.page, ...base };
+    });
+    return {
+        visit: v.visit,
+        startedAt: v.started_at,
+        endedAt: v.ended_at,
+        engagedSeconds: v.engaged_seconds,
+        items: items.slice(0, VISIT_ITEMS_MAX),
+        ...(items.length > VISIT_ITEMS_MAX ? { itemsTruncated: items.length - VISIT_ITEMS_MAX } : {}),
+    };
+}
+/**
+ * Viewer (7.4 item 2): items per visit are already capped at 60 and the newest 50 visits kept; then, while over
+ * `budget`, drop the oldest visit, then files from the end. File totals were computed over every visit before any
+ * cut. Measured with `truncated` included.
+ */
+export function fitViewer(data, budget = DSR_VIEW_MAX_BYTES) {
+    const out = { ...data };
+    const note = () => {
+        const { truncated: _old, ...rest } = out;
+        const parts = [];
+        if (out.visits.length < data.visitsTotal)
+            parts.push(`Newest ${out.visits.length} of ${data.visitsTotal} visits; file totals cover every visit`);
+        if (out.files.length < data.files.length)
+            parts.push(`${out.files.length} of ${data.files.length} files shown`);
+        return parts.length ? { ...rest, truncated: parts.join('; ') } : rest;
+    };
+    while (out.visits.length && jsonBytes(note()) > budget)
+        out.visits = out.visits.slice(0, -1);
+    while (out.files.length && jsonBytes(note()) > budget)
+        out.files = out.files.slice(0, -1);
+    return note();
+}
+/** Content (7.4 item 3): pages are capped at 300 per file already; drop files from the end. */
+export function fitContent(data, budget = DSR_VIEW_MAX_BYTES) {
+    const out = { ...data };
+    const total = data.files.length;
+    const note = () => {
+        const { truncated: _old, ...rest } = out;
+        return out.files.length < total ? { ...rest, truncated: `${out.files.length} of ${total} files shown` } : rest;
+    };
+    while (out.files.length && jsonBytes(note()) > budget)
+        out.files = out.files.slice(0, -1);
+    return note();
+}
+// ── runners ──────────────────────────────────────────────────────────────────
+/**
+ * One viewer (6.3): one timeline under a 25 s deadline, all-visit file totals, meta only within the first 10 s.
+ * Unfitted: each caller fits it ONCE with its own budget, so `truncated` always counts against the full lists.
+ */
+async function loadViewer(client, scope, identity, deps) {
+    const now = clockOf(deps);
+    const start = now();
+    const signal = abortOf(deps)(VIEWER_DEADLINE_MS);
+    const t = await underDeadline(readTimeline(client, scope, identity, signal), signal);
+    const agg = aggregateFiles([t]);
+    let meta = { meta: new Map(), truncated: 0 };
+    let metaSkipped = false;
+    if (agg.files.length) {
+        if (now() - start <= VIEWER_META_MAX_ELAPSED_MS && !signal.aborted) {
+            meta = await readFileMeta(client, scope.instanceId, agg.files.map((f) => f.fileId), signal);
+        }
+        else {
+            metaSkipped = true;
+        }
+    }
+    const newestFirst = [...t.visits].reverse();
+    const data = {
+        kind: 'viewer',
+        scope,
+        identity,
+        isExternal: null,
+        totals: {
+            visits: t.visits.length,
+            engagedSeconds: t.visits.reduce((n, v) => n + v.engaged_seconds, 0),
+            firstVisit: t.visits[0]?.started_at ?? null,
+            lastVisit: newestFirst[0]?.started_at ?? null,
+        },
+        files: agg.files.map((f) => toFileStat(f, meta.meta.get(f.fileId))),
+        sections: agg.sections.map(({ id, name, seconds, views }) => ({ id, name, seconds, views })),
+        visits: newestFirst.slice(0, VIEWER_VISITS_MAX).map((v) => visitView(v, t.names)),
+        visitsTotal: t.visits.length,
+        ...(meta.truncated ? { metaTruncated: meta.truncated } : {}),
+        ...(metaSkipped ? { metaSkipped: true } : {}),
+    };
+    return data;
+}
+/**
+ * The drilled identity's flag. The External and Internal filters decide it. Under `all` an address can be listed
+ * twice (signed in, and through the link with the marker) and the drill covers both, so only a page that holds
+ * every row can tell: one agreeing flag there, else null (PR 6010 review).
+ */
+export function flagOf(page, identity, viewerType) {
+    if (viewerType !== 'all')
+        return viewerType === 'external';
+    if (page.hasMore)
+        return null;
+    const flags = new Set(page.rows.filter((r) => r.identity === identity).map((r) => r.isExternal));
+    return flags.size === 1 ? [...flags][0] : null;
+}
+export async function runDsrView(opts, deps = {}) {
+    try {
+        const now = clockOf(deps);
+        const scope = scopeOf(opts, now());
+        const identity = opts.viewerIdentity === undefined ? null : identityOf(opts.viewerIdentity, 'viewerIdentity');
+        const client = clickhouseClientFor(opts, deps);
+        const [v, viewer] = await Promise.all([
+            readViewers(client, scope),
+            identity === null ? Promise.resolve(null) : loadViewer(client, scope, identity, deps),
+        ]);
+        const data = {
+            kind: 'overview',
+            scope,
+            header: toHeader(v.native),
+            viewers: v.page,
+            unavailable: v.unavailable,
+            fetchedAt: new Date(now()).toISOString(),
+        };
+        if (viewer) {
+            // D22: the viewer gets whatever the overview leaves of the one budget.
+            data.viewer = fitViewer({ ...viewer, isExternal: flagOf(v.page, identity, scope.viewerType) }, DSR_VIEW_MAX_BYTES - jsonBytes(data) - 16);
+        }
+        return ok(data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runDsrViewersPage(opts, deps = {}) {
+    try {
+        const scope = scopeOf(opts, clockOf(deps)());
+        const page = opts.page ?? 1;
+        if (!Number.isInteger(page) || page < 1)
+            throw createCliError('VALIDATION', 'page must be an integer from 1');
+        const sortBy = (opts.sortBy ?? 'last_active');
+        if (!SORTS.includes(sortBy))
+            throw createCliError('VALIDATION', `sortBy must be one of: ${SORTS.join(', ')}`);
+        if (opts.search !== undefined && opts.search.length > 200)
+            throw createCliError('VALIDATION', 'search must be at most 200 characters');
+        const search = opts.search ? opts.search : null;
+        const v = await readViewers(clickhouseClientFor(opts, deps), scope, { page, sortBy, search });
+        return ok({ kind: 'viewers-page', scope, ...v.page, sortBy, search, unavailable: v.unavailable });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runDsrViewer(opts, deps = {}) {
+    try {
+        const scope = scopeOf(opts, clockOf(deps)());
+        const identity = identityOf(opts.viewerIdentity, 'viewerIdentity');
+        return ok(fitViewer(await loadViewer(clickhouseClientFor(opts, deps), scope, identity, deps)));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * Content (6.4, D21): up to 15 deduped identities (passed by the view, else page 1 of the viewers by last active),
+ * their timelines three at a time under ONE 20 s deadline whose signal reaches every request; a failed or late
+ * timeline is "not covered", never a tool failure, unless every timeline failed.
+ */
+export async function runDsrContent(opts, deps = {}) {
+    try {
+        const now = clockOf(deps);
+        const start = now();
+        const scope = scopeOf(opts, start);
+        if (opts.viewerIdentities !== undefined) {
+            if (!Array.isArray(opts.viewerIdentities) || opts.viewerIdentities.length > CONTENT_MAX_VIEWERS) {
+                throw createCliError('VALIDATION', `viewerIdentities must hold at most ${CONTENT_MAX_VIEWERS} identities`);
+            }
+            opts.viewerIdentities.forEach((id) => identityOf(id, 'viewerIdentities'));
+        }
+        const client = clickhouseClientFor(opts, deps);
+        const signal = abortOf(deps)(CONTENT_DEADLINE_MS);
+        const listed = !!opts.viewerIdentities?.length;
+        let ids;
+        let viewersTotal = null;
+        let unavailable = [];
+        let canvasName = null;
+        if (listed) {
+            ids = opts.viewerIdentities;
+        }
+        else {
+            // A rejection here is a tool error with its own code (gate NOT_FOUND / AUTH, deadline NETWORK), never "no viewers".
+            const v = await underDeadline(readViewers(client, scope, { signal }), signal);
+            ids = v.page.rows.map((r) => r.identity);
+            viewersTotal = v.page.total;
+            unavailable = v.unavailable;
+            canvasName = toHeader(v.native).canvasName || null;
+        }
+        const keys = dedupeIdentities(ids, CONTENT_MAX_VIEWERS);
+        const empty = {
+            kind: 'content',
+            scope,
+            canvasName,
+            files: [],
+            sections: [],
+            viewersCovered: 0,
+            viewersSampled: keys.length,
+            viewersFailed: 0,
+            viewersTotal,
+            sampleSource: listed ? 'listed' : 'recent',
+            deadlineHit: false,
+            unavailable,
+        };
+        if (!keys.length)
+            return ok(empty);
+        let deadlineHit = false;
+        const settled = await pool(keys, CONTENT_CONCURRENCY, (key) => underDeadline(readTimeline(client, scope, key, signal), signal).catch((e) => {
+            if (signal.aborted)
+                deadlineHit = true;
+            throw e;
+        }), () => {
+            if (signal.aborted)
+                deadlineHit = true;
+            return !signal.aborted;
+        });
+        const covered = settled.flatMap((s) => (s.status === 'fulfilled' ? [s.value] : []));
+        if (!covered.length) {
+            const first = settled.find((s) => s.status === 'rejected');
+            throw isCliError(first?.reason) ? first.reason : toCliError(first?.reason);
+        }
+        const agg = aggregateFiles(covered, { countViewers: true });
+        let meta = { meta: new Map(), truncated: 0 };
+        let metaSkipped = false;
+        if (agg.files.length) {
+            if (CONTENT_DEADLINE_MS - (now() - start) >= CONTENT_META_MIN_REMAINING_MS && !signal.aborted) {
+                meta = await readFileMeta(client, scope.instanceId, agg.files.map((f) => f.fileId), signal);
+            }
+            else {
+                metaSkipped = true;
+            }
+        }
+        return ok(fitContent({
+            ...empty,
+            canvasName: canvasName ?? covered.find((t) => t.canvasName)?.canvasName ?? null,
+            files: agg.files.map((f) => toFileStat(f, meta.meta.get(f.fileId))),
+            sections: agg.sections.map(({ id, name, seconds, views, viewers }) => ({ id, name, seconds, views, viewers: viewers ?? 0 })),
+            viewersCovered: covered.length,
+            viewersFailed: keys.length - covered.length,
+            deadlineHit,
+            ...(meta.truncated ? { metaTruncated: meta.truncated } : {}),
+            ...(metaSkipped ? { metaSkipped: true } : {}),
+        }));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+// ── text (7.3) ───────────────────────────────────────────────────────────────
+const WINDOW_TEXT = { '30d': 'last 30 days', '90d': 'last 90 days', '365d': 'last 12 months' };
+const TYPE_WORD = { external: 'external ', internal: 'internal ', all: '' };
+const SORT_TEXT = { last_active: 'last active', total_engagement_time: 'time', session_count: 'visits' };
+const dur = (s, estimated = false) => `${estimated ? '~' : ''}${fmtDuration(s)}`;
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/** Shrink only the free-text names until `build` fits `max` (so the fixed sentences are never cut). */
+function shrinkNames(build, max) {
+    for (const n of [120, 60, 30, 12]) {
+        const t = build(n);
+        if (byteLen(t) <= max)
+            return t;
+    }
+    return build(0);
+}
+const nameAt = (s, n) => (n ? clipBytes(s, n) : '...');
+/** 7.3 item 5: the full scope of the list, so the model's next page is the same list. */
+export function continuationArgs(scope, sortBy, search, page, total) {
+    const lastPage = Math.max(1, Math.ceil(total / VIEWERS_PAGE_SIZE));
+    const parts = [`viewerType ${scope.viewerType}`];
+    if (scope.startDate)
+        parts.push(`startDate ${scope.startDate}`);
+    parts.push(`sortBy ${sortBy}`);
+    if (search)
+        parts.push(`search ${JSON.stringify(search)}`);
+    parts.push(`limit ${VIEWERS_PAGE_SIZE}`, `page ${page} of ${lastPage}`);
+    return `use pitcher_analytics_viewers with ${parts.join(', ')}`;
+}
+/** fitText with the reserve sized to the longest `more` this call can print, never below 160 B. */
+function fitDsrText(input) {
+    const longest = byteLen(input.more({ lines: 99999, hidden: 99999, kinds: ['viewer', 'visit'] }));
+    return fitText({ ...input, maxBytes: DSR_TEXT_MAX_BYTES, reserve: Math.max(DSR_MORE_MIN_RESERVE, longest + 1) });
+}
+function viewerLine(r, scope) {
+    const flag = scope.viewerType === 'external' ? '' : ` [${r.isExternal ? 'external' : 'internal'}]`;
+    return (`${r.identity}${flag}: ${plural(r.visits, 'visit')}, ${dur(r.engagedSeconds)}, last ${naiveDate(r.lastActive)}, ` +
+        `${plural(r.filesViewed, 'file')}${r.forwards > 0 ? `, forwarded ${r.forwards}x` : ''}`);
+}
+function visitLine(v) {
+    const files = new Set(v.items.filter((i) => i.fileId).map((i) => i.fileId)).size;
+    const sections = v.items.filter((i) => i.type === 'section').length;
+    return `${naiveMinute(v.startedAt)} ${dur(v.engagedSeconds)} ${plural(files, 'file')} ${plural(sections, 'section')}`;
+}
+function topPages(f, n) {
+    return f.pages
+        .filter((p) => p.seconds > 0 || p.views > 0)
+        .sort((a, b) => b.seconds - a.seconds || a.page - b.page)
+        .slice(0, n);
+}
+function viewerTotalsHead(d, listed) {
+    const t = d.totals;
+    if (!t.visits)
+        return 'This viewer: no visits in this window.';
+    const list = listed < t.visits ? `Newest ${listed} of ${t.visits} visits listed below.` : `${plural(listed, 'visit')} listed below.`;
+    return (`This viewer: ${plural(t.visits, 'visit')}, ${dur(t.engagedSeconds)}, first ${naiveDate(t.firstVisit)}, ` +
+        `last ${naiveDate(t.lastVisit)} (viewer's local time). ${list}`);
+}
+function viewerFilesHead(d) {
+    if (!d.files.length)
+        return '';
+    const entries = d.files.slice(0, 5).map((f) => {
+        const tops = topPages(f, 3);
+        return `${clipBytes(f.name, 60)} (${f.fileId}) ${dur(f.seconds, f.estimated)}${tops.length ? `, top pages ${tops.map((p) => `${p.page} ${dur(p.seconds, p.estimated)}`).join(', ')}` : ''}`;
+    });
+    return listHead('Files: ', entries, d.files.length, 900, `Files: ${d.files.length} files.`);
+}
+function unavailableHead(unavailable, viewers) {
+    if (!unavailable.length)
+        return '';
+    const list = listFailed(unavailable, viewers) ? 'The viewer list could not be loaded. ' : '';
+    return `${list}Some figures could not be loaded (${unavailable.join(', ')}); a 0 may be missing data.`;
+}
+/**
+ * 8.2 row 6: the list is lost and the viewers exist, or the counts that could say "none" are lost with it (then 0 is
+ * missing data, never "nobody opened", PR 6010 review).
+ */
+export const listFailed = (unavailable, viewers) => unavailable.includes('viewer_list') &&
+    (viewers > 0 || unavailable.includes('viewer_count') || unavailable.includes('overview'));
+const zeroSentence = (viewers, unavailable) => viewers === 0 && !unavailable.includes('overview') && !unavailable.includes('viewer_count')
+    ? 'No one has opened this DSR in this window.'
+    : '';
+export function dsrViewText(raw) {
+    const d = raw;
+    const h = d.header;
+    const s = d.scope;
+    const head1 = shrinkNames((n) => 'If your host shows the DSR engagement view, the user sees it there; otherwise summarise this for the user. ' +
+        'Viewer identities below are drill keys: pass one unchanged as viewerIdentity. ' +
+        `DSR "${nameAt(h.canvasName, n)}" (canvas ${s.canvasId}), ${TYPE_WORD[s.viewerType]}viewers, ${WINDOW_TEXT[s.window]}: ` +
+        `${plural(h.viewers, 'viewer')}, ${plural(h.visits, 'visit')}, ${dur(h.engagedSeconds)} engaged; ` +
+        `forwarded ${plural(h.forwards, 'time')} (all viewers).` +
+        (h.mostViewedFile ? ` Most read file: ${nameAt(h.mostViewedFile.name, n && Math.min(n, 60))} (${h.mostViewedFile.id}) ${dur(h.mostViewedFile.seconds)}.` : '') +
+        (h.lastActivity ? ` Last activity ${naiveMinute(h.lastActivity)} (viewer's local time).` : ''), 700);
+    const v = d.viewer;
+    const visits = v ? v.visits.slice(0, TEXT_VISITS_IN_OVERVIEW) : [];
+    const sortBy = 'last_active';
+    const hidden = Math.max(0, d.viewers.total - d.viewers.rows.length);
+    return fitDsrText({
+        heads: [
+            { text: head1, maxBytes: 700 },
+            { text: unavailableHead(d.unavailable, h.viewers), maxBytes: 200 },
+            { text: zeroSentence(h.viewers, d.unavailable), maxBytes: 45 },
+            { text: v ? viewerTotalsHead(v, visits.length) : '', maxBytes: 200 },
+            { text: v ? viewerFilesHead(v) : '', maxBytes: 900 },
+        ],
+        body: [
+            ...visits.map((x) => ({ text: visitLine(x), kind: 'visit' })),
+            ...d.viewers.rows.map((r) => ({ text: viewerLine(r, s), kind: 'viewer' })),
+        ],
+        hidden,
+        more: ({ lines, hidden: h2 }) => {
+            const next = continuationArgs(s, sortBy, null, h2 > 0 ? 2 : 1, d.viewers.total);
+            const dropped = h2 > 0 && lines > 0 ? ` (dropped lines of this page: the same call with page 1)` : '';
+            return `...and ${lines + h2} more viewers: ${next}${dropped}.`;
+        },
+    });
+}
+export function dsrViewersPageText(raw) {
+    const d = raw;
+    const s = d.scope;
+    const first = (d.page - 1) * VIEWERS_PAGE_SIZE + 1;
+    const range = d.rows.length ? `Viewers ${first}-${first + d.rows.length - 1} of ${d.total}` : `No viewers on page ${d.page} of ${d.total}`;
+    const head = `${range} (${TYPE_WORD[s.viewerType]}${s.viewerType === 'all' ? 'all ' : ''}viewers, ${WINDOW_TEXT[s.window]}, ` +
+        `sorted by ${SORT_TEXT[d.sortBy]}${d.search ? `, search ${JSON.stringify(d.search)}` : ''}):`;
+    const later = Math.max(0, d.total - (d.page - 1) * VIEWERS_PAGE_SIZE - d.rows.length);
+    return fitDsrText({
+        heads: [{ text: head, maxBytes: 200 }],
+        body: d.rows.map((r) => ({ text: viewerLine(r, s), kind: 'viewer' })),
+        hidden: later,
+        more: ({ lines, hidden }) => {
+            const parts = [];
+            if (hidden > 0)
+                parts.push(`${hidden} on later pages: ${continuationArgs(s, d.sortBy, d.search, d.page + 1, d.total)}`);
+            if (lines > 0)
+                parts.push(`${lines} dropped from this page: the same call with page ${d.page}`);
+            return `...${lines + hidden} not listed: ${parts.join('; ')}`;
+        },
+    });
+}
+export function dsrViewerText(raw) {
+    const d = raw;
+    return fitDsrText({
+        heads: [
+            { text: viewerTotalsHead(d, d.visits.length), maxBytes: 200 },
+            { text: viewerFilesHead(d), maxBytes: 900 },
+        ],
+        body: d.visits.map((v) => ({ text: visitLine(v), kind: 'visit' })),
+        hidden: Math.max(0, d.visitsTotal - d.visits.length),
+        more: ({ lines, hidden }) => `...${lines + hidden} older visits not listed`,
+    });
+}
+function contentHead(d) {
+    const s = d.scope;
+    const n = d.viewersCovered;
+    if (d.viewersSampled === 0) {
+        if (listFailed(d.unavailable, d.viewersTotal ?? 0))
+            return 'The viewer list could not be loaded.';
+        return zeroSentence(d.viewersTotal ?? 0, d.unavailable) || 'No viewers to sample in this window.';
+    }
+    const filesRead = d.files.length;
+    const time = dur(d.files.reduce((t, f) => t + f.seconds, 0), d.files.some((f) => f.estimated));
+    return shrinkNames((len) => {
+        const name = d.canvasName ? ` for DSR "${nameAt(d.canvasName, len)}"` : '';
+        const failed = d.viewersFailed
+            ? ` (${n} of ${d.viewersSampled} sampled viewers loaded; ${d.viewersFailed} timed out or failed)`
+            : '';
+        const who = d.sampleSource === 'listed'
+            ? `${failed ? `${n} of the ${d.viewersSampled}` : `the ${n}`} listed viewers (${WINDOW_TEXT[s.window]})`
+            : `${failed ? `${n} of the ${d.viewersSampled}` : `the ${n}`} most recently active of ${d.viewersTotal === null ? 'the listed' : d.viewersTotal} ${TYPE_WORD[s.viewerType]}viewers (${WINDOW_TEXT[s.window]})`;
+        return (`Sample: ${who}${name}${failed}. Not totals: the overview counts every viewer; timelines include every visit ` +
+            `of each address. Read: ${plural(filesRead, 'file')}, ${time}.`);
+    }, 350);
+}
+function contentFileLine(f, n) {
+    const parts = [`${clipBytes(f.name, 60)} (${f.fileId}): ${dur(f.seconds, f.estimated)}, ${f.viewers ?? 0} of ${n} covered viewers`];
+    if (f.pageCount > 0) {
+        const read = f.pages.filter((p) => p.seconds > 0 || p.views > 0);
+        parts.push(f.dense ? `pages read ${read.length} of ${f.pageCount}` : `pages read ${read.length}`);
+        const tops = topPages(f, 3);
+        if (tops.length) {
+            parts.push(`top ${tops
+                .map((p, i) => `${p.page} (${dur(p.seconds, p.estimated)}${i === 0 ? `, ${plural(p.viewers ?? 0, 'viewer')}` : ''})`)
+                .join(', ')}`);
+        }
+        if (f.dense) {
+            const unopened = f.pages.filter((p) => p.seconds === 0 && p.views === 0).map((p) => p.page);
+            if (unopened.length)
+                parts.push(`not opened by these ${n}: ${clipBytes(compressRanges(unopened), 40)}`);
+        }
+    }
+    return parts.join('; ');
+}
+export function dsrContentText(raw) {
+    const d = raw;
+    const n = d.viewersCovered;
+    const sections = d.sections.slice(0, 8).map((x) => `${clipBytes(x.name, 40)} ${dur(x.seconds)}`);
+    return fitDsrText({
+        heads: [
+            { text: contentHead(d), maxBytes: 350 },
+            { text: sections.length ? listHead('Sections: ', sections, d.sections.length, 600, `Sections: ${d.sections.length}.`) : '', maxBytes: 600 },
+        ],
+        body: d.files.map((f) => ({ text: contentFileLine(f, n), kind: 'file' })),
+        more: ({ lines }) => `...${lines} more files`,
+    });
+}
+// ── tools ────────────────────────────────────────────────────────────────────
+const VIEW = 'dsr-engagement';
+const identity = z.string().min(1).max(1024);
+const dsrInput = {
+    instanceId: z.string().describe('Instance ID (required)'),
+    canvasId: z
+        .string()
+        .describe('DSR canvas ID (required): from pitcher_search, pitcher_canvases_list, or canvas.id of pitcher_dsr_create'),
+    viewerType: z.enum(['external', 'internal', 'all']).optional().describe('Whose views: external (default), internal, all'),
+    window: z.enum(['30d', '90d', '365d']).optional().describe('Time window: 30d (default), 90d, 365d (last 12 months)'),
+};
+export const dsrEngagementTools = [
+    {
+        name: 'pitcher_analytics_dsr_view',
+        title: 'DSR engagement view (interactive)',
+        description: 'Interactive engagement view for one DSR (Digital Sales Room) canvas: who opened it, how often, how long. With ' +
+            "viewerIdentity it also returns that viewer's visits and time per page of each file. In hosts without UI it " +
+            "returns the same as text. Shows what Pitcher's Sharing Analytics shows the signed-in user. Find canvasId with " +
+            'pitcher_search or pitcher_canvases_list. Viewer identities in the text are drill keys: pass them back unchanged.',
+        inputShape: {
+            ...dsrInput,
+            viewerIdentity: identity.optional().describe('A viewer identity exactly as an earlier result printed it'),
+        },
+        run: runDsrView,
+        toText: dsrViewText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'analytics',
+        ui: { view: VIEW },
+    },
+    {
+        name: 'pitcher_analytics_dsr_viewers_page',
+        title: 'DSR viewers page (DSR engagement view UI helper)',
+        description: 'UI helper for the DSR engagement view: one page of 25 viewers with search and sort. For a plain data answer ' +
+            'use pitcher_analytics_viewers with limit 25.',
+        inputShape: {
+            ...dsrInput,
+            page: z.number().int().min(1).optional().describe('1-based, 25 viewers a page'),
+            sortBy: z.enum(['last_active', 'total_engagement_time', 'session_count']).optional().describe('Default last_active'),
+            search: z.string().max(200).optional().describe('Case-sensitive part of a viewer identity'),
+        },
+        run: runDsrViewersPage,
+        toText: dsrViewersPageText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'analytics',
+        ui: { view: VIEW, visibility: ['app'] },
+    },
+    {
+        name: 'pitcher_analytics_dsr_viewer',
+        title: 'DSR viewer drill (DSR engagement view UI helper)',
+        description: "UI helper for the DSR engagement view: one viewer's visits and time per page. Model path: " +
+            'pitcher_analytics_dsr_view with viewerIdentity.',
+        inputShape: {
+            ...dsrInput,
+            viewerIdentity: identity.describe('The viewer identity exactly as listed'),
+        },
+        run: runDsrViewer,
+        toText: dsrViewerText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'analytics',
+        ui: { view: VIEW, visibility: ['app'] },
+    },
+    {
+        name: 'pitcher_analytics_dsr_content',
+        title: 'DSR content read by recent viewers',
+        description: 'Most-read files and pages of one DSR canvas among its most recently active viewers (a sample of up to 15; the ' +
+            "result states how many it covers). Use it for 'which pages did the buyer team read'. It cannot say that nobody " +
+            'opened a page, only that the covered viewers did not. In hosts with UI it opens the DSR engagement view on its ' +
+            'Content tab.',
+        inputShape: {
+            ...dsrInput,
+            viewerIdentities: z
+                .array(identity)
+                .max(CONTENT_MAX_VIEWERS)
+                .optional()
+                .describe("UI use only: identities from the view's default list. Omit it."),
+        },
+        run: runDsrContent,
+        toText: dsrContentText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        group: 'analytics',
+        ui: { view: VIEW, visibility: ['model', 'app'] },
+    },
+];