@unboundai/tb-ppt-mgagent 0.2.0 → 0.4.0

package/README.md

@@ -1,12 +1,14 @@
 # Traffic Builders PowerPoint MCP Server
 
-A Model Context Protocol (MCP) server that hands a presentation outline to Anthropic's hosted **Managed Agent** for building Traffic Builders-branded PowerPoints, then retrieves the finished file once it's done. Brand assets (logos, Outfit font) and the design brief are already provisioned in that agent's environment — this server does not upload anything, it just starts the run and later collects the result.
+A Model Context Protocol (MCP) server that hands a presentation outline to Anthropic's hosted **Managed Agent** for building Traffic Builders-branded PowerPoints, then retrieves the finished file once it's done.
+
+Brand assets (the design brief, logos, Outfit font) are **not** assumed to already exist in the agent's environment. A Managed Agents "deployment" (scheduled/cron runs) was investigated as a way to pin a session to a specific pre-configured setup, but it only re-sends a fixed baked-in message on a schedule — it offers no extra asset-targeting capability over a plain session. So instead, this server uploads each brand asset once via the Files API (a one-time step, see [Setup](#setup)) and attaches them explicitly to **every** session it creates via the `resources` array, mounted into the sandbox for the agent to read.
 
 Built against the official Managed Agents docs (session creation, session operations, events & streaming, files, event/type reference) using the official `@anthropic-ai/sdk` client, which sets the `managed-agents-2026-04-01` beta header automatically for session endpoints.
 
 ## Available tools
 
-- **`generate_tb_powerpoint(outline, deckType?, clientName?, filename?)`** — creates a session against the configured agent + environment, sends the outline as the first message, returns `{ success, sessionId, message }`. Does not wait for the deck to finish.
+- **`generate_tb_powerpoint(outline, deckType?, clientName?, filename?)`** — creates a session against the configured agent + environment, attaches whichever brand asset `resources` are configured (see Setup), sends the outline as the first message, returns `{ success, sessionId, message }`. Does not wait for the deck to finish.
 
 - **`get_tb_powerpoint_result(sessionId)`** — checks on a generation started above:
   1. Retrieves the session. If its `status` isn't `idle`, returns `{ ready: false, status }` — still running, try again later.
