@pitcher/cli-scripts 3.1.1 → 3.3.0

package/dist/src/mcp/groups.d.ts

@@ -0,0 +1,42 @@
+/**
+ * PIT-10114: tool groups, the per-org policy and the access class of every tool.
+ *
+ * An org sets each group to off | read | read_write in `pitcher_organization.settings.mcp.groups`; `settings.mcp.access`
+ * stays the master switch and the ceiling (read_only caps every group at read). L&D is off unless the org turns it on.
+ * Inactive tools are absent from tools/list, and a call to one is refused and recorded.
+ */
+import type { ToolDescriptor } from './tools/types.js';
+export declare const TOOL_GROUPS: readonly ["content", "sharing", "analytics", "roleplay", "training_studio", "ld", "admin", "search", "developer"];
+export type ToolGroup = (typeof TOOL_GROUPS)[number];
+/** Policy class: 'write' = changes data OR exists only to lead to a change (PIT-10113 _propose and _commit). */
+export type ToolAccess = 'read' | 'write';
+export type GroupLevel = 'off' | 'read' | 'read_write';
+export type ToolPolicy = Readonly<Record<ToolGroup, GroupLevel>>;
+/**
+ * Groups an org may configure (developer is local-only). Django mirrors this list (`MCP_GROUPS` in
+ * ng-rest-api `pitcher/utils/validators.py`, which refuses unknown groups): add a group THERE FIRST.
+ */
+export declare const CONFIGURABLE_GROUPS: readonly ToolGroup[];
+export interface ResolvedPolicy {
+    policy: ToolPolicy;
+    /** Invalid or unknown keys ('groups' when malformed); logged once per fetch, never shown to users. */
+    warnings: string[];
+}
+export declare const OFF_POLICY: ToolPolicy;
+/** `settings.mcp` → per-group levels. Fails closed: no valid `access`, malformed `groups`, an invalid level. */
+export declare function resolveToolPolicy(mcp: unknown): ResolvedPolicy;
+type AccessFields = Pick<ToolDescriptor, 'access' | 'readOnly' | 'write' | 'alwaysDestructive'>;
+/** The policy class of a tool: explicit `access`, else the legacy read-only predicate (frozen for today's tools). */
+export declare function accessOf(t: AccessFields): ToolAccess;
+export type ToolVerdict = 'allowed' | 'GROUP_INACTIVE' | 'GROUP_READ_ONLY' | 'UNGROUPED';
+export declare function toolVerdict(policy: ToolPolicy, t: AccessFields & Pick<ToolDescriptor, 'group'>): ToolVerdict;
+/** A prompt drives a write tool unless flagged `readOnly`, so a group at `read` serves only the read-only ones. */
+export declare function allowsPrompt(policy: ToolPolicy, p: {
+    group?: ToolGroup;
+    readOnly?: true;
+}): boolean;
+/** Hard rules on every registered descriptor: a group, and no write tool classed `read`. */
+export declare function checkDescriptor(t: ToolDescriptor): ToolDescriptor;
+/** Assign a whole module to a group; a descriptor that already names another group throws. */
+export declare function inGroup(group: ToolGroup, tools: ToolDescriptor[]): ToolDescriptor[];
+export {};

package/dist/src/mcp/groups.js

@@ -0,0 +1,89 @@
+export const TOOL_GROUPS = [
+    'content',
+    'sharing',
+    'analytics',
+    'roleplay',
+    'training_studio',
+    'ld',
+    'admin',
+    'search',
+    'developer',
+];
+/**
+ * Groups an org may configure (developer is local-only). Django mirrors this list (`MCP_GROUPS` in
+ * ng-rest-api `pitcher/utils/validators.py`, which refuses unknown groups): add a group THERE FIRST.
+ */
+export const CONFIGURABLE_GROUPS = TOOL_GROUPS.filter((g) => g !== 'developer');
+const DEFAULT_OFF = new Set(['ld']); // N1 ruling, 2026-11-10
+const RANK = { off: 0, read: 1, read_write: 2 };
+const LEVELS = new Set(['off', 'read', 'read_write']);
+/** The keys `settings.mcp` may hold; mirrors `MCP_KEYS` in ng-rest-api `pitcher/utils/validators.py`. */
+const MCP_KEYS = new Set(['access', 'groups']);
+export const OFF_POLICY = Object.freeze(Object.fromEntries(TOOL_GROUPS.map((g) => [g, 'off'])));
+/** `settings.mcp` → per-group levels. Fails closed: no valid `access`, malformed `groups`, an invalid level. */
+export function resolveToolPolicy(mcp) {
+    const raw = (mcp && typeof mcp === 'object' && !Array.isArray(mcp) ? mcp : {});
+    if (raw.access !== 'full' && raw.access !== 'read_only')
+        return { policy: OFF_POLICY, warnings: [] };
+    const ceiling = raw.access === 'full' ? 'read_write' : 'read';
+    const g0 = raw.groups ?? {};
+    if (typeof g0 !== 'object' || Array.isArray(g0))
+        return { policy: OFF_POLICY, warnings: ['groups'] };
+    const groups = g0;
+    const warnings = [
+        // A top-level typo (`group`, `Groups`) leaves `groups` absent, so every group takes its default. Django refuses
+        // unknown keys at save (ng-rest-api#1809, `MCP_KEYS`); report any that reach us anyway, as `mcp.<key>`.
+        ...Object.keys(raw).filter((k) => !MCP_KEYS.has(k)).map((k) => `mcp.${k}`),
+        ...Object.keys(groups).filter((k) => !CONFIGURABLE_GROUPS.includes(k)),
+    ];
+    const policy = { ...OFF_POLICY };
+    for (const g of CONFIGURABLE_GROUPS) {
+        const v = groups[g];
+        let requested;
+        if (v === undefined)
+            requested = DEFAULT_OFF.has(g) ? 'off' : ceiling;
+        else if (typeof v === 'string' && LEVELS.has(v))
+            requested = v;
+        else {
+            requested = 'off';
+            warnings.push(g);
+        }
+        policy[g] = RANK[requested] <= RANK[ceiling] ? requested : ceiling;
+    }
+    return { policy: Object.freeze(policy), warnings };
+}
+/** The policy class of a tool: explicit `access`, else the legacy read-only predicate (frozen for today's tools). */
+export function accessOf(t) {
+    return t.access ?? (t.readOnly && !t.write && !t.alwaysDestructive ? 'read' : 'write');
+}
+export function toolVerdict(policy, t) {
+    if (!t.group)
+        return 'UNGROUPED'; // fail closed
+    const level = policy[t.group];
+    if (level === 'off')
+        return 'GROUP_INACTIVE';
+    return accessOf(t) === 'read' || level === 'read_write' ? 'allowed' : 'GROUP_READ_ONLY';
+}
+/** A prompt drives a write tool unless flagged `readOnly`, so a group at `read` serves only the read-only ones. */
+export function allowsPrompt(policy, p) {
+    if (!p.group)
+        return false;
+    const level = policy[p.group];
+    return level === 'read_write' || (level === 'read' && p.readOnly === true);
+}
+/** Hard rules on every registered descriptor: a group, and no write tool classed `read`. */
+export function checkDescriptor(t) {
+    if (!t.group)
+        throw new Error(`${t.name}: no tool group`);
+    if ((t.write || t.alwaysDestructive) && t.access === 'read')
+        throw new Error(`${t.name}: a write tool cannot be access 'read'`);
+    return t;
+}
+/** Assign a whole module to a group; a descriptor that already names another group throws. */
+export function inGroup(group, tools) {
+    return tools.map((t) => {
+        if (t.group && t.group !== group)
+            throw new Error(`${t.name}: group ${t.group} conflicts with ${group}`);
+        return checkDescriptor({ ...t, group });
+    });
+}

