@collage-dam/mcp-server 0.1.0

package/dist/tools/insights/analyze-share-links.js

@@ -0,0 +1,314 @@
+// ── analyze_share_links (T1, read-only) ──────────────────────────────
+//
+// Read-only distribution-insights tool. Aggregates share-link engagement
+// metrics across the workspace by walking the existing
+// `dashboard/list-share-assets-url` enumeration surface (already exposed
+// to the MCP layer via `client.listShareLinks`).
+//
+// Output is purely structured metrics (totals, top-N, status
+// distribution, creation time series, cohort breakdowns by creator). The
+// client LLM is responsible for narrative synthesis on top — no prose is
+// generated here. The companion `T6` task in this spec covers the
+// AI-summary scaffolding separately.
+//
+// Caching is the next task (T5). This file is written so a cache wrapper
+// can plug in around `analyzeShareLinks(...)` without touching the
+// detection / aggregation logic.
+//
+// Type discipline: never uses `any`. The upstream `ShareLink` row carries
+// loose / nullable fields (per the live `ShareLinkSchema` in `types.ts`),
+// so this module defines a narrow projection (`ShareLinkRow`) that the
+// enumerator adapter is responsible for producing.
+import { z } from 'zod';
+import { createToolError } from '../../conventions/errors.js';
+import { estimateTokens, HARD_CAP_TOKENS } from '../../conventions/response-budget.js';
+// ── Tool description ────────────────────────────────────────────────
+export const ANALYZE_SHARE_LINKS_DESCRIPTION = 'Read-only analytics over share links in the workspace. Returns ' +
+    'structured engagement metrics — totals, top-N most-viewed links, ' +
+    'status distribution (active/expired/revoked), creation time series, ' +
+    'and cohort breakdowns by creator and (if scoped) by collection. ' +
+    'Filters: optional date range, collection scope, creator scope. ' +
+    'Per-day view counts are NOT exposed by the upstream surface, so the ' +
+    'time series only carries creation cadence; view metrics are reported ' +
+    'as totals/aggregates only. No mutation, no AI prose.';
+// ── Input schema ────────────────────────────────────────────────────
+export const DEFAULT_TOP_N = 10;
+export const MAX_TOP_N = 50;
+export const ENUMERATOR_HARD_CAP = 5000;
+/**
+ * `date_from` / `date_to` are inclusive ISO-8601 date or datetime strings.
+ * If only a date is supplied (e.g. `2026-04-14`), it is interpreted as
+ * the start (00:00:00Z) for `date_from` or the end (23:59:59.999Z) for
+ * `date_to`. Both bounds are optional — omit to leave that side
+ * unbounded.
+ */
+export const AnalyzeShareLinksInputSchema = z
+    .object({
+    date_from: z
+        .string()
+        .min(1)
+        .refine((v) => !Number.isNaN(Date.parse(v)), {
+        message: 'date_from must be a valid ISO-8601 date or datetime string',
+    })
+        .optional(),
+    date_to: z
+        .string()
+        .min(1)
+        .refine((v) => !Number.isNaN(Date.parse(v)), {
+        message: 'date_to must be a valid ISO-8601 date or datetime string',
+    })
+        .optional(),
+    collection_id: z.string().min(1).optional(),
+    created_by_user_id: z.string().min(1).optional(),
+    top_n: z.number().int().min(1).max(MAX_TOP_N).default(DEFAULT_TOP_N),
+})
+    .strict();
+export class AnalyzeShareLinksTool {
+    deps;
+    name = 'analyze_share_links';
+    description = ANALYZE_SHARE_LINKS_DESCRIPTION;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run(rawInput = {}) {
+        let parsed;
+        try {
+            parsed = AnalyzeShareLinksInputSchema.parse(rawInput);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: createToolError('VALIDATION', err instanceof Error ? err.message : 'invalid input'),
+            };
+        }
+        // Cross-field validation: when both bounds are set, from <= to.
+        if (parsed.date_from !== undefined && parsed.date_to !== undefined) {
+            const fromMs = Date.parse(parsed.date_from);
+            const toMs = Date.parse(parsed.date_to);
+            if (fromMs > toMs) {
+                return {
+                    ok: false,
+                    error: createToolError('VALIDATION', 'date_from must be <= date_to'),
+                };
+            }
+        }
+        const enumerated = await this.deps.enumerator.enumerate();
+        if (!enumerated.ok) {
+            return { ok: false, error: enumerated.error };
+        }
+        const report = buildReport(enumerated.rows, enumerated.truncated, parsed);
+        return { ok: true, report };
+    }
+}
+export function buildAnalyzeShareLinksTool(deps) {
+    return new AnalyzeShareLinksTool(deps);
+}
+// ── Aggregation (pure) ──────────────────────────────────────────────
+/**
+ * Build the analytics report from a flat list of rows. Pure function,
+ * exported for direct test access.
+ */
+export function buildReport(rows, enumeratorTruncated, input) {
+    // ── Filter ──
+    const fromMs = parseLowerBound(input.date_from);
+    const toMs = parseUpperBound(input.date_to);
+    const matching = rows.filter((row) => {
+        if (input.collection_id !== undefined) {
+            if (row.collection_id !== input.collection_id)
+                return false;
+        }
+        if (input.created_by_user_id !== undefined) {
+            if (row.created_by_user_id !== input.created_by_user_id)
+                return false;
+        }
+        if (fromMs !== null || toMs !== null) {
+            const created = row.created_at;
+            if (created === null)
+                return false;
+            const createdMs = Date.parse(created);
+            if (Number.isNaN(createdMs))
+                return false;
+            if (fromMs !== null && createdMs < fromMs)
+                return false;
+            if (toMs !== null && createdMs > toMs)
+                return false;
+        }
+        return true;
+    });
+    // ── Totals ──
+    const viewCounts = matching.map((r) => r.view_count);
+    const totalViews = viewCounts.reduce((acc, v) => acc + v, 0);
+    const linkCount = matching.length;
+    const meanViews = linkCount === 0 ? null : totalViews / linkCount;
+    const medianViews = linkCount === 0 ? null : computeMedian(viewCounts);
+    // ── Status distribution ──
+    const statusDistribution = { active: 0, expired: 0, revoked: 0 };
+    for (const row of matching) {
+        statusDistribution[row.status] += 1;
+    }
+    // ── Top N (descending by view count, ties broken by created_at desc) ──
+    const sortedByViews = [...matching].sort((a, b) => {
+        if (b.view_count !== a.view_count)
+            return b.view_count - a.view_count;
+        const aMs = a.created_at === null ? 0 : Date.parse(a.created_at);
+        const bMs = b.created_at === null ? 0 : Date.parse(b.created_at);
+        return bMs - aMs;
+    });
+    const topLinks = sortedByViews
+        .slice(0, input.top_n)
+        .map((r) => ({
+        id: r.id,
+        title: r.title,
+        share_url: r.share_url,
+        view_count: r.view_count,
+        status: r.status,
+        created_at: r.created_at,
+        expires_at: r.expires_at,
+    }));
+    // ── Time series (creation cadence, daily) ──
+    const dayBuckets = new Map();
+    for (const row of matching) {
+        if (row.created_at === null)
+            continue;
+        const day = toIsoDay(row.created_at);
+        if (day === null)
+            continue;
+        dayBuckets.set(day, (dayBuckets.get(day) ?? 0) + 1);
+    }
+    const linksCreatedPerDay = [...dayBuckets.entries()]
+        .map(([date, count]) => ({ date, links_created: count }))
+        .sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+    // ── Cohorts ──
+    const byCreator = aggregateCohort(matching, (r) => r.created_by_user_id);
+    const byCollection = input.collection_id !== undefined
+        ? aggregateCohort(matching, (r) => r.collection_id)
+        : [];
+    const initial = {
+        filters: {
+            date_from: input.date_from ?? null,
+            date_to: input.date_to ?? null,
+            collection_id: input.collection_id ?? null,
+            created_by_user_id: input.created_by_user_id ?? null,
+            top_n: input.top_n,
+        },
+        totals: {
+            link_count: linkCount,
+            total_views: totalViews,
+            mean_views: meanViews,
+            median_views: medianViews,
+        },
+        status_distribution: statusDistribution,
+        top_links: topLinks,
+        time_series: {
+            links_created_per_day: linksCreatedPerDay,
+            views_per_day: null,
+        },
+        cohorts: {
+            by_creator: byCreator,
+            by_collection: byCollection,
+        },
+        truncated: enumeratorTruncated,
+    };
+    if (enumeratorTruncated) {
+        initial.truncation_reason =
+            `Enumerator stopped at the internal cap of ${ENUMERATOR_HARD_CAP} share links; report reflects a partial dataset.`;
+    }
+    return enforceResponseBudget(initial);
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function parseLowerBound(value) {
+    if (value === undefined)
+        return null;
+    // Bare YYYY-MM-DD → start of day in UTC.
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return Date.parse(`${value}T00:00:00.000Z`);
+    }
+    return Date.parse(value);
+}
+function parseUpperBound(value) {
+    if (value === undefined)
+        return null;
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return Date.parse(`${value}T23:59:59.999Z`);
+    }
+    return Date.parse(value);
+}
+function toIsoDay(value) {
+    const ms = Date.parse(value);
+    if (Number.isNaN(ms))
+        return null;
+    return new Date(ms).toISOString().slice(0, 10);
+}
+function computeMedian(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const n = sorted.length;
+    if (n === 0)
+        return 0;
+    const mid = Math.floor(n / 2);
+    if (n % 2 === 1)
+        return sorted[mid] ?? 0;
+    const left = sorted[mid - 1] ?? 0;
+    const right = sorted[mid] ?? 0;
+    return (left + right) / 2;
+}
+function aggregateCohort(rows, keyFn) {
+    const buckets = new Map();
+    for (const row of rows) {
+        const key = keyFn(row);
+        if (key === null)
+            continue;
+        let bucket = buckets.get(key);
+        if (bucket === undefined) {
+            bucket = { link_count: 0, view_count: 0 };
+            buckets.set(key, bucket);
+        }
+        bucket.link_count += 1;
+        bucket.view_count += row.view_count;
+    }
+    return [...buckets.entries()]
+        .map(([key, v]) => ({ key, link_count: v.link_count, view_count: v.view_count }))
+        .sort((a, b) => {
+        if (b.link_count !== a.link_count)
+            return b.link_count - a.link_count;
+        if (b.view_count !== a.view_count)
+            return b.view_count - a.view_count;
+        return a.key.localeCompare(b.key);
+    });
+}
+// ── Response-budget enforcement ─────────────────────────────────────
+const REDUCED_TOP_LIMIT = 5;
+const REDUCED_COHORT_LIMIT = 10;
+const REDUCED_TIMESERIES_LIMIT = 30;
+/**
+ * Aggregate reports tend to be small (totals, distribution, top-N), but a
+ * very wide creator cohort or a long date-range time series could push us
+ * over budget. If the serialised report exceeds {@link HARD_CAP_TOKENS},
+ * trim sample-heavy fields in priority order:
+ *   1. cap `top_links`, `cohorts.*`, and `time_series.links_created_per_day`
+ *      to small limits;
+ *   2. if still over, mark `truncated: true` regardless of enumerator
+ *      truncation and return.
+ */
+function enforceResponseBudget(report) {
+    if (estimateTokens(JSON.stringify(report)) <= HARD_CAP_TOKENS) {
+        return report;
+    }
+    const trimmed = {
+        ...report,
+        top_links: report.top_links.slice(0, REDUCED_TOP_LIMIT),
+        time_series: {
+            ...report.time_series,
+            links_created_per_day: report.time_series.links_created_per_day.slice(-REDUCED_TIMESERIES_LIMIT),
+        },
+        cohorts: {
+            by_creator: report.cohorts.by_creator.slice(0, REDUCED_COHORT_LIMIT),
+            by_collection: report.cohorts.by_collection.slice(0, REDUCED_COHORT_LIMIT),
+        },
+        truncated: true,
+        truncation_reason: report.truncation_reason !== undefined
+            ? `${report.truncation_reason} Additionally, top/cohort/time-series lists were trimmed to fit the response budget.`
+            : 'Top, cohort, and time-series lists were trimmed to fit the response budget.',
+    };
+    return trimmed;
+}
+//# sourceMappingURL=analyze-share-links.js.map