@@ -15,7 +17,7 @@ Built against the official Managed Agents docs (session creation, session operat
 
 ## What's still an assumption
 
-Every SDK call in `src/index.ts` (`sessions.create`, `sessions.events.send`, `sessions.retrieve`, `sessions.events.list`, `files.list`, `files.download`) is checked against `@anthropic-ai/sdk`'s own `.d.ts`/source (installed version, not just the docs prose) — that's how a real bug was caught in 0.1.0: the docs' TypeScript sample for downloading a file shows `content.writeToFile(path)`, but that method doesn't exist on the installed SDK. `files.download()` actually resolves to a plain `Response`; 0.1.1 fixes this by reading it with `.arrayBuffer()` and writing the bytes directly.
+Every SDK call in `src/index.ts` (`sessions.create`, `sessions.events.send`, `sessions.retrieve`, `sessions.events.list`, `files.list`, `files.download`) is checked against `@anthropic-ai/sdk`'s own `.d.ts`/source (installed version, not just the docs prose) — that's how a real bug was caught in 0.1.0: the docs' TypeScript sample for downloading a file shows `content.writeToFile(path)`, but that method doesn't exist on the installed SDK. `files.download()` actually resolves to a plain `Response`; 0.1.1 fixes this by reading it with `.arrayBuffer()` and writing the bytes directly. The `resources` shape (`{ type: "file", file_id, mount_path }`) is likewise checked against the SDK source, not just the docs.
 
 The one thing still **not** confirmed against a real response is the exact `filename`/path convention the Files API returns for a file the agent wrote to its outputs directory — the code guesses by matching `/outputs?[\/]/i` against the filename and falling back to any `.pptx` file on the session if nothing matches that pattern. If a real run's file list looks different, adjust the filter in `get_tb_powerpoint_result` in `src/index.ts`.
 
@@ -31,7 +33,13 @@ The one thing still **not** confirmed against a real response is the exact `file
    npm run build
    ```
 
-3. **Configure environment variables**:
+3. **Upload the brand assets** (one time, or again whenever an asset changes):
+   ```
+   .\uploadAssets.ps1 -ApiKey "sk-ant-..."
+   ```
+   Uploads `TrafficBuilders-PPT-Handoff.md`, all five `logos/*.png`, and `fonts/Outfit-VariableFont_wght.ttf` to the Files API, and prints a `file_id` per asset along with the matching env var name. These are just config, not code — plug them into step 5 below and there's nothing else to change or republish.
+
+4. **Configure environment variables**:
    - `ANTHROPIC_API_KEY` — Anthropic API key with Managed Agents access.
    - `ANTHROPIC_AGENT_ID` — e.g. `agent_01H8osDSMeEtGcEHT1ajzuin`.
    - `ANTHROPIC_ENVIRONMENT_ID` — e.g. `env_01VHzZmqBababsghFjQoAGFx`.
@@ -39,31 +47,9 @@ The one thing still **not** confirmed against a real response is the exact `file
    - `TB_PPT_OUTPUT_DIR` — required for `get_tb_powerpoint_result`. Local folder that's synced to GCS by something outside this server; finished `.pptx` files are written here.
    - `TB_PPT_PUBLIC_URL_BASE` — required for `get_tb_powerpoint_result`. Base URL the synced folder is served from (e.g. `https://storage.googleapis.com/bucket/prefix`), used to build the returned download link.
    - `TB_PPT_LOG_FILE` — optional. Path to the task log file. Defaults to `logs/tasks.log` next to this package.
+   - `TB_DESIGN_BRIEF_FILE_ID`, `TB_LOGO_HORIZONTAL_FILE_ID`, `TB_LOGO_HORIZONTAL_WHITE_FILE_ID`, `TB_LOGO_ICON_FILE_ID`, `TB_LOGO_ICON_WHITE_FILE_ID`, `TB_LOGO_ICON_TAGLINE_FILE_ID`, `TB_FONT_FILE_ID` — all optional but strongly recommended, from step 3. Any left unset are just skipped (with a warning in the log) rather than failing the call — the deck still gets built, just without that asset available to the agent.
 
-## Task logging
-
-Every tool call writes one JSON-lines entry to `TB_PPT_LOG_FILE` (default `logs/tasks.log`) and mirrors it to stderr (which the MCP host's own log viewer already shows, as seen in the `[powerpoint-creator]` logs). Each line has a `timestamp`, `tool`, and `status`, plus whatever's relevant to that outcome:
-
-| status | tool | meaning |
-|---|---|---|
-| `started` | either | call received, with its key arguments (outline preview/length, or sessionId) |
-| `success` | `generate_tb_powerpoint` | session created; includes `sessionId` |
-| `not_ready` | `get_tb_powerpoint_result` | session isn't `idle` yet; includes `sessionStatus` |
-| `not_end_turn` | `get_tb_powerpoint_result` | idle, but `stop_reason` wasn't `end_turn`; includes `stopReason` |
-| `no_output_file` | `get_tb_powerpoint_result` | finished cleanly but no `.pptx` found; includes `fileCount` |
-| `success` | `get_tb_powerpoint_result` | file downloaded; includes `filename`, `downloadUrl` |
-| `invalid_arguments` | either | zod validation failed; includes `details` |
-| `error` | either | anything else threw; includes `message` |
-
-All entries include `durationMs` except the initial `started` line. To see what's been run:
-
-```bash
-tail -f logs/tasks.log
-# or, for just failures:
-grep -E '"status":"(error|not_end_turn|no_output_file)"' logs/tasks.log
-```
-
-4. **Register with your MCP client** (Claude Desktop / TypingMind's local MCP connector — same pattern as this repo's siblings, e.g. `tb-gcs-assembly-mcp`). Published to npm as [`@unboundai/tb-ppt-mgagent`](https://www.npmjs.com/package/@unboundai/tb-ppt-mgagent), so `npx` can run it without a local checkout:
+5. **Register with your MCP client** (Claude Desktop / TypingMind's local MCP connector — same pattern as this repo's siblings, e.g. `tb-gcs-assembly-mcp`). Published to npm as [`@unboundai/tb-ppt-mgagent`](https://www.npmjs.com/package/@unboundai/tb-ppt-mgagent), so `npx` can run it without a local checkout:
 
    ```json
    "tb-ppt-mgagent": {
@@ -77,7 +63,14 @@ grep -E '"status":"(error|not_end_turn|no_output_file)"' logs/tasks.log
        "ANTHROPIC_AGENT_ID": "agent_...",
        "ANTHROPIC_ENVIRONMENT_ID": "env_...",
        "TB_PPT_OUTPUT_DIR": "/path/to/gcs-synced-folder",
-       "TB_PPT_PUBLIC_URL_BASE": "https://storage.googleapis.com/your-bucket/your-prefix"
+       "TB_PPT_PUBLIC_URL_BASE": "https://storage.googleapis.com/your-bucket/your-prefix",
+       "TB_DESIGN_BRIEF_FILE_ID": "file_...",
+       "TB_LOGO_HORIZONTAL_FILE_ID": "file_...",
+       "TB_LOGO_HORIZONTAL_WHITE_FILE_ID": "file_...",
+       "TB_LOGO_ICON_FILE_ID": "file_...",
+       "TB_LOGO_ICON_WHITE_FILE_ID": "file_...",
+       "TB_LOGO_ICON_TAGLINE_FILE_ID": "file_...",
+       "TB_FONT_FILE_ID": "file_..."
      }
    }
    ```
@@ -94,12 +87,45 @@ grep -E '"status":"(error|not_end_turn|no_output_file)"' logs/tasks.log
    }
    ```
 
-   ### Publishing a new version
+### Publishing a new version
 
-   ```bash
-   npm version patch   # or minor/major
-   npm publish         # prepublishOnly rebuilds automatically; will prompt for a 2FA OTP
-   ```
+```bash
+npm version patch   # or minor/major
+npm publish         # prepublishOnly rebuilds automatically; will prompt for a 2FA OTP
+```
+
+## Task logging
+
+Every tool call writes one JSON-lines entry to `TB_PPT_LOG_FILE` (default `logs/tasks.log`) and mirrors it to stderr (which the MCP host's own log viewer already shows, as seen in the `[powerpoint-creator]` logs). Each line has a `timestamp`, `tool`, and `status`, plus whatever's relevant to that outcome:
+
+| status | tool | meaning |
+|---|---|---|
+| `started` | either | call received, with its key arguments (outline preview/length, or sessionId) |
+| `attaching_assets` | `generate_tb_powerpoint` | which brand asset `resources` are being attached (`attached`, a list of mount paths) and which env vars are unset (`missing`) |
+| `success` | `generate_tb_powerpoint` | session created; includes `sessionId` and `assetsAttached` count |
+| `not_ready` | `get_tb_powerpoint_result` | session isn't `idle` yet; includes `sessionStatus` |
+| `agent_message` | `get_tb_powerpoint_result` | the agent's own most recent `agent.message` text, up to 500 chars, in `agentMessagePreview` — this is what the agent actually said, not our derived status. Logged once the session is idle, before the stop-reason check, so it's there even on `not_end_turn` |
+| `not_end_turn` | `get_tb_powerpoint_result` | idle, but `stop_reason` wasn't `end_turn`; includes `stopReason` |
+| `listing_files` | `get_tb_powerpoint_result` | about to call Files API `list` for this session |
+| `files_listed` | `get_tb_powerpoint_result` | includes `fileCount`, every `.pptx` candidate found (`pptxCandidates`, each with `id`/`filename`/`sizeBytes`), and which one was `chosenFileId` |
+| `no_output_file` | `get_tb_powerpoint_result` | finished cleanly but no `.pptx` found; includes `fileCount` |
+| `download_started` | `get_tb_powerpoint_result` | about to call Files API `download`; includes `fileId`, `filename`, `expectedSizeBytes` |
+| `download_completed` | `get_tb_powerpoint_result` | bytes received; includes `downloadedBytes` |
+| `saving_file` | `get_tb_powerpoint_result` | about to write to `destPath` inside `outputDir` |
+| `file_saved` | `get_tb_powerpoint_result` | write confirmed via `fs.statSync`; includes `savedBytes` and `bytesMatch` (should be `true`) |
+| `success` | `get_tb_powerpoint_result` | fully done; includes `filename`, `destPath`, `downloadUrl` |
+| `invalid_arguments` | either | zod validation failed; includes `details` |
+| `error` | either | anything else threw; includes `message` |
+
+The agent's actual final message is also returned to the caller as `agentMessage` on every `get_tb_powerpoint_result` response (not just logged), so a not-quite-right run can be diagnosed from the tool's own output, not just the log file.
+
+All entries include `durationMs` except the intermediate progress lines (`attaching_assets`, `agent_message`, `listing_files`, `files_listed`, `download_started`, `download_completed`, `saving_file`) — those are pure checkpoints, timed by their surrounding `started`/`success`/`error` lines instead. To see what's been run:
+
+```bash
+tail -f logs/tasks.log
+# or, for just failures:
+grep -E '"status":"(error|not_end_turn|no_output_file)"' logs/tasks.log
+```
 
 ## Development
 
@@ -108,8 +134,8 @@ grep -E '"status":"(error|not_end_turn|no_output_file)"' logs/tasks.log
 npm run dev
 ```
 
-Both tools were smoke-tested end-to-end over the real MCP protocol (`tools/list`, and calling each with a dummy API key to confirm the SDK calls actually reach `api.anthropic.com` and get a real `401 authentication_error` back rather than failing on a wrong method/shape before the network call).
+Both tools were smoke-tested end-to-end over the real MCP protocol (`tools/list`, and calling each with a dummy API key to confirm the SDK calls actually reach `api.anthropic.com` and get a real `401 authentication_error` back rather than failing on a wrong method/shape before the network call) — including with asset env vars set, to confirm the `resources` array builds correctly.
 
 ## Design brief reference
 
-`TrafficBuilders-PPT-Handoff.md`, `logos/`, and `fonts/` in this repo are the source material that was provisioned into the Managed Agent's environment (colors, type scale, the six slide archetypes, brand logo PNGs, Outfit variable font). Kept here as the local record of what the environment should contain — not read or uploaded by this server at runtime.
+`TrafficBuilders-PPT-Handoff.md`, `logos/`, and `fonts/` in this repo are the source material — pulled from the "Traffic Builders Design System" Claude Design project (colors, type scale, the six slide archetypes, brand logo PNGs, Outfit variable font) — that `uploadAssets.ps1` uploads and every session attaches via `resources`. Update the files here first if the design system changes, then re-run `uploadAssets.ps1` and update the env vars with the new file_ids.

package/build/index.js

@@ -3,11 +3,17 @@
  * Traffic Builders PowerPoint MCP Server
  *
  * Hands a presentation outline to Anthropic's hosted Managed Agent that
- * builds Traffic Builders-branded PowerPoints (brand assets and design
- * brief are already provisioned in that agent's environment - this server
- * does not upload any brand files itself), then later retrieves the
+ * builds Traffic Builders-branded PowerPoints, then later retrieves the
  * finished .pptx once the agent's turn has ended.
  *
+ * Brand assets (design brief, logos, font) are NOT assumed to already exist
+ * in the agent's environment - a "deployment" in the Managed Agents API is
+ * only a fixed/scheduled way to re-run the same baked-in message and offers
+ * no extra asset-targeting capability over a plain session, so instead this
+ * server attaches each asset to every session explicitly via the `resources`
+ * array (mounted through the Files API - see uploadAssets.ps1 for the
+ * one-time upload step that produces the file_ids below).
+ *
  * Built against the documented Managed Agents API:
  *   https://platform.claude.com/docs/en/managed-agents/sessions
  *   https://platform.claude.com/docs/en/managed-agents/session-operations
@@ -42,6 +48,15 @@
  *   next to this package. Every entry is also mirrored to stderr, which the
  *   MCP host's own log viewer already picks up - the file exists so history
  *   survives a host restart and can be grepped/tailed directly.
+ * - TB_DESIGN_BRIEF_FILE_ID, TB_LOGO_HORIZONTAL_FILE_ID,
+ *   TB_LOGO_HORIZONTAL_WHITE_FILE_ID, TB_LOGO_ICON_FILE_ID,
+ *   TB_LOGO_ICON_WHITE_FILE_ID, TB_LOGO_ICON_TAGLINE_FILE_ID,
+ *   TB_FONT_FILE_ID: all optional but strongly recommended. Files API
+ *   file_ids (from uploadAssets.ps1) for the design brief, each logo
+ *   variant, and the Outfit font. Any that are set get mounted into every
+ *   session via `resources`; any left unset are just skipped (with a
+ *   warning), so the agent falls back to approximating the brand from the
+ *   prompt text alone.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -87,6 +102,26 @@ if (!OUTPUT_DIR)
     console.error("Warning: TB_PPT_OUTPUT_DIR environment variable is not set (needed for get_tb_powerpoint_result)");
 if (!PUBLIC_URL_BASE)
     console.error("Warning: TB_PPT_PUBLIC_URL_BASE environment variable is not set (needed for get_tb_powerpoint_result)");
+/**
+ * Brand assets mounted into every session via `resources`. `mountPath` is
+ * relative to the session's uploads root - see file header - so the actual
+ * sandbox path is `/mnt/session/uploads${mountPath}`. Any entry whose env
+ * var isn't set is skipped (not an error): the deck still gets built, just
+ * without that asset available to the agent.
+ */
+const ASSET_RESOURCES = [
+    { envVar: "TB_DESIGN_BRIEF_FILE_ID", mountPath: "/design/TrafficBuilders-PPT-Handoff.md", label: "design brief" },
+    { envVar: "TB_LOGO_HORIZONTAL_FILE_ID", mountPath: "/design/logos/logo-horizontal.png", label: "logo-horizontal.png (full-color, light backgrounds)" },
+    { envVar: "TB_LOGO_HORIZONTAL_WHITE_FILE_ID", mountPath: "/design/logos/logo-horizontal-white.png", label: "logo-horizontal-white.png (reversed, brand-blue backgrounds)" },
+    { envVar: "TB_LOGO_ICON_FILE_ID", mountPath: "/design/logos/logo-icon.png", label: "logo-icon.png (full-color square mark)" },
+    { envVar: "TB_LOGO_ICON_WHITE_FILE_ID", mountPath: "/design/logos/logo-icon-white.png", label: "logo-icon-white.png (reversed square mark)" },
+    { envVar: "TB_LOGO_ICON_TAGLINE_FILE_ID", mountPath: "/design/logos/logo-icon-tagline.png", label: "logo-icon-tagline.png (icon + tagline lockup)" },
+    { envVar: "TB_FONT_FILE_ID", mountPath: "/design/fonts/Outfit-VariableFont_wght.ttf", label: "Outfit variable font (weights 300-900)" }
+];
+const missingAssetEnvVars = ASSET_RESOURCES.filter((a) => !(process.env[a.envVar] || "").trim());
+if (missingAssetEnvVars.length > 0) {
+    console.error(`Warning: brand asset file_ids not configured, decks will be built without them: ${missingAssetEnvVars.map((a) => a.envVar).join(", ")}`);
+}
 function requireSessionConfig() {
     if (!API_KEY)
         throw new Error("ANTHROPIC_API_KEY is not configured on this MCP server.");
@@ -208,9 +243,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             });
             const { apiKey, agentId, environmentId } = requireSessionConfig();
             const client = getClient(apiKey);
+            const attachedAssets = ASSET_RESOURCES
+                .map((a) => ({ ...a, fileId: (process.env[a.envVar] || "").trim() }))
+                .filter((a) => a.fileId);
+            logTask({
+                tool: name,
+                status: "attaching_assets",
+                attached: attachedAssets.map((a) => a.mountPath),
+                missing: missingAssetEnvVars.map((a) => a.envVar)
+            });
             const session = await client.beta.sessions.create({
                 agent: agentId,
-                environment_id: environmentId
+                environment_id: environmentId,
+                ...(attachedAssets.length > 0
+                    ? {
+                        resources: attachedAssets.map((a) => ({
+                            type: "file",
+                            file_id: a.fileId,
+                            mount_path: a.mountPath
+                        }))
+                    }
+                    : {})
             });
             const lines = [];
             if (deckType)
@@ -220,7 +273,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (filename)
                 lines.push(`Save the resulting file as "${filename}.pptx".`);
             const meta = lines.length ? `${lines.join("\n")}\n\n` : "";
-            const messageText = `Build a Traffic Builders PowerPoint from the following outline.\n\n${meta}## Outline\n${outline}`;
+            const assetsNote = attachedAssets.length > 0
+                ? `## Attached brand assets\nThese files are mounted in your sandbox:\n${attachedAssets
+                    .map((a) => `- /mnt/session/uploads${a.mountPath} - ${a.label}`)
+                    .join("\n")}\n\nRead the design brief first and follow it exactly: brand colors, type scale, and the six slide archetypes it defines. Place the correct logo variant per slide background (full-color logo on white/light backgrounds, the reversed white logo on brand-blue backgrounds). Embed/register the attached font file and use it for all text - ExtraBold (800) for headings, Regular (400) for body - instead of a fallback typeface.\n\n---\n\n`
+                : "";
+            const messageText = `Build a Traffic Builders PowerPoint from the following outline.\n\n${assetsNote}${meta}## Outline\n${outline}`;
             await client.beta.sessions.events.send(session.id, {
                 events: [
                     { type: "user.message", content: [{ type: "text", text: messageText }] }
@@ -230,6 +288,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 tool: name,
                 status: "success",
                 sessionId: session.id,
+                assetsAttached: attachedAssets.length,
                 durationMs: Date.now() - startedAt
             });
             return {
@@ -268,15 +327,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         }]
                 };
             }
