@unboundai/tb-ppt-mgagent 0.2.0 → 0.3.0

package/README.md

@@ -49,13 +49,22 @@ Every tool call writes one JSON-lines entry to `TB_PPT_LOG_FILE` (default `logs/
 | `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` |
+| `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` |
-| `success` | `get_tb_powerpoint_result` | file downloaded; includes `filename`, `downloadUrl` |
+| `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` |
 
-All entries include `durationMs` except the initial `started` line. To see what's been run:
+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 (`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

package/build/index.js

@@ -268,15 +268,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 +313,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 +329,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 +352,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 +362,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 +413,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.3.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": {