package/dist/src/mcp/hosted.d.ts

@@ -1,3 +1,6 @@
+import type { AppViewDescriptor } from './apps/types.js';
+import { type ToolPolicy } from './groups.js';
+import type { ResourceDescriptor } from './resources/types.js';
 import type { PromptDescriptor } from './prompts/types.js';
 import type { BuildServerOptions } from './server.js';
 import type { ToolDescriptor } from './tools/types.js';
@@ -32,5 +35,38 @@ export declare const hostedTools: ToolDescriptor[];
  * A write tool is never registered, so calling one is "unknown tool", not a refused write.
  */
 export declare const hostedReadOnlyTools: ToolDescriptor[];
+/** MCP Apps tools (PIT-10066), hosted-shaped: the same file/id runtime guards as every hosted tool. */
+export declare const hostedAppTools: ToolDescriptor[];
+/** A read-only server's app tool: read class, and never a PIT-10113 confirm tool, whatever its `access` says. */
+export declare const isHostedReadOnlyAppTool: (t: ToolDescriptor) => boolean;
+/** The app tools a read-only server serves (same rule as hostedReadOnlyTools). */
+export declare const hostedReadOnlyAppTools: ToolDescriptor[];
 /** The prompts a read-only server serves: only those flagged `readOnly` (the rest drive a write tool). */
 export declare const readOnlyPrompts: PromptDescriptor[];
+/** The CLI-backed hosted tools this policy serves. */
+export declare const hostedToolsFor: (p: ToolPolicy) => ToolDescriptor[];
+/** What decides app-tool registration besides the policy: the enabled views, and whether a PIT-10113 signer exists. */
+export interface HostedFeatures {
+    views: AppViewDescriptor[];
+    proposals: boolean;
+}
+/** The app tools this policy serves: allowed, their view enabled, and a confirm tool only with a proposal signer. */
+export declare const hostedAppToolsFor: (p: ToolPolicy, f: HostedFeatures) => ToolDescriptor[];
+/**
+ * Views worth serving: only those with at least one surviving app tool. App tools are filtered by their own group
+ * first, so a view whose group is off (analytics off hides dsr-engagement) is never served.
+ */
+export declare const viewsFor: (p: ToolPolicy, f: HostedFeatures) => AppViewDescriptor[];
+/** Exactly the names buildServer registers for this policy and these features (one filter, used by build and recording). */
+export declare const hostedRegisteredNames: (p: ToolPolicy, f: HostedFeatures) => Set<string>;
+export declare const promptsFor: (p: ToolPolicy) => PromptDescriptor[];
+export declare const resourcesFor: (p: ToolPolicy) => ResourceDescriptor[];
+/** The HOSTED descriptor (hosted inputShape, never a LOCAL_ONLY name) by name. */
+export declare function hostedToolByName(name: string): ToolDescriptor | undefined;
+/**
+ * Whether `args` pass the hosted tool's input schema: the same `inputShape` object `registerTool` receives, so the
+ * mcp-server pre-inspection sees exactly the calls the SDK rejects before the callback (recorded as INVALID_ARGS).
+ */
+export declare function hostedArgsValid(t: ToolDescriptor, args: unknown): boolean;
+/** On = at least one hosted tool survives; an empty group (training_studio) does not keep the connector on. */
+export declare const policyIsOn: (p: ToolPolicy) => boolean;

package/dist/src/mcp/hosted.js

