@pitcher/cli-scripts 3.2.0 → 3.3.0

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

@@ -0,0 +1,268 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { runFilesGet } from '../../commands/files.js';
+import { ok, fail } from '../../core/envelope.js';
+import { createCliError } from '../../core/errors.js';
+import { clientFor, toCliError } from '../../core/http.js';
+import { orgOrigin } from './types.js';
+/**
+ * MCP Apps content picker (PIT-10066): a files-only gallery with multi-select that creates a DSR
+ * through the ShareBox path of the existing pitcher_dsr_create tool. Owner rulings P1 + P5: files only.
+ */
+export const contentPickerView = {
+    name: 'content-picker',
+    title: 'Pitcher content picker',
+    description: 'Thumbnail gallery of files with multi-select and DSR (ShareBox) creation.',
+    csp: (ctx) => ({ resourceDomains: orgOrigin(ctx) }),
+    permissions: { clipboardWrite: {} },
+    // rollout: the shared enable_mcp_apps flag (owner ruling P7), no per-view flag
+};
+export const PICKER_PAGE_SIZE = 24;
+export const PICKER_MAX_BYTES = 120000;
+export const ITEM_MAX_BYTES = 60000;
+export const TEMPLATES_MAX_BYTES = 30000;
+const jsonBytes = (v) => Buffer.byteLength(JSON.stringify(v), 'utf8');
+/**
+ * Drop items from the end until the serialized payload fits; report how many were dropped.
+ * Trade-off: the next page starts after the FULL server page, so a dropped item is never reachable by
+ * paging (only by a narrower search). Accepted: 24 items rarely come near 120 KB (thumbnail URLs are ~1 KB).
+ */
+export function fitToBudget(data, max = PICKER_MAX_BYTES) {
+    let items = data.items;
+    const size = (xs) => jsonBytes({ ...data, items: xs });
+    while (items.length && size(items) > max)
+        items = items.slice(0, -1);
+    const dropped = data.items.length - items.length;
+    return dropped ? { ...data, items, truncated: dropped } : { ...data, items };
+}
+/** Model-facing text: one short line per file, no URLs. structuredContent carries the thumbnails. */
+export function pickerText(data) {
+    const d = data;
+    const lines = d.items.map((i) => `${i.id} ${i.fileType ?? ''} ${i.name}${i.shareable ? '' : ' (cannot be shared)'}`.replace(/\s+/g, ' ').trim());
+    const tail = d.hasMore || d.truncated ? ' More available.' : '';
+    return `${d.items.length} files.${tail} If your host shows the content picker view, the user sees these items there; otherwise list them for the user.\n${lines.join('\n')}`;
+}
+const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+function fileTypeOf(row) {
+    const ext = str(row.content_extension);
+    if (ext)
+        return ext.replace(/^\./, '').toUpperCase();
+    return str(row.content_type);
+}
+/** A files-list (or retrieve) row -> PickerItem. `shareable` is false only for an explicit can_share=false. */
+export function toPickerItem(row) {
+    const folder = row.folder;
+    const permissions = row.permissions;
+    return {
+        id: String(row.id),
+        name: typeof row.name === 'string' ? row.name : String(row.id),
+        subtitle: str(folder?.name),
+        fileType: fileTypeOf(row),
+        shareable: permissions?.can_share !== false,
+        thumbnailUrl: str(row.thumbnail_url),
+    };
+}
+/** Every File.ContentType a user would filter by (Django filemodels.py File.ContentType). */
+export const CONTENT_FILTERS = ['pdf', 'video', 'image', 'web', 'audio', 'attch'];
+const isNotFound = (e) => toCliError(e).code === 'NOT_FOUND';
+/**
+ * next-core's account rule (shared-links/route.ts): lodash `merge({}, defaults, org.settings, instance.settings)`
+ * then a truthiness test. merge copies an explicit instance value, null included, over the org value; only
+ * `undefined` falls through, so this is NOT `??`. Either read failing = null (unknown; the 400 path covers it).
+ */
+async function readRequiresAccount(client, instanceId) {
+    const [orgRes, instRes] = await Promise.allSettled([
+        client.get('/api/v1/organization/'),
+        client.get(`/api/v1/instances/${encodeURIComponent(instanceId)}`),
+    ]);
+    if (orgRes.status !== 'fulfilled' || instRes.status !== 'fulfilled')
+        return null;
+    const org = orgRes.value.data?.settings?.canvas?.require_account_on_canvas_creation;
+    const inst = instRes.value.data?.settings?.canvas?.require_account_on_canvas_creation;
+    return Boolean(inst !== undefined ? inst : org);
+}
+/**
+ * requiresAccount memo (C3): a search keystroke re-runs page 1, which would re-read two settings endpoints
+ * every time. Keyed by sha256(credential) + instanceId (never the raw token), 60 s TTL, at most 1000 entries
+ * with oldest-first eviction. A null (read failed) is never stored, so the next call retries.
+ */
+export const REQUIRES_ACCOUNT_TTL_MS = 60000;
+export const REQUIRES_ACCOUNT_CACHE_MAX = 1000;
+const requiresAccountCache = new Map();
+/** Test hook: empty the requiresAccount memo. */
+export function clearRequiresAccountCache() {
+    requiresAccountCache.clear();
+}
+function requiresAccountKey(opts, instanceId) {
+    const c = opts.credential;
+    if (!c)
+        return null; // no explicit credential (local CLI session): nothing stable to key on, no memo
+    const secret = c.kind === 'bearer' ? `bearer:${c.token}` : `apiKey:${c.key}`;
+    return `${createHash('sha256').update(secret).digest('hex')}:${instanceId}`;
+}
+async function cachedRequiresAccount(client, opts, instanceId) {
+    const key = requiresAccountKey(opts, instanceId);
+    const now = Date.now();
+    if (key) {
+        const hit = requiresAccountCache.get(key);
+        if (hit && hit.expires > now)
+            return hit.value;
+        if (hit)
+            requiresAccountCache.delete(key);
+    }
+    const value = await readRequiresAccount(client, instanceId);
+    if (key && value !== null) {
+        // Map keeps insertion order, so the first key is the oldest entry.
+        while (requiresAccountCache.size >= REQUIRES_ACCOUNT_CACHE_MAX) {
+            const oldest = requiresAccountCache.keys().next().value;
+            requiresAccountCache.delete(oldest);
+        }
+        requiresAccountCache.set(key, { value, expires: Date.now() + REQUIRES_ACCOUNT_TTL_MS });
+    }
+    return value;
+}
+export async function runContentPicker(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', 'instanceId is required');
+        const client = clientFor(opts, deps);
+        const page = opts.page ?? 1;
+        const createDsr = opts.availableTools?.has('pitcher_dsr_create') === true;
+        const contentTypes = opts.contentTypes ?? [];
+        const params = {
+            instance_id: opts.instanceId,
+            type__in: 'content,asset',
+            page,
+            page_size: PICKER_PAGE_SIZE,
+        };
+        if (opts.query)
+            params.search = opts.query;
+        if (contentTypes.length)
+            params.content_type__in = contentTypes.join(',');
+        // Settings are read only where they matter: page 1 (the view keeps the first answer) of a server that can create.
+        const settings = createDsr && page === 1 ? cachedRequiresAccount(client, opts, opts.instanceId) : Promise.resolve(null);
+        const files = client.get('/api/v1/files/', { params }).then((res) => ({ rows: (res.data?.results ?? []), hasMore: Boolean(res.data?.next) }), (e) => {
+            // DRF answers 404 "Invalid page." past the last page (a file deleted between two requests): exhausted, not an error.
+            if (page > 1 && isNotFound(e))
+                return { rows: [], hasMore: false };
+            throw e;
+        });
+        const [list, requiresAccount] = await Promise.all([files, settings]);
+        return ok(fitToBudget({
+            instanceId: opts.instanceId,
+            query: opts.query ?? null,
+            contentTypes,
+            page,
+            items: list.rows.map(toPickerItem),
+            hasMore: list.hasMore,
+            actions: { createDsr },
+            requiresAccount,
+        }));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runContentItem(opts, deps = {}) {
+    const env = await runFilesGet(opts, deps);
+    if (!env.ok)
+        return env;
+    const row = (env.data ?? {});
+    const item = toPickerItem(row);
+    const thumbs = Array.isArray(row.content_thumbnails) ? row.content_thumbnails : [];
+    let pages = thumbs.slice(0, 4);
+    const data = () => ({
+        id: item.id,
+        name: item.name,
+        thumbnailUrl: item.thumbnailUrl,
+        fileType: item.fileType,
+        size: typeof row.size === 'number' ? row.size : null,
+        shareable: item.shareable,
+        pages,
+    });
+    while (pages.length && jsonBytes(data()) > ITEM_MAX_BYTES)
+        pages = pages.slice(0, -1);
+    return ok(data());
+}
+/**
+ * Share-tagged canvas templates, newest first (the rule next-core's fetchShareboxTemplate and the rep UI use).
+ * The access-scoped Django list may not start with next-core's own default, so the view's default option sends no templateId.
+ */
+export async function runShareboxTemplates(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', 'instanceId is required');
+        const client = clientFor(opts, deps);
+        const res = await client.get('/api/v1/canvases/', {
+            params: {
+                instance_id: opts.instanceId,
+                is_template: true,
+                is_section: false,
+                tags__in: 'share',
+                ordering: '-created_at',
+                fields: 'id,name,thumbnail_url',
+                page_size: 50,
+            },
+        });
+        const rows = (res.data?.results ?? []);
+        const all = rows.map((r) => ({
+            id: String(r.id),
+            name: typeof r.name === 'string' ? r.name : String(r.id),
+            thumbnailUrl: str(r.thumbnail_url),
+        }));
+        let templates = all;
+        while (templates.length && jsonBytes({ templates }) > TEMPLATES_MAX_BYTES)
+            templates = templates.slice(0, -1);
+        const dropped = all.length - templates.length;
+        return ok(dropped ? { templates, truncated: dropped } : { templates });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export const contentPickerTools = [
+    {
+        name: 'pitcher_content_picker',
+        title: 'Pick files (visual gallery)',
+        description: 'Interactive picker; in hosts without UI it returns a text list (id, type, name). Shows the user a gallery of files ' +
+            'in an instance to browse, filter, select and share as a DSR. For an id lookup during a task use pitcher_search instead.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            query: z.string().optional().describe('Search words (file name or tag). Omit to browse the newest files'),
+            contentTypes: z.array(z.enum(CONTENT_FILTERS)).optional().describe('Filter by content type'),
+            page: z.number().int().min(1).optional().describe('1-based'),
+        },
+        run: runContentPicker,
+        toText: pickerText,
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        ui: { view: 'content-picker' },
+    },
+    {
+        name: 'pitcher_content_item',
+        title: 'File detail (picker UI helper)',
+        description: 'UI helper for the Pitcher content picker view: returns one file summary for its detail panel. ' +
+            'Not for general use: prefer pitcher_files_get.',
+        inputShape: { id: z.string().describe('File ID') },
+        run: runContentItem,
+        toText: (d) => {
+            const x = d;
+            return `file ${x.id} ${x.name}`;
+        },
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        ui: { view: 'content-picker', visibility: ['app'] },
+    },
+    {
+        name: 'pitcher_sharebox_templates',
+        title: 'ShareBox templates (picker UI helper)',
+        description: "UI helper for the Pitcher content picker view: lists the instance's ShareBox templates for the DSR confirm step.",
+        inputShape: { instanceId: z.string().describe('Instance ID') },
+        run: runShareboxTemplates,
+        toText: (d) => d.templates.map((t) => `${t.id} ${t.name}`).join('\n') ||
+            'No ShareBox templates',
+        readOnly: true,
+        access: 'read', // PIT-10114: explicit for every app tool
+        ui: { view: 'content-picker', visibility: ['app'] },
+    },
+];

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

@@ -0,0 +1,194 @@
+import type { AxiosInstance } from 'axios';
+import { type DsrHeader, type DsrPageStat, type DsrUnavailable, type DsrViewerRow } from '../../core/dsr-engagement.js';
+import { type Envelope } from '../../core/envelope.js';
+import { type CommonOpts } from '../../core/http.js';
+import type { ToolDescriptor } from '../tools/types.js';
+import { type AppViewDescriptor } from './types.js';
+export type { DsrHeader, DsrPageStat, DsrUnavailable, DsrViewerRow } from '../../core/dsr-engagement.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 declare const dsrEngagementView: AppViewDescriptor;
+/** structuredContent budget per result (the picker's, PIT-10066 D14). */
+export declare const DSR_VIEW_MAX_BYTES = 120000;
+/** Model-facing text budget per result, in UTF-8 bytes. */
+export declare const DSR_TEXT_MAX_BYTES = 4096;
+export declare const VIEWERS_PAGE_SIZE = 25;
+export declare const VIEWER_VISITS_MAX = 50;
+export declare const VISIT_ITEMS_MAX = 60;
+export declare const FILE_META_MAX = 200;
+export declare const CONTENT_MAX_VIEWERS = 15;
+export declare const CONTENT_CONCURRENCY = 3;
+export declare const CONTENT_DEADLINE_MS = 20000;
+export declare const VIEWER_DEADLINE_MS = 25000;
+export type DsrViewerType = 'external' | 'internal' | 'all';
+export type DsrWindow = '30d' | '90d' | '365d';
+export type DsrSortBy = 'last_active' | 'total_engagement_time' | 'session_count';
+export interface DsrScope {
+    instanceId: string;
+    canvasId: string;
+    viewerType: DsrViewerType;
+    window: DsrWindow;
+    /** The ISO date `window` mapped to on the server's clock; null for 365d (the route's own default). */
+    startDate: string | null;
+}
+export interface DsrViewersPage {
+    rows: DsrViewerRow[];
+    total: number;
+    page: number;
+    hasMore: boolean;
+}
+export interface DsrFileStat {
+    fileId: string;
+    name: string;
+    seconds: number;
+    views: number;
+    viewers?: number;
+    estimated: boolean;
+    pageCount: number;
+    dense: boolean;
+    pages: DsrPageStat[];
+    pagesTruncated?: number;
+    thumbnailUrl: string | null;
+    contentType: string | null;
+}
+export interface DsrVisitItemView {
+    type: 'section' | 'file' | 'page';
+    id: string;
+    name: string;
+    fileId?: string;
+    page?: number;
+    views: number;
+    seconds: number;
+    estimated: boolean;
+}
+export interface DsrVisitView {
+    visit: number;
+    startedAt: string;
+    endedAt: string;
+    engagedSeconds: number;
+    items: DsrVisitItemView[];
+    itemsTruncated?: number;
+}
+export interface DsrSectionStat {
+    id: string;
+    name: string;
+    seconds: number;
+    views: number;
+}
+export interface DsrViewerData {
+    kind: 'viewer';
+    scope: DsrScope;
+    identity: string;
+    /** From the overview row when dsr_view has it, else null (the view keeps the clicked row's flag). */
+    isExternal: boolean | null;
+    totals: {
+        visits: number;
+        engagedSeconds: number;
+        firstVisit: string | null;
+        lastVisit: string | null;
+    };
+    files: DsrFileStat[];
+    sections: DsrSectionStat[];
+    visits: DsrVisitView[];
+    visitsTotal: number;
+    metaTruncated?: number;
+    metaSkipped?: boolean;
+    truncated?: string;
+}
+export interface DsrOverviewData {
+    kind: 'overview';
+    scope: DsrScope;
+    header: DsrHeader;
+    viewers: DsrViewersPage;
+    unavailable: DsrUnavailable[];
+    viewer?: DsrViewerData;
+    fetchedAt: string;
+}
+export interface DsrViewersPageData extends DsrViewersPage {
+    kind: 'viewers-page';
+    scope: DsrScope;
+    sortBy: DsrSortBy;
+    search: string | null;
+    unavailable: DsrUnavailable[];
+}
+export interface DsrContentData {
+    kind: 'content';
+    scope: DsrScope;
+    canvasName: string | null;
+    files: DsrFileStat[];
+    sections: Array<DsrSectionStat & {
+        viewers: number;
+    }>;
+    viewersCovered: number;
+    viewersSampled: number;
+    viewersFailed: number;
+    viewersTotal: number | null;
+    sampleSource: 'recent' | 'listed';
+    deadlineHit: boolean;
+    /** The viewers read's `_meta.unavailable` ([] when identities were passed in). */
+    unavailable: DsrUnavailable[];
+    metaSkipped?: boolean;
+    metaTruncated?: number;
+    truncated?: string;
+}
+export type DsrResult = DsrOverviewData | DsrViewersPageData | DsrViewerData | DsrContentData;
+interface DsrOpts extends CommonOpts {
+    instanceId?: string;
+    canvasId?: string;
+    viewerType?: string;
+    window?: string;
+    viewerIdentity?: string;
+    viewerIdentities?: string[];
+    page?: number;
+    sortBy?: string;
+    search?: string;
+}
+export interface DsrDeps {
+    client?: AxiosInstance;
+    /** Clock in ms (tests drive the deadlines). Default Date.now. */
+    now?: () => number;
+    /** Abort signal firing after `ms`. Default AbortSignal.timeout. */
+    abortAfter?: (ms: number) => AbortSignal;
+}
+/** `today (UTC) - N days` as YYYY-MM-DD; null for 365d, which sends no dates (the route's default). */
+export declare function windowStart(w: DsrWindow, nowMs: number): string | null;
+/**
+ * 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 declare function fitViewer(data: DsrViewerData, budget?: number): DsrViewerData;
+/** Content (7.4 item 3): pages are capped at 300 per file already; drop files from the end. */
+export declare function fitContent(data: DsrContentData, budget?: number): DsrContentData;
+/**
+ * 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 declare function flagOf(page: DsrViewersPage, identity: string, viewerType: DsrViewerType): boolean | null;
+export declare function runDsrView(opts: DsrOpts, deps?: DsrDeps): Promise<Envelope<DsrOverviewData>>;
+export declare function runDsrViewersPage(opts: DsrOpts, deps?: DsrDeps): Promise<Envelope<DsrViewersPageData>>;
+export declare function runDsrViewer(opts: DsrOpts, deps?: DsrDeps): Promise<Envelope<DsrViewerData>>;
+/**
+ * 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 declare function runDsrContent(opts: DsrOpts, deps?: DsrDeps): Promise<Envelope<DsrContentData>>;
+/** 7.3 item 5: the full scope of the list, so the model's next page is the same list. */
+export declare function continuationArgs(scope: DsrScope, sortBy: DsrSortBy, search: string | null, page: number, total: number): string;
+/**
+ * 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 declare const listFailed: (unavailable: DsrUnavailable[], viewers: number) => boolean;
+export declare function dsrViewText(raw: unknown): string;
+export declare function dsrViewersPageText(raw: unknown): string;
+export declare function dsrViewerText(raw: unknown): string;
+export declare function dsrContentText(raw: unknown): string;
+export declare const dsrEngagementTools: ToolDescriptor[];