package/dist/tools/insights/analyze-share-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-share-links.js","sourceRoot":"","sources":["../../../src/tools/insights/analyze-share-links.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,EAAE;AACF,yEAAyE;AACzE,uDAAuD;AACvD,yEAAyE;AACzE,iDAAiD;AACjD,EAAE;AACF,6DAA6D;AAC7D,yEAAyE;AACzE,yEAAyE;AACzE,kEAAkE;AAClE,qCAAqC;AACrC,EAAE;AACF,yEAAyE;AACzE,mEAAmE;AACnE,iCAAiC;AACjC,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,mDAAmD;AAEnD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAqB,MAAM,6BAA6B,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAEvF,uEAAuE;AAEvE,MAAM,CAAC,MAAM,+BAA+B,GAC1C,iEAAiE;IACjE,mEAAmE;IACnE,sEAAsE;IACtE,kEAAkE;IAClE,iEAAiE;IACjE,sEAAsE;IACtE,uEAAuE;IACvE,sDAAsD,CAAC;AAEzD,uEAAuE;AAEvE,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAChC,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC;AAC5B,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC;KAC1C,MAAM,CAAC;IACN,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;QAC3C,OAAO,EAAE,4DAA4D;KACtE,CAAC;SACD,QAAQ,EAAE;IACb,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;QAC3C,OAAO,EAAE,0DAA0D;KACpE,CAAC;SACD,QAAQ,EAAE;IACb,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC3C,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;CACrE,CAAC;KACD,MAAM,EAAE,CAAC;AAkIZ,MAAM,OAAO,qBAAqB;IAIH;IAHpB,IAAI,GAAG,qBAAqB,CAAC;IAC7B,WAAW,GAAG,+BAA+B,CAAC;IAEvD,YAA6B,IAA2B;QAA3B,SAAI,GAAJ,IAAI,CAAuB;IAAG,CAAC;IAE5D,KAAK,CAAC,GAAG,CAAC,WAAmC,EAAE;QAC7C,IAAI,MAAsC,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,GAAG,4BAA4B,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,eAAe,CACpB,YAAY,EACZ,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CACrD;aACF,CAAC;QACJ,CAAC;QAED,gEAAgE;QAChE,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACnE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACxC,IAAI,MAAM,GAAG,IAAI,EAAE,CAAC;gBAClB,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,KAAK,EAAE,eAAe,CACpB,YAAY,EACZ,8BAA8B,CAC/B;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;QAC1D,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;YACnB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC;QAChD,CAAC;QAED,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC1E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,UAAU,0BAA0B,CACxC,IAA2B;IAE3B,OAAO,IAAI,qBAAqB,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,uEAAuE;AAEvE;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,IAAiC,EACjC,mBAA4B,EAC5B,KAAqC;IAErC,eAAe;IACf,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE;QACnC,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACtC,IAAI,GAAG,CAAC,aAAa,KAAK,KAAK,CAAC,aAAa;gBAAE,OAAO,KAAK,CAAC;QAC9D,CAAC;QACD,IAAI,KAAK,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;YAC3C,IAAI,GAAG,CAAC,kBAAkB,KAAK,KAAK,CAAC,kBAAkB;gBAAE,OAAO,KAAK,CAAC;QACxE,CAAC;QACD,IAAI,MAAM,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACrC,MAAM,OAAO,GAAG,GAAG,CAAC,UAAU,CAAC;YAC/B,IAAI,OAAO,KAAK,IAAI;gBAAE,OAAO,KAAK,CAAC;YACnC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACtC,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC1C,IAAI,MAAM,KAAK,IAAI,IAAI,SAAS,GAAG,MAAM;gBAAE,OAAO,KAAK,CAAC;YACxD,IAAI,IAAI,KAAK,IAAI,IAAI,SAAS,GAAG,IAAI;gBAAE,OAAO,KAAK,CAAC;QACtD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,eAAe;IACf,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7D,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;IAClC,MAAM,SAAS,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC;IAClE,MAAM,WAAW,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAEvE,4BAA4B;IAC5B,MAAM,kBAAkB,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IACjE,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,yEAAyE;IACzE,MAAM,aAAa,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAChD,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;YAAE,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;QACtE,MAAM,GAAG,GAAG,CAAC,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,CAAC,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACjE,OAAO,GAAG,GAAG,GAAG,CAAC;IACnB,CAAC,CAAC,CAAC;IACH,MAAM,QAAQ,GAAwB,aAAa;SAChD,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,UAAU,EAAE,CAAC,CAAC,UAAU;KACzB,CAAC,CAAC,CAAC;IAEN,8CAA8C;IAC9C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,UAAU,KAAK,IAAI;YAAE,SAAS;QACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACrC,IAAI,GAAG,KAAK,IAAI;YAAE,SAAS;QAC3B,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,MAAM,kBAAkB,GAA+B,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC;SAC7E,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;SACxD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpE,gBAAgB;IAChB,MAAM,SAAS,GAAG,eAAe,CAC/B,QAAQ,EACR,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAC5B,CAAC;IACF,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,KAAK,SAAS;QACpD,CAAC,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;QACnD,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,OAAO,GAA6B;QACxC,OAAO,EAAE;YACP,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;YAClC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;YAC9B,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;YAC1C,kBAAkB,EAAE,KAAK,CAAC,kBAAkB,IAAI,IAAI;YACpD,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB;QACD,MAAM,EAAE;YACN,UAAU,EAAE,SAAS;YACrB,WAAW,EAAE,UAAU;YACvB,UAAU,EAAE,SAAS;YACrB,YAAY,EAAE,WAAW;SAC1B;QACD,mBAAmB,EAAE,kBAAkB;QACvC,SAAS,EAAE,QAAQ;QACnB,WAAW,EAAE;YACX,qBAAqB,EAAE,kBAAkB;YACzC,aAAa,EAAE,IAAI;SACpB;QACD,OAAO,EAAE;YACP,UAAU,EAAE,SAAS;YACrB,aAAa,EAAE,YAAY;SAC5B;QACD,SAAS,EAAE,mBAAmB;KAC/B,CAAC;IACF,IAAI,mBAAmB,EAAE,CAAC;QACxB,OAAO,CAAC,iBAAiB;YACvB,6CAA6C,mBAAmB,kDAAkD,CAAC;IACvH,CAAC;IAED,OAAO,qBAAqB,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC;AAED,uEAAuE;AAEvE,SAAS,eAAe,CAAC,KAAyB;IAChD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,yCAAyC;IACzC,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,gBAAgB,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,eAAe,CAAC,KAAyB;IAChD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,gBAAgB,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,QAAQ,CAAC,KAAa;IAC7B,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,aAAa,CAAC,MAA6B;IAClD,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;IACxB,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,eAAe,CACtB,IAAiC,EACjC,KAA2C;IAE3C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsD,CAAC;IAC9E,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,GAAG,KAAK,IAAI;YAAE,SAAS;QAC3B,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;YAC1C,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC3B,CAAC;QACD,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC;QACvB,MAAM,CAAC,UAAU,IAAI,GAAG,CAAC,UAAU,CAAC;IACtC,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;SAC1B,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;SAChF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACb,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;YAAE,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;QACtE,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;YAAE,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;QACtE,OAAO,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACP,CAAC;AAED,uEAAuE;AAEvE,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAC5B,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAChC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAEpC;;;;;;;;;GASG;AACH,SAAS,qBAAqB,CAC5B,MAAgC;IAEhC,IAAI,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,eAAe,EAAE,CAAC;QAC9D,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,OAAO,GAA6B;QACxC,GAAG,MAAM;QACT,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC;QACvD,WAAW,EAAE;YACX,GAAG,MAAM,CAAC,WAAW;YACrB,qBAAqB,EAAE,MAAM,CAAC,WAAW,CAAC,qBAAqB,CAAC,KAAK,CACnE,CAAC,wBAAwB,CAC1B;SACF;QACD,OAAO,EAAE;YACP,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC;YACpE,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC;SAC3E;QACD,SAAS,EAAE,IAAI;QACf,iBAAiB,EACf,MAAM,CAAC,iBAAiB,KAAK,SAAS;YACpC,CAAC,CAAC,GAAG,MAAM,CAAC,iBAAiB,sFAAsF;YACnH,CAAC,CAAC,6EAA6E;KACpF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/tools/insights/insight-cache.d.ts