@@ -1,6 +1,10 @@
+import { z } from 'zod';
 import { fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
+import { allAppTools } from './apps/registry.js';
+import { accessOf, allowsPrompt, toolVerdict } from './groups.js';
 import { allPrompts } from './prompts/registry.js';
+import { allResources } from './resources/registry.js';
 import { allTools } from './registry.js';
 /**
  * The tool set served by the hosted (remote, OAuth) MCP server — PIT-8912.
@@ -110,6 +114,48 @@ export const hostedTools = allTools.filter((t) => !LOCAL_ONLY.has(t.name)).map(t
  * Read-only mode (the org's `settings.mcp.access` is `read_only`, PIT-9768): only the hosted tools that read.
  * A write tool is never registered, so calling one is "unknown tool", not a refused write.
  */
-export const hostedReadOnlyTools = hostedTools.filter((t) => t.readOnly && !t.write && !t.alwaysDestructive);
+export const hostedReadOnlyTools = hostedTools.filter((t) => accessOf(t) === 'read');
+/** MCP Apps tools (PIT-10066), hosted-shaped: the same file/id runtime guards as every hosted tool. */
+export const hostedAppTools = allAppTools.map(toHosted);
+/** A read-only server's app tool: read class, and never a PIT-10113 confirm tool, whatever its `access` says. */
+export const isHostedReadOnlyAppTool = (t) => accessOf(t) === 'read' && !t.confirm;
+/** The app tools a read-only server serves (same rule as hostedReadOnlyTools). */
+export const hostedReadOnlyAppTools = hostedAppTools.filter(isHostedReadOnlyAppTool);
 /** The prompts a read-only server serves: only those flagged `readOnly` (the rest drive a write tool). */
 export const readOnlyPrompts = allPrompts.filter((p) => p.readOnly === true);
+// ---------------------------------------------------------------------------------------------------------------------
+// PIT-10114: per-org tool groups. Every hosted list below is derived from the org's policy (`resolveToolPolicy`).
+const allowed = (p) => (t) => toolVerdict(p, t) === 'allowed';
+/** The CLI-backed hosted tools this policy serves. */
+export const hostedToolsFor = (p) => hostedTools.filter(allowed(p));
+/** The app tools this policy serves: allowed, their view enabled, and a confirm tool only with a proposal signer. */
+export const hostedAppToolsFor = (p, f) => {
+    const on = new Set(f.views.map((v) => v.name));
+    return hostedAppTools.filter((t) => allowed(p)(t) && (!t.ui || on.has(t.ui.view)) && (!t.confirm || f.proposals));
+};
+/**
+ * Views worth serving: only those with at least one surviving app tool. App tools are filtered by their own group
+ * first, so a view whose group is off (analytics off hides dsr-engagement) is never served.
+ */
+export const viewsFor = (p, f) => {
+    const used = new Set(hostedAppToolsFor(p, f).map((t) => t.ui.view));
+    return f.views.filter((v) => used.has(v.name));
+};
+/** Exactly the names buildServer registers for this policy and these features (one filter, used by build and recording). */
+export const hostedRegisteredNames = (p, f) => new Set([...hostedToolsFor(p), ...hostedAppToolsFor(p, f)].map((t) => t.name));
+export const promptsFor = (p) => allPrompts.filter((x) => allowsPrompt(p, x));
+export const resourcesFor = (p) => allResources.filter((r) => !r.group || p[r.group] !== 'off');
+const HOSTED_BY_NAME = new Map([...hostedTools, ...hostedAppTools].map((t) => [t.name, t]));
+/** The HOSTED descriptor (hosted inputShape, never a LOCAL_ONLY name) by name. */
+export function hostedToolByName(name) {
+    return HOSTED_BY_NAME.get(name);
+}
+/**
+ * Whether `args` pass the hosted tool's input schema: the same `inputShape` object `registerTool` receives, so the
+ * mcp-server pre-inspection sees exactly the calls the SDK rejects before the callback (recorded as INVALID_ARGS).
+ */
+export function hostedArgsValid(t, args) {
+    return z.object(t.inputShape).safeParse(args ?? {}).success;
+}
+/** On = at least one hosted tool survives; an empty group (training_studio) does not keep the connector on. */
+export const policyIsOn = (p) => hostedToolsFor(p).length > 0;

package/dist/src/mcp/index.d.ts

@@ -1,7 +1,13 @@
-export { buildServer, PITCHER_ICON, type McpRunContext, type BuildServerOptions } from './server.js';
-export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, } from './hosted.js';
+export { buildServer, PITCHER_ICON, CLI_SCRIPTS_VERSION, toolCallEvent, type McpRunContext, type BuildServerOptions, type ToolCallEvent, type ToolCallSink, } from './server.js';
+export { TOOL_GROUPS, CONFIGURABLE_GROUPS, OFF_POLICY, resolveToolPolicy, toolVerdict, accessOf, allowsPrompt, type ToolGroup, type ToolAccess, type GroupLevel, type ToolPolicy, type ResolvedPolicy, type ToolVerdict, } from './groups.js';
+export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, hostedAppTools, hostedReadOnlyAppTools, hostedToolsFor, hostedAppToolsFor, viewsFor, hostedRegisteredNames, promptsFor, resourcesFor, hostedToolByName, hostedArgsValid, policyIsOn, type HostedFeatures, } from './hosted.js';
+export { allAppViews, allAppTools } from './apps/registry.js';
+export { PROPOSAL_TTL_S, PROPOSAL_MAX_BYTES, PROPOSAL_TEXT_MAX_BYTES, TEXT_HOST_MODE, type ProposalClaims, type ProposalSigner, type HostClient, type Proposal, type CommitResult, } from './apps/confirm/types.js';
+export { APPS_RENDER_POLICY } from './renderPolicy.js';
+export { appViewUri, type AppViewDescriptor, type AppCsp } from './apps/types.js';
 export { allTools } from './registry.js';
 export { allPrompts } from './prompts/registry.js';
 export { allResources } from './resources/registry.js';
-export type { ToolDescriptor } from './tools/types.js';
+export type { ToolDescriptor, ToolUi, AppInjected } from './tools/types.js';
 export type { Credential } from '../core/credential.js';
+export { createCliError, isCliError, type CliError } from '../core/errors.js';

package/dist/src/mcp/index.js

@@ -1,6 +1,13 @@
 // Public entry `@pitcher/cli-scripts/mcp` — what the hosted MCP server (web/packages/mcp-server) consumes.