-            // Find the most recent session.status_idle event to read its stop_reason.
+            // Find the most recent session.status_idle event to read its stop_reason, and
+            // the most recent agent.message event so we can log/return what the agent
+            // actually said (not just our own derived status).
             let latestIdleEvent = null;
+            let latestAgentMessage = null;
             for await (const event of client.beta.sessions.events.list(sessionId)) {
                 if (event.type === "session.status_idle") {
                     if (!latestIdleEvent || event.processed_at > latestIdleEvent.processed_at) {
                         latestIdleEvent = event;
                     }
                 }
+                else if (event.type === "agent.message") {
+                    const text = event.content
+                        .filter((block) => block.type === "text")
+                        .map((block) => block.text)
+                        .join("\n")
+                        .trim();
+                    if (text && (!latestAgentMessage || event.processed_at > latestAgentMessage.processed_at)) {
+                        latestAgentMessage = { processed_at: event.processed_at, text };
+                    }
+                }
             }
+            const agentMessagePreview = latestAgentMessage ? latestAgentMessage.text.slice(0, 500) : null;
+            logTask({
+                tool: name,
+                status: "agent_message",
+                sessionId,
+                agentMessagePreview
+            });
             const stopReasonType = latestIdleEvent?.stop_reason.type;
             if (stopReasonType !== "end_turn") {
                 logTask({
@@ -293,12 +372,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 ready: false,
                                 status: session.status,
                                 stopReason: stopReasonType ?? null,
+                                agentMessage: agentMessagePreview,
                                 message: `Session is idle but its stop reason is "${stopReasonType ?? "unknown"}", not "end_turn" - not fetching files yet.`
                             }, null, 2)
                         }]
                 };
             }
             // Session finished cleanly - look for a .pptx output file.