@@ -0,0 +1,36 @@
+import type { ShareLinkEnumerator } from './analyze-share-links.js';
+/** Default cache lifetime per the spec — 10 minutes. */
+export declare const DEFAULT_INSIGHT_CACHE_TTL_MS: number;
+export interface InsightCacheOptions {
+    /** Cache lifetime in milliseconds. Defaults to {@link DEFAULT_INSIGHT_CACHE_TTL_MS}. */
+    ttlMs?: number;
+    /** Clock source. Defaults to `Date.now`; supply for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * Diagnostic shape exposed for tests. Production callers should ignore
+ * the extra methods — they exist so unit tests can assert cache hit /
+ * miss behaviour without poking the closure.
+ */
+export interface CachedEnumeratorWithStats extends ShareLinkEnumerator {
+    /** Returns true when a cached entry exists and is still fresh. */
+    hasFreshEntry(): boolean;
+    /** Force-expire the cached entry, if any. */
+    invalidate(): void;
+}
+/**
+ * Wrap a `ShareLinkEnumerator` with a 10-minute (default) in-memory
+ * cache. Multiple calls within the TTL window return the same cached
+ * result; concurrent calls during a fetch share the same in-flight
+ * promise. Errors are surfaced to every concurrent caller but are NOT
+ * cached — the next call after a failure will re-fetch.
+ *
+ * Pure function over the enumerator — does not mutate the input.
+ *
+ * The return shape exposes test-introspection methods
+ * ({@link CachedEnumeratorWithStats}) but assignment to a plain
+ * `ShareLinkEnumerator` is the production usage and discards them at
+ * the type level.
+ */
+export declare function buildCachedShareLinkEnumerator(inner: ShareLinkEnumerator, options?: InsightCacheOptions): CachedEnumeratorWithStats;
+//# sourceMappingURL=insight-cache.d.ts.map

package/dist/tools/insights/insight-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight-cache.d.ts","sourceRoot":"","sources":["../../../src/tools/insights/insight-cache.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,mBAAmB,EAEpB,MAAM,0BAA0B,CAAC;AAGlC,wDAAwD;AACxD,eAAO,MAAM,4BAA4B,QAAiB,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAaD;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,kEAAkE;IAClE,aAAa,IAAI,OAAO,CAAC;IACzB,6CAA6C;IAC7C,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE,mBAAwB,GAChC,yBAAyB,CAuD3B"}

package/dist/tools/insights/insight-cache.js

@@ -0,0 +1,98 @@
+// ── Insight Cache (T5) ──────────────────────────────────────────────
+//
+// In-memory TTL cache wrapper around the share-link enumerator. The four
+// distribution-insight tools (analyze_share_links, report_asset_activation,
+// report_top_assets, report_stale_assets) all enumerate the workspace's
+// share-link list — three paginated GETs per status bucket per call.
+// Without caching, four insight tool calls in the same conversation hit
+// the upstream API up to 12 times. Caching the enumerator output for ten
+// minutes drops that to one round-trip per ten-minute window, regardless
+// of which (or how many) insight tools are called.
+//
+// Caching policy:
+//   * Cache LIFE: 10 minutes by default; configurable.
+//   * Cache KEY: implicit — each cache instance is per-workspace because
+//     the MCP server is single-workspace and a new server instance is
+//     created per stdio client. There is exactly one shared enumerator
+//     in `createServer()`.
+//   * Cache POLLUTION: failures are NOT cached. A bad upstream response
+//     should be retried, not memoised for ten minutes.
+//   * SINGLE-FLIGHT: concurrent callers during a fetch share the same
+//     in-flight promise. Without this, four insight tools booting at the
+//     same time would issue four parallel enumerations even though we
+//     intend to serve them all from one round-trip.
+//
+// Type discipline: never uses `any`. The cache only operates on the
+// already-typed `ShareLinkEnumerator` surface — it does not need
+// generics because the enumerator is the only memoisable boundary in
+// the insight surface.
+/** Default cache lifetime per the spec — 10 minutes. */
+export const DEFAULT_INSIGHT_CACHE_TTL_MS = 10 * 60 * 1000;
+/**
+ * Wrap a `ShareLinkEnumerator` with a 10-minute (default) in-memory
+ * cache. Multiple calls within the TTL window return the same cached
+ * result; concurrent calls during a fetch share the same in-flight
+ * promise. Errors are surfaced to every concurrent caller but are NOT
+ * cached — the next call after a failure will re-fetch.
+ *
+ * Pure function over the enumerator — does not mutate the input.
+ *
+ * The return shape exposes test-introspection methods
+ * ({@link CachedEnumeratorWithStats}) but assignment to a plain
+ * `ShareLinkEnumerator` is the production usage and discards them at
+ * the type level.
+ */
+export function buildCachedShareLinkEnumerator(inner, options = {}) {
+    const ttlMs = options.ttlMs ?? DEFAULT_INSIGHT_CACHE_TTL_MS;
+    const now = options.now ?? Date.now;
+    let entry = null;
+    let inflight = null;
+    const tryRefresh = () => {
+        if (inflight !== null)
+            return inflight;
+        const fetchPromise = (async () => {
+            try {
+                const result = await inner.enumerate();
+                if (result.ok) {
+                    entry = {
+                        expires_at: now() + ttlMs,
+                        // Defensive copy — the cache owns its rows independently of
+                        // the caller, so external mutation of the returned array
+                        // does not corrupt subsequent cache hits.
+                        result: {
+                            ok: true,
+                            rows: [...result.rows],
+                            truncated: result.truncated,
+                        },
+                    };
+                }
+                // Failures are intentionally NOT cached.
+                return result;
+            }
+            finally {
+                inflight = null;
+            }
+        })();
+        inflight = fetchPromise;
+        return fetchPromise;
+    };
+    return {
+        enumerate: async () => {
+            if (entry !== null && entry.expires_at > now()) {
+                // Return a fresh copy of the cached result so callers can
+                // mutate their local view without corrupting future cache hits.
+                return {
+                    ok: true,
+                    rows: [...entry.result.rows],
+                    truncated: entry.result.truncated,
+                };
+            }
+            return tryRefresh();
+        },
+        hasFreshEntry: () => entry !== null && entry.expires_at > now(),
+        invalidate: () => {
+            entry = null;
+        },
+    };
+}
+//# sourceMappingURL=insight-cache.js.map

package/dist/tools/insights/insight-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight-cache.js","sourceRoot":"","sources":["../../../src/tools/insights/insight-cache.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,EAAE;AACF,yEAAyE;AACzE,4EAA4E;AAC5E,wEAAwE;AACxE,qEAAqE;AACrE,wEAAwE;AACxE,yEAAyE;AACzE,yEAAyE;AACzE,mDAAmD;AACnD,EAAE;AACF,kBAAkB;AAClB,uDAAuD;AACvD,yEAAyE;AACzE,sEAAsE;AACtE,uEAAuE;AACvE,2BAA2B;AAC3B,wEAAwE;AACxE,uDAAuD;AACvD,sEAAsE;AACtE,yEAAyE;AACzE,sEAAsE;AACtE,oDAAoD;AACpD,EAAE;AACF,oEAAoE;AACpE,iEAAiE;AACjE,qEAAqE;AACrE,uBAAuB;AAQvB,wDAAwD;AACxD,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAgC3D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,8BAA8B,CAC5C,KAA0B,EAC1B,UAA+B,EAAE;IAEjC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,4BAA4B,CAAC;IAC5D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAEpC,IAAI,KAAK,GAAsB,IAAI,CAAC;IACpC,IAAI,QAAQ,GAAoC,IAAI,CAAC;IAErD,MAAM,UAAU,GAAG,GAA6B,EAAE;QAChD,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,QAAQ,CAAC;QAEvC,MAAM,YAAY,GAAG,CAAC,KAAK,IAA8B,EAAE;YACzD,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,SAAS,EAAE,CAAC;gBACvC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;oBACd,KAAK,GAAG;wBACN,UAAU,EAAE,GAAG,EAAE,GAAG,KAAK;wBACzB,4DAA4D;wBAC5D,yDAAyD;wBACzD,0CAA0C;wBAC1C,MAAM,EAAE;4BACN,EAAE,EAAE,IAAI;4BACR,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;4BACtB,SAAS,EAAE,MAAM,CAAC,SAAS;yBAC5B;qBACF,CAAC;gBACJ,CAAC;gBACD,yCAAyC;gBACzC,OAAO,MAAM,CAAC;YAChB,CAAC;oBAAS,CAAC;gBACT,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QAEL,QAAQ,GAAG,YAAY,CAAC;QACxB,OAAO,YAAY,CAAC;IACtB,CAAC,CAAC;IAEF,OAAO;QACL,SAAS,EAAE,KAAK,IAA8B,EAAE;YAC9C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,GAAG,GAAG,EAAE,EAAE,CAAC;gBAC/C,0DAA0D;gBAC1D,gEAAgE;gBAChE,OAAO;oBACL,EAAE,EAAE,IAAI;oBACR,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;oBAC5B,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS;iBAClC,CAAC;YACJ,CAAC;YACD,OAAO,UAAU,EAAE,CAAC;QACtB,CAAC;QACD,aAAa,EAAE,GAAG,EAAE,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,GAAG,GAAG,EAAE;QAC/D,UAAU,EAAE,GAAG,EAAE;YACf,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/insights/report-asset-activation.d.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+import { type McpToolError } from '../../conventions/errors.js';
+import type { ShareLinkEnumerator, ShareLinkRow } from './analyze-share-links.js';
+export declare const REPORT_ASSET_ACTIVATION_DESCRIPTION: string;
+export declare const DEFAULT_TOP_N = 10;
+export declare const MAX_TOP_N = 50;
+/** Default look-back window when neither `date_from` nor `date_to` is set. */
+export declare const DEFAULT_LOOKBACK_DAYS = 30;
+/**
+ * `date_from` / `date_to` are inclusive ISO-8601 date or datetime
+ * strings. If only a date is supplied (e.g. `2026-04-14`) it is
+ * interpreted as the start (00:00:00Z) for `date_from` or the end
+ * (23:59:59.999Z) for `date_to`. When BOTH are omitted, the analyzer
+ * defaults to the last {@link DEFAULT_LOOKBACK_DAYS} days.
+ */
+export declare const ReportAssetActivationInputSchema: z.ZodObject<{
+    date_from: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    date_to: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    collection_id: z.ZodOptional<z.ZodString>;
+    top_n: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    top_n: number;
+    collection_id?: string | undefined;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+}, {
+    collection_id?: string | undefined;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+    top_n?: number | undefined;
+}>;
+export type ReportAssetActivationInput = z.input<typeof ReportAssetActivationInputSchema>;
+export type ReportAssetActivationInputResolved = z.output<typeof ReportAssetActivationInputSchema>;
+/**
+ * Narrow shape consumed from `dashboard/common-data`. The upstream
+ * surface is opaque (`unknown` at the client layer), so the reader is
+ * responsible for parsing it via zod and returning `null` when the shape
+ * does not carry a usable `total_assets` count.
+ */
+export interface DashboardSnapshot {
+    /** Total number of assets in the workspace. */
+    total_assets: number;
+}
+/**
+ * Read-only adapter for the workspace dashboard projection. Returns
+ * `ok: true` with a parsed snapshot, `ok: true` with `snapshot: null`
+ * when the upstream shape did not carry the fields we need (the report
+ * surfaces `total_assets: null` and `activation_rate: null` rather than
+ * crashing), or `ok: false` with a typed `McpToolError` on a transport
+ * failure.
+ */
+export interface DashboardCommonDataReader {
+    read(): Promise<{
+        ok: true;
+        snapshot: DashboardSnapshot | null;
+    } | {
+        ok: false;
+        error: McpToolError;
+    }>;
+}
+export interface AssetActivationSummary {
+    /** Workspace-wide asset count. `null` when the dashboard reader could not parse the upstream shape. */
+    total_assets: number | null;
+    /** Number of distinct assets touched by share-link activity in the matching range. */
+    assets_with_distribution_activity: number;
+    /** Ratio in [0, 1]; `null` when `total_assets` is unknown. */
+    activation_rate: number | null;
+    /** `total_assets - assets_with_distribution_activity`; `null` when `total_assets` is unknown. */
+    dormant_count: number | null;
+}
+export interface AssetFirstSharedPoint {
+    /** ISO date (YYYY-MM-DD) bucket. */
+    date: string;
+    /** Number of assets that were first shared on this date (within the matching range). */
+    count: number;
+}
+export interface TopActivatedAsset {
+    id: string;
+    /** Best-effort title pulled from the most-recent share-link row covering this asset. */
+    title: string | null;
+    /** Number of share links covering this asset within the matching range. */
+    share_link_count: number;
+    /** Sum of view counts across those share links. */
+    total_views: number;
+}
+export interface ActivationCohortEntry {
+    /** User id for `by_user`, collection id for `by_collection`. */
+    user_id?: string;
+    collection_id?: string;
+    /** Number of distinct activated assets attributed to this cohort. */
+    activated_assets: number;
+}
+export interface AssetActivationReport {
+    /** Inputs as resolved (after defaults / filters applied). */
+    filters: {
+        date_from: string | null;
+        date_to: string | null;
+        collection_id: string | null;
+        top_n: number;
+    };
+    summary: AssetActivationSummary;
+    time_series: {
+        assets_first_shared_per_day: AssetFirstSharedPoint[];
+    };
+    top_activated_assets: TopActivatedAsset[];
+    cohort_breakdown: {
+        by_user: Array<{
+            user_id: string;
+            activated_assets: number;
+        }>;
+        by_collection: Array<{
+            collection_id: string;
+            activated_assets: number;
+        }>;
+    };
+    /** True when the share-link enumerator hit its hard cap or the response was trimmed for budget. */
+    truncated: boolean;
+    truncation_reason?: string;
+}
+export interface ReportAssetActivationDeps {
+    enumerator: ShareLinkEnumerator;
+    dashboard: DashboardCommonDataReader;
+}
+export type ReportAssetActivationOutcome = {
+    ok: true;
+    report: AssetActivationReport;
+} | {
+    ok: false;
+    error: McpToolError;
+};
+export declare class ReportAssetActivationTool {
+    private readonly deps;
+    readonly name = "report_asset_activation";
+    readonly description: string;
+    constructor(deps: ReportAssetActivationDeps);
+    run(rawInput?: ReportAssetActivationInput): Promise<ReportAssetActivationOutcome>;
+}
+export declare function buildReportAssetActivationTool(deps: ReportAssetActivationDeps): ReportAssetActivationTool;
+/**
+ * Build the asset-activation report from a flat list of share-link rows
+ * plus an optional workspace-snapshot denominator. Pure function,
+ * exported for direct test access.
+ *
+ * `dashboardSnapshot === null` means the workspace asset-count is
+ * unavailable; the report surfaces `total_assets`, `activation_rate`,
+ * and `dormant_count` as `null` per the degradation contract.
+ */
+export declare function buildReport(rows: ReadonlyArray<ShareLinkRow>, enumeratorTruncated: boolean, dashboardSnapshot: DashboardSnapshot | null, input: ReportAssetActivationInputResolved): AssetActivationReport;
+//# sourceMappingURL=report-asset-activation.d.ts.map

package/dist/tools/insights/report-asset-activation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-asset-activation.d.ts","sourceRoot":"","sources":["../../../src/tools/insights/report-asset-activation.ts"],"names":[],"mappings":"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"}