-export { buildServer, PITCHER_ICON } from './server.js';
-export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, } from './hosted.js';
+export { buildServer, PITCHER_ICON, CLI_SCRIPTS_VERSION, toolCallEvent, } from './server.js';
+export { TOOL_GROUPS, CONFIGURABLE_GROUPS, OFF_POLICY, resolveToolPolicy, toolVerdict, accessOf, allowsPrompt, } from './groups.js';
+export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, hostedAppTools, hostedReadOnlyAppTools, hostedToolsFor, hostedAppToolsFor, viewsFor, hostedRegisteredNames, promptsFor, resourcesFor, hostedToolByName, hostedArgsValid, policyIsOn, } from './hosted.js';
+export { allAppViews, allAppTools } from './apps/registry.js';
+export { PROPOSAL_TTL_S, PROPOSAL_MAX_BYTES, PROPOSAL_TEXT_MAX_BYTES, TEXT_HOST_MODE, } from './apps/confirm/types.js';
+export { APPS_RENDER_POLICY } from './renderPolicy.js';
+export { appViewUri } from './apps/types.js';
 export { allTools } from './registry.js';
 export { allPrompts } from './prompts/registry.js';
 export { allResources } from './resources/registry.js';
+// PIT-10113: the proposal signer (mcp-server) throws CliErrors so a commit maps them to the right code
+export { createCliError, isCliError } from '../core/errors.js';

package/dist/src/mcp/prompts/registry.js

@@ -4,12 +4,13 @@ import { dsrPrompts } from './dsr.js';
 import { announcementsPrompts } from './announcements.js';
 import { ldCanvasCoursePrompts } from './ldCanvasCourse.js';
 import { analyticsPrompts } from './analytics.js';
-// Every recipe prompt the server can expose. Mirrors mcp/registry.ts (allTools).
+const withGroup = (group, prompts) => prompts.map((p) => ({ ...p, group }));
+// Every recipe prompt the server can expose, each in the group of the tools it drives (PIT-10114). Mirrors mcp/registry.ts.
 export const allPrompts = [
-    ...emailTemplatePrompts,
-    ...dsrLandingPrompts,
-    ...dsrPrompts,
-    ...announcementsPrompts,
-    ...ldCanvasCoursePrompts,
-    ...analyticsPrompts,
+    ...withGroup('sharing', emailTemplatePrompts),
+    ...withGroup('sharing', dsrLandingPrompts),
+    ...withGroup('sharing', dsrPrompts),
+    ...withGroup('content', announcementsPrompts),
+    ...withGroup('ld', ldCanvasCoursePrompts),
+    ...withGroup('analytics', analyticsPrompts),
 ];

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