+            logTask({ tool: name, status: "listing_files", sessionId });
             const files = await client.beta.files.list({
                 scope_id: sessionId,
                 betas: [MANAGED_AGENTS_BETA]
@@ -307,6 +388,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const pptxFiles = fileList.filter((f) => /\.pptx$/i.test(f.filename));
             const outputPptxFiles = pptxFiles.filter((f) => /outputs?[\\/]/i.test(f.filename));
             const chosen = outputPptxFiles[0] ?? pptxFiles[0];
+            logTask({
+                tool: name,
+                status: "files_listed",
+                sessionId,
+                fileCount: fileList.length,
+                pptxCandidates: pptxFiles.map((f) => ({ id: f.id, filename: f.filename, sizeBytes: f.size_bytes })),
+                chosenFileId: chosen?.id ?? null
+            });
             if (!chosen) {
                 logTask({
                     tool: name,
@@ -322,6 +411,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 ready: true,
                                 status: "idle",
                                 stopReason: "end_turn",
+                                agentMessage: agentMessagePreview,
                                 message: "Session finished but no .pptx output file was found.",
                                 sessionFiles: fileList.map((f) => ({ id: f.id, filename: f.filename }))
                             }, null, 2)
@@ -331,20 +421,47 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { outputDir, publicUrlBase } = requireOutputConfig();
             const safeName = path.basename(chosen.filename || `${sessionId}.pptx`);
             const destPath = path.join(outputDir, safeName);
+            logTask({
+                tool: name,
+                status: "download_started",
+                sessionId,
+                fileId: chosen.id,
+                filename: safeName,
+                expectedSizeBytes: chosen.size_bytes
+            });
             // files.download() resolves to a plain Response on this SDK version - no
             // writeToFile() helper (see file header). Read the bytes and write them ourselves.
             const response = await client.beta.files.download(chosen.id, {
                 betas: [MANAGED_AGENTS_BETA]
             });
             const arrayBuffer = await response.arrayBuffer();
+            const downloadedBytes = arrayBuffer.byteLength;
+            logTask({
+                tool: name,
+                status: "download_completed",
+                sessionId,
+                fileId: chosen.id,
+                downloadedBytes
+            });
+            logTask({ tool: name, status: "saving_file", sessionId, destPath, outputDir });
             fs.mkdirSync(outputDir, { recursive: true });
             fs.writeFileSync(destPath, Buffer.from(arrayBuffer));
+            const savedBytes = fs.statSync(destPath).size;
+            logTask({
+                tool: name,
+                status: "file_saved",
+                sessionId,
+                destPath,
+                savedBytes,
+                bytesMatch: savedBytes === downloadedBytes
+            });
             const downloadUrl = `${publicUrlBase.replace(/\/$/, "")}/${encodeURIComponent(safeName)}`;
             logTask({
                 tool: name,
                 status: "success",
                 sessionId,
                 filename: safeName,
+                destPath,
                 downloadUrl,
                 durationMs: Date.now() - startedAt
             });
@@ -355,6 +472,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             ready: true,
                             status: "idle",
                             stopReason: "end_turn",
+                            agentMessage: agentMessagePreview,
                             filename: safeName,
                             savedTo: destPath,
                             downloadUrl

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundai/tb-ppt-mgagent",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server that hands a presentation outline to the Traffic Builders PowerPoint Managed Agent, then retrieves the finished .pptx",
   "main": "build/index.js",
   "bin": {