@@ -1,5 +1,6 @@
 import type { ZodOptional, ZodString } from 'zod';
 import type { PromptMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolGroup } from '../groups.js';
 export interface PromptDescriptor {
     name: string;
     title: string;
@@ -7,4 +8,6 @@ export interface PromptDescriptor {
     argsSchema: Record<string, ZodOptional<ZodString>>;
     build: (args: Record<string, string | undefined>) => PromptMessage[];
     readOnly?: true;
+    /** PIT-10114: served when its group is read_write, or at read when `readOnly`. Set in prompts/registry.ts. */
+    group?: ToolGroup;
 }

package/dist/src/mcp/registry.d.ts

@@ -1,2 +1,6 @@
 import type { ToolDescriptor } from './tools/types.js';
+/**
+ * Every CLI-backed tool, each module assigned whole to one tool group (PIT-10114, spec "Group Taxonomy"). `inGroup`
+ * throws when a descriptor names another group or a write tool is classed `read` (checkDescriptor).
+ */
 export declare const allTools: ToolDescriptor[];

package/dist/src/mcp/registry.js

@@ -1,3 +1,4 @@
+import { inGroup } from './groups.js';
 import { analyticsTools } from './tools/analytics.js';
 import { announcementsTools } from './tools/announcements.js';
 import { canvasesTools } from './tools/canvases.js';
@@ -15,34 +16,40 @@ import { metadataTemplateTools } from './tools/metadataTemplate.js';
 import { ldTools } from './tools/ld.js';
 import { orgTools } from './tools/org.js';
 import { publishAppTools } from './tools/publishApp.js';
+import { roleplayTools } from './tools/roleplay.js';
 import { rolesTools } from './tools/roles.js';
 import { searchTools } from './tools/search.js';
 import { sharedLinksTools } from './tools/sharedLinks.js';
 import { tagsTools } from './tools/tags.js';
 import { themesTools } from './tools/themes.js';
 import { usersTools } from './tools/users.js';
+/**
+ * Every CLI-backed tool, each module assigned whole to one tool group (PIT-10114, spec "Group Taxonomy"). `inGroup`
+ * throws when a descriptor names another group or a write tool is classed `read` (checkDescriptor).
+ */
 export const allTools = [
-    ...canvasesTools,
-    ...filesTools,
-    ...foldersTools,
-    ...searchTools,
-    ...instancesTools,
-    ...sharedLinksTools,
-    ...tagsTools,
-    ...announcementsTools,
-    ...dsrLandingTools,
-    ...dsrTools,
-    ...emailTemplateTools,
-    ...themesTools,
-    ...usersTools,
-    ...invitationsTools,
-    ...rolesTools,
-    ...orgTools,
-    ...analyticsTools,
-    ...membershipsTools,
-    ...groupsTools,
-    ...metadataTemplateTools,
-    ...ldTools,
-    ...devSyncTools,
-    ...publishAppTools,
+    ...inGroup('content', canvasesTools),
+    ...inGroup('content', filesTools),
+    ...inGroup('content', foldersTools),
+    ...inGroup('search', searchTools),
+    ...inGroup('search', instancesTools),
+    ...inGroup('sharing', sharedLinksTools),
+    ...inGroup('content', tagsTools),
+    ...inGroup('content', announcementsTools),
+    ...inGroup('sharing', dsrLandingTools),
+    ...inGroup('sharing', dsrTools),
+    ...inGroup('sharing', emailTemplateTools),
+    ...inGroup('content', themesTools),
+    ...inGroup('admin', usersTools),
+    ...inGroup('admin', invitationsTools),
+    ...inGroup('admin', rolesTools),
+    ...inGroup('search', orgTools),
+    ...inGroup('analytics', analyticsTools),
+    ...inGroup('roleplay', roleplayTools),
+    ...inGroup('admin', membershipsTools),
+    ...inGroup('admin', groupsTools),
+    ...inGroup('content', metadataTemplateTools),
+    ...inGroup('ld', ldTools),
+    ...inGroup('developer', devSyncTools),
+    ...inGroup('developer', publishAppTools),
 ];

package/dist/src/mcp/renderPolicy.d.ts

@@ -1 +1,2 @@
-export declare const ANALYTICS_RENDER_POLICY = "When answering Pitcher content-analytics questions (the pitcher_analytics_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.\n\nRendering tiers (evaluate top-down, stop at the first match):\n- A single fact / yes-no / \"who/what/how many is the single X\" (e.g. \"which canvas did I view?\", \"how many viewers?\") -> 1-2 sentences with the number inline. No table, no chart.\n- A ranking request (\"top\", \"most\", \"best\", \"rank\", or \"list the highest/lowest ...\") about content, files, users, or canvases -> a markdown TABLE of the ranked rows (default the top 5-8); columns = only the metric(s) asked for. Treat \"what's my top content?\" as a ranking (a table), NOT a single-item sentence. Lead with a one-line takeaway, then the table.\n- \"over time\" / \"trend\" / \"by week/month\" -> ONE line/area chart artifact (this rule wins over the generic comparison rule below for time series).\n- An explicit visualization request (\"show a chart\", \"chart\", \"visualize\", \"graph\", \"plot\") OR a comparison across a non-time dimension -> ONE focused chart as a single self-contained HTML artifact, only the asked-for series.\n- A broad overview (\"how's everything / my content / adoption doing\", \"give me the picture\", \"dashboard\", QBR) -> a multi-panel dashboard artifact. This is the ceiling \u2014 use it rarely, only for genuinely broad asks.\n\nGuardrails (every tier):\n1. Words first \u2014 even with a chart, lead with a one-sentence answer to the literal question.\n2. Mask names, emails, and user IDs by default (User A/B/...). Reveal an identity only when the analytics tool actually returned it for the authenticated role (the verbs are role-gated); never infer authorization from the user's wording.\n3. If data is empty or trivially small, say so in prose \u2014 do not render an empty chart.\n4. If results are capped/truncated, state the cap (\"top 15 of 118\").\n5. Never show a \"vs prior period\" delta unless the data actually contains prior-period numbers.\n6. Cite the source verb (\"via analytics popularity\").\n\nDo not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.";
+export declare const ANALYTICS_RENDER_POLICY = "When answering Pitcher content-analytics or AI Roleplay questions (the pitcher_analytics_* and pitcher_roleplay_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.\n\nRendering tiers (evaluate top-down, stop at the first match):\n- A single fact / yes-no / \"who/what/how many is the single X\" (e.g. \"which canvas did I view?\", \"how many viewers?\") -> 1-2 sentences with the number inline. No table, no chart.\n- A ranking request (\"top\", \"most\", \"best\", \"rank\", or \"list the highest/lowest ...\") about content, files, users, or canvases -> a markdown TABLE of the ranked rows (default the top 5-8); columns = only the metric(s) asked for. Treat \"what's my top content?\" as a ranking (a table), NOT a single-item sentence. Lead with a one-line takeaway, then the table.\n- \"over time\" / \"trend\" / \"by week/month\" -> ONE line/area chart artifact (this rule wins over the generic comparison rule below for time series).\n- An explicit visualization request (\"show a chart\", \"chart\", \"visualize\", \"graph\", \"plot\") OR a comparison across a non-time dimension -> ONE focused chart as a single self-contained HTML artifact, only the asked-for series.\n- A broad overview (\"how's everything / my content / adoption doing\", \"give me the picture\", \"dashboard\", QBR) -> a multi-panel dashboard artifact. This is the ceiling \u2014 use it rarely, only for genuinely broad asks.\n\nGuardrails (every tier):\n1. Words first \u2014 even with a chart, lead with a one-sentence answer to the literal question.\n2. Mask names, emails, and user IDs by default (User A/B/...). Reveal an identity only when the analytics tool actually returned it for the authenticated role (the verbs are role-gated); never infer authorization from the user's wording.\n3. If data is empty or trivially small, say so in prose \u2014 do not render an empty chart.\n4. If results are capped/truncated, state the cap (\"top 15 of 118\").\n5. Never show a \"vs prior period\" delta unless the data actually contains prior-period numbers.\n6. Cite the source verb (\"via analytics popularity\").\n7. AI Roleplay: a session with no score (null) is unscored, never a 0; never fold it into an average, a pass rate or a ranking.\n\nDo not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.";
+export declare const APPS_RENDER_POLICY = "When your host actually renders a Pitcher tool result in its own interactive view (MCP Apps: a Pitcher view), answer in one sentence and do not redraw the same data as a table, chart or artifact. If your host does not render the view, the text result is all the user gets: list the items for the user.\n\nConfirmed writes (tools ending in _propose): a propose call saves nothing. If your host shows the Pitcher confirm view, the user confirms or cancels there: say one sentence and do nothing else. Never call a _commit tool unless the proposal text tells you how and the user explicitly confirmed in this conversation; never change its arguments; never retry a commit the user cancelled.";

package/dist/src/mcp/renderPolicy.js

@@ -1,9 +1,10 @@
 // Connector-level MCP instructions surfaced to the host model (Claude Desktop, Cursor) via
 // InitializeResult.instructions. Governs how analytics answers are RENDERED so a natural-language
 // question gets a right-sized reply (a sentence, a table, one chart, or — rarely — a dashboard)
-// instead of a rigid full dashboard on every question. This constant is the single source of truth;
-// the Docs Portal spec (Product/Specs/2026-07-24-analytics-answer-rendering-policy.md) mirrors it.
-export const ANALYTICS_RENDER_POLICY = `When answering Pitcher content-analytics questions (the pitcher_analytics_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.
+// instead of a rigid full dashboard on every question. This constant is the only copy of the policy:
+// edit it here. The Docs Portal spec (Product/Specs/2026-07-24-analytics-answer-rendering-policy.md)
+// points here and keeps only the background and decisions.
+export const ANALYTICS_RENDER_POLICY = `When answering Pitcher content-analytics or AI Roleplay questions (the pitcher_analytics_* and pitcher_roleplay_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.
 
 Rendering tiers (evaluate top-down, stop at the first match):
 - A single fact / yes-no / "who/what/how many is the single X" (e.g. "which canvas did I view?", "how many viewers?") -> 1-2 sentences with the number inline. No table, no chart.
@@ -19,5 +20,11 @@ Guardrails (every tier):
 4. If results are capped/truncated, state the cap ("top 15 of 118").
 5. Never show a "vs prior period" delta unless the data actually contains prior-period numbers.
 6. Cite the source verb ("via analytics popularity").
+7. AI Roleplay: a session with no score (null) is unscored, never a 0; never fold it into an average, a pass rate or a ranking.
 
 Do not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.`;
+// MCP Apps (PIT-10066): appended to the server instructions ONLY when at least one view is enabled, so a
+// server without apps keeps exactly ANALYTICS_RENDER_POLICY. The confirmed-writes paragraph is PIT-10113's (spec 8.2).
+export const APPS_RENDER_POLICY = `When your host actually renders a Pitcher tool result in its own interactive view (MCP Apps: a Pitcher view), answer in one sentence and do not redraw the same data as a table, chart or artifact. If your host does not render the view, the text result is all the user gets: list the items for the user.
+
+Confirmed writes (tools ending in _propose): a propose call saves nothing. If your host shows the Pitcher confirm view, the user confirms or cancels there: say one sentence and do nothing else. Never call a _commit tool unless the proposal text tells you how and the user explicitly confirmed in this conversation; never change its arguments; never retry a commit the user cancelled.`;

package/dist/src/mcp/resources/analyticsCatalog.d.ts

@@ -1,3 +1,3 @@
 import type { ResourceDescriptor } from './types.js';
-export declare const ANALYTICS_CATALOG = "# Pitcher analytics catalog\n\nTen read-only verbs, each an MCP tool named `pitcher_analytics_<verb>`. Pick the verb that matches the\nquestion, then call its tool. All are read-only; org scope + auth come from the server's API key (never a\ntool input) \u2014 you only pass `instanceId` (and, where noted, `canvasId`/`userEmail`).\n\n## Key tiers\n- **org-admin key required:** org, popularity, users, files, canvases\n- **instance-admin or org-admin:** instance\n- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions\n\n## Time model\n- **Rollup (no window):** org, instance \u2014 lifetime/current totals.\n- **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, `users` with\n  `stats: true`, files, canvases \u2014 omit dates to get the last 30 days. (`users` without `stats` is a\n  full roster with no window.)\n- **Date-range, server default window:** viewers, sessions \u2014 omit dates and the service picks the window.\n\n## Verbs\n\n| Verb (tool) | Returns | Time | Key | Example question |\n|---|---|---|---|---|\n| `org` | Organization-wide rollup totals (Django) | rollup | org-admin | \"How is the whole org doing overall?\" |\n| `instance` | Single-instance rollup totals (Django) | rollup | instance-admin | \"Totals for this one workspace?\" |\n| `kpi` | KPI metrics for an instance (members, active users, \u2026) | date-range | member | \"How many active users last month?\" |\n| `engagement` | Per-DSR/content engagement rows (capped list + summary) | date-range | member | \"Which content is being engaged with?\" |\n| `popularity` | Most-viewed canvases, ranked (view-analysis) | date-range | org-admin | \"Top 10 most-viewed decks this quarter?\" |\n| `users` | User roster, or active-user stats with `stats: true` | roster: none / stats: date-range | org-admin | \"Who are my active users this month?\" |\n| `files` | File usage analytics (views/opens/engagement per file) | date-range | org-admin | \"Which files get opened the most?\" |\n| `canvases` | Per-section canvas engagement list | date-range | org-admin | \"How are my canvas sections performing?\" |\n| `viewers` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | \"Who viewed this DSR, and how much?\" |\n| `sessions` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | \"What did this viewer do inside the DSR?\" |\n\n## Shaping\nRow-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:\n`summary` + `rows` (default 20, max 100 \u2014 raise with `limit`) + `total_count`/`returned`/`has_more`,\nand a `truncated` note when more rows exist. `kpi` and `sessions` return the raw payload (a KPI scalar set\nand an uncapped event timeline, respectively) \u2014 never truncated.\n\n## DSR drill-down\nFor \"who viewed X and what did they do\": call `viewers` (with `canvasId`) to list viewers, then `sessions`\n(with the same `canvasId` + the viewer's `userEmail`) to see that viewer's event timeline.\nA session is one `Entered` of the queried id itself (a canvas or a section), paired by `event_pair_id`; an\n`Entered` with an empty `event_pair_id` counts as one session on its own.\n`session_count` is counted the same way as the overview's `total_sessions`. `canvases` lists sections, and their\nids are valid `canvasId` inputs for `viewers` and `sessions`.\n\n## Notes\n- `popularity` maps to the canvases view-analysis endpoint (there is no separate popularity route).\n- Results can include user identities/emails \u2014 treat as customer data and handle per policy.\n";
+export declare const ANALYTICS_CATALOG = "# Pitcher analytics catalog\n\nFourteen read-only verbs, each an MCP tool named `pitcher_analytics_<verb>`. Pick the verb that matches the\nquestion, then call its tool. All are read-only; org scope + auth come from the server's API key (never a\ntool input) \u2014 you only pass `instanceId` (and, where noted, `canvasId`/`userEmail`).\n\n## Key tiers\n- **org-admin key required:** org, popularity, users, files, canvases\n- **instance-admin or org-admin:** instance\n- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions, viewer_visits\n- **instance editor, instance admin or org admin:** file_users, file_pages, canvas_users\n\n## Time model\n- **Rollup (no window):** org, instance \u2014 lifetime/current totals.\n- **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, `users` with\n  `stats: true`, files, canvases \u2014 omit dates to get the last 30 days. (`users` without `stats` is a\n  full roster with no window.) Also file_users, file_pages, canvas_users.\n- **Date-range, server default window:** viewers, sessions, viewer_visits \u2014 omit dates and the service picks the window.\n\n## Verbs\n\n| Verb (tool) | Returns | Time | Key | Example question |\n|---|---|---|---|---|\n| `org` | Organization-wide rollup totals (Django) | rollup | org-admin | \"How is the whole org doing overall?\" |\n| `instance` | Single-instance rollup totals (Django) | rollup | instance-admin | \"Totals for this one workspace?\" |\n| `kpi` | KPI metrics for an instance (members, active users, \u2026) | date-range | member | \"How many active users last month?\" |\n| `engagement` | Per-DSR/content engagement rows (capped list + summary) | date-range | member | \"Which content is being engaged with?\" |\n| `popularity` | Most-viewed canvases, ranked (view-analysis) | date-range | org-admin | \"Top 10 most-viewed decks this quarter?\" |\n| `users` | User roster, or active-user stats with `stats: true` | roster: none / stats: date-range | org-admin | \"Who are my active users this month?\" |\n| `files` | File usage analytics (views/opens/engagement per file) | date-range | org-admin | \"Which files get opened the most?\" |\n| `canvases` | Per-section canvas engagement list | date-range | org-admin | \"How are my canvas sections performing?\" |\n| `viewers` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | \"Who viewed this DSR, and how much?\" |\n| `sessions` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | \"What did this viewer do inside the DSR?\" |\n| `file_users` | Who opened ONE file: opens, seconds, days active per user | date-range | editor | \"Who opened the pricing PDF, and for how long?\" |\n| `file_pages` | Time per page of ONE file (one user with a single `userEmails`) | date-range | editor | \"Which pages of this file do reps spend time on?\" |\n| `canvas_users` | Per user and canvas: visits, seconds; with `canvasId`, seconds per page (section) | date-range | editor | \"Which reps presented this deck, and which slides?\" |\n| `viewer_visits` | Per DSR viewer and visit: sections, files and pages with seconds; `format: csv` to export | date-range | member | \"Export who looked at which pages of this DSR\" |\n\n## Shaping\nRow-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:\n`summary` + `rows` (default 20, max 100 \u2014 raise with `limit`) + `total_count`/`returned`/`has_more`,\nand a `truncated` note when more rows exist. `kpi` and `sessions` return the raw payload (a KPI scalar set\nand an uncapped event timeline, respectively) \u2014 never truncated.\n\n## DSR drill-down\nFor \"who viewed X and what did they do\": call `viewers` (with `canvasId`) to list viewers, then `sessions`\n(with the same `canvasId` + the viewer's `userEmail`) to see that viewer's event timeline.\nA session is one `Entered` of the queried id itself (a canvas or a section), paired by `event_pair_id`; an\n`Entered` with an empty `event_pair_id` counts as one session on its own.\n`session_count` is counted the same way as the overview's `total_sessions`. `canvases` lists sections, and their\nids are valid `canvasId` inputs for `viewers` and `sessions`.\n\n`viewer_visits` does both steps for up to 25 viewers at once and returns per-visit, per-page time; use it for\n\"which pages did each viewer look at\", and `format: \"csv\"` when the user wants a file.\n\n## Per-user usage\n\"Which files did this user open\" is `files` with `userEmails`; \"who opened this file\" is `file_users`; time per page\nof a file is `file_pages`; reps' canvas usage is `canvas_users` (internal users only \u2014 external DSR viewers are\n`viewers` / `viewer_visits`).\n\n## AI Roleplay\nRoleplay results are separate tools (`pitcher_roleplay_*`): kpis, sessions and rep_summary for instance or org admins,\nteam (assignment completion; admins see every assignment, coaching managers their own), session_get and\nscenarios_list. A session with no score is unscored, never 0.\n\n## Notes\n- `popularity` maps to the canvases view-analysis endpoint (there is no separate popularity route).\n- Results can include user identities/emails \u2014 treat as customer data and handle per policy.\n";
 export declare const analyticsCatalogResource: ResourceDescriptor;

package/dist/src/mcp/resources/analyticsCatalog.js

@@ -1,25 +1,26 @@
 // A model-facing catalog of the analytics verbs exposed as pitcher_analytics_* tools. It exists so a
 // host can read ONE resource to learn which verb answers which question, the time model each uses, and
-// the key tier each needs — instead of guessing from 10 tool descriptions. Distilled from the analytics
+// the key tier each needs — instead of guessing from 14 tool descriptions. Distilled from the analytics
 // runner contracts in src/commands/analytics.ts (the authoritative source); keep in sync on route/gate
 // changes. Definitions mirror the platform analytics vocabulary.
 export const ANALYTICS_CATALOG = `# Pitcher analytics catalog
 
-Ten read-only verbs, each an MCP tool named \`pitcher_analytics_<verb>\`. Pick the verb that matches the
+Fourteen read-only verbs, each an MCP tool named \`pitcher_analytics_<verb>\`. Pick the verb that matches the
 question, then call its tool. All are read-only; org scope + auth come from the server's API key (never a
 tool input) — you only pass \`instanceId\` (and, where noted, \`canvasId\`/\`userEmail\`).
 
 ## Key tiers
 - **org-admin key required:** org, popularity, users, files, canvases
 - **instance-admin or org-admin:** instance
-- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions
+- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions, viewer_visits
+- **instance editor, instance admin or org admin:** file_users, file_pages, canvas_users
 
 ## Time model
 - **Rollup (no window):** org, instance — lifetime/current totals.
 - **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, \`users\` with
   \`stats: true\`, files, canvases — omit dates to get the last 30 days. (\`users\` without \`stats\` is a
-  full roster with no window.)
-- **Date-range, server default window:** viewers, sessions — omit dates and the service picks the window.
+  full roster with no window.) Also file_users, file_pages, canvas_users.
+- **Date-range, server default window:** viewers, sessions, viewer_visits — omit dates and the service picks the window.
 
 ## Verbs
 
@@ -35,6 +36,10 @@ tool input) — you only pass \`instanceId\` (and, where noted, \`canvasId\`/\`u
 | \`canvases\` | Per-section canvas engagement list | date-range | org-admin | "How are my canvas sections performing?" |
 | \`viewers\` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | "Who viewed this DSR, and how much?" |
 | \`sessions\` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | "What did this viewer do inside the DSR?" |
+| \`file_users\` | Who opened ONE file: opens, seconds, days active per user | date-range | editor | "Who opened the pricing PDF, and for how long?" |
+| \`file_pages\` | Time per page of ONE file (one user with a single \`userEmails\`) | date-range | editor | "Which pages of this file do reps spend time on?" |
+| \`canvas_users\` | Per user and canvas: visits, seconds; with \`canvasId\`, seconds per page (section) | date-range | editor | "Which reps presented this deck, and which slides?" |
+| \`viewer_visits\` | Per DSR viewer and visit: sections, files and pages with seconds; \`format: csv\` to export | date-range | member | "Export who looked at which pages of this DSR" |
 
 ## Shaping
 Row-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:
@@ -50,6 +55,19 @@ A session is one \`Entered\` of the queried id itself (a canvas or a section), p
 \`session_count\` is counted the same way as the overview's \`total_sessions\`. \`canvases\` lists sections, and their
 ids are valid \`canvasId\` inputs for \`viewers\` and \`sessions\`.
 
+\`viewer_visits\` does both steps for up to 25 viewers at once and returns per-visit, per-page time; use it for
+"which pages did each viewer look at", and \`format: "csv"\` when the user wants a file.
+
+## Per-user usage
+"Which files did this user open" is \`files\` with \`userEmails\`; "who opened this file" is \`file_users\`; time per page
+of a file is \`file_pages\`; reps' canvas usage is \`canvas_users\` (internal users only — external DSR viewers are
+\`viewers\` / \`viewer_visits\`).
+
+## AI Roleplay
+Roleplay results are separate tools (\`pitcher_roleplay_*\`): kpis, sessions and rep_summary for instance or org admins,
+team (assignment completion; admins see every assignment, coaching managers their own), session_get and
+scenarios_list. A session with no score is unscored, never 0.
+
 ## Notes
 - \`popularity\` maps to the canvases view-analysis endpoint (there is no separate popularity route).
 - Results can include user identities/emails — treat as customer data and handle per policy.

package/dist/src/mcp/resources/registry.js

@@ -4,6 +4,6 @@ import { analyticsCatalogResource } from './analyticsCatalog.js';
 // Every resource the server can expose. Mirrors mcp/registry.ts (allTools).
 export const allResources = [
     contentDesignResource,
-    ldCanvasDesignResource,
-    analyticsCatalogResource,
+    { ...ldCanvasDesignResource, group: 'ld' },
+    { ...analyticsCatalogResource, group: 'analytics' },
 ];

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

@@ -1,3 +1,4 @@
+import type { ToolGroup } from '../groups.js';
 export interface ResourceDescriptor {
     name: string;
     uri: string;
@@ -5,4 +6,6 @@ export interface ResourceDescriptor {
     description: string;
     mimeType: string;
     read: () => string;
+    /** PIT-10114: hidden when this group is off. Unset = always served (static text no group owns). */
+    group?: ToolGroup;
 }

package/dist/src/mcp/result.d.ts

@@ -10,5 +10,6 @@ export interface CallToolResultShape {
     [key: string]: unknown;
 }
 export declare const MAX_RESULT_BYTES = 900000;
+export declare const MAX_TEXT_BYTES = 8000;
 export declare function toErrorResult(code: string, message: string): CallToolResultShape;
-export declare function envelopeToToolResult(env: Envelope<unknown>, maxBytes?: number): CallToolResultShape;
+export declare function envelopeToToolResult(env: Envelope<unknown>, maxBytes?: number, toText?: (data: unknown) => string, textMaxBytes?: number): CallToolResultShape;

package/dist/src/mcp/result.js

@@ -3,9 +3,9 @@
 export const MAX_RESULT_BYTES = 900000;
 // Cap any single variable-length string (a server error message, a warning) so one huge value
 // can't blow the size budget regardless of which tier it lands in.
-const MAX_TEXT_BYTES = 8000;
-function clampText(s) {
-    return Buffer.byteLength(s, 'utf8') <= MAX_TEXT_BYTES ? s : `${s.slice(0, MAX_TEXT_BYTES)}… (truncated)`;
+export const MAX_TEXT_BYTES = 8000;
+function clampText(s, max = MAX_TEXT_BYTES) {
+    return Buffer.byteLength(s, 'utf8') <= max ? s : `${s.slice(0, max)}… (truncated)`;
 }
 function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -21,7 +21,7 @@ function countItems(data) {
 export function toErrorResult(code, message) {
     return { content: [{ type: 'text', text: clampText(`${code}: ${message}`) }], isError: true };
 }
-export function envelopeToToolResult(env, maxBytes = MAX_RESULT_BYTES) {
+export function envelopeToToolResult(env, maxBytes = MAX_RESULT_BYTES, toText, textMaxBytes = MAX_TEXT_BYTES) {
     if (!env.ok) {
         return toErrorResult(env.error?.code ?? 'UNKNOWN', env.error?.message ?? 'unknown error');
     }
@@ -39,8 +39,10 @@ export function envelopeToToolResult(env, maxBytes = MAX_RESULT_BYTES) {
     // counted — rather than projecting from the raw data size. maxBytes keeps headroom under the
     // host cap for the outer JSON-RPC framing around this result.
     const fits = (candidate) => Buffer.byteLength(JSON.stringify(candidate), 'utf8') <= maxBytes;
-    // Tier 1: full payload with the default dual representation (text + structuredContent).
-    const dual = { content: withWarnings([{ type: 'text', text: full }]), isError: false };
+    // Tier 1: full payload with the default dual representation (text + structuredContent). An MCP Apps tool
+    // (`toText`) sends the model a short text instead of the full JSON, so the payload is not sent twice.
+    const text = toText ? clampText(toText(env.data), textMaxBytes) : full;
+    const dual = { content: withWarnings([{ type: 'text', text }]), isError: false };
     if (obj)
         dual.structuredContent = obj;
     if (fits(dual))