@unboundai/tb-ppt-mgagent 0.1.1 → 0.3.0

package/README.md

@@ -38,6 +38,39 @@ The one thing still **not** confirmed against a real response is the exact `file
    - `ANTHROPIC_API_BASE` — optional, overrides the SDK's default API base URL.
    - `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.
+
+## 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` |
+| `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 (`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
+```
 
 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:
 

package/build/index.js

@@ -37,6 +37,11 @@
  * - TB_PPT_PUBLIC_URL_BASE: required for retrieval. Base URL the synced
  *   folder is served from (e.g. "https://storage.googleapis.com/bucket/prefix"),
  *   used to build the download link returned to the caller.
+ * - TB_PPT_LOG_FILE: optional. Path to a JSON-lines task log (one call per
+ *   line: tool, status, timing, and relevant ids). Defaults to logs/tasks.log
+ *   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.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -45,7 +50,27 @@ import { z } from "zod";
 import Anthropic from "@anthropic-ai/sdk";
 import fs from "fs";
 import path from "path";
+import { fileURLToPath } from "url";
 const MANAGED_AGENTS_BETA = "managed-agents-2026-04-01";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LOG_FILE = process.env.TB_PPT_LOG_FILE || path.join(__dirname, "..", "logs", "tasks.log");
+/**
+ * Records one line of task history: a JSON object to LOG_FILE, and a short
+ * human-readable echo to stderr (stdout is reserved for MCP's own JSON-RPC
+ * traffic in stdio mode - never write task logs there).
+ */
+function logTask(event) {
+    const record = { timestamp: new Date().toISOString(), ...event };
+    const line = JSON.stringify(record);
+    try {
+        fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
+        fs.appendFileSync(LOG_FILE, line + "\n");
+    }
+    catch (err) {
+        console.error(`Failed to write task log to ${LOG_FILE}: ${err.message}`);
+    }
+    console.error(`[task] ${line}`);
+}
 const API_KEY = process.env.ANTHROPIC_API_KEY;
 const AGENT_ID = process.env.ANTHROPIC_AGENT_ID;
 const ENVIRONMENT_ID = process.env.ANTHROPIC_ENVIRONMENT_ID;
@@ -168,9 +193,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    const startedAt = Date.now();
     try {
         if (name === "generate_tb_powerpoint") {
             const { outline, deckType, clientName, filename } = GenerateTbPowerpointSchema.parse(args);
+            logTask({
+                tool: name,
+                status: "started",
+                outlinePreview: outline.slice(0, 120),
+                outlineLength: outline.length,
+                deckType: deckType ?? null,
+                clientName: clientName ?? null,
+                filename: filename ?? null
+            });
             const { apiKey, agentId, environmentId } = requireSessionConfig();
             const client = getClient(apiKey);
             const session = await client.beta.sessions.create({
@@ -191,6 +226,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     { type: "user.message", content: [{ type: "text", text: messageText }] }
                 ]
             });
+            logTask({
+                tool: name,
+                status: "success",
+                sessionId: session.id,
+                durationMs: Date.now() - startedAt
+            });
             return {
                 content: [{
                         type: "text",
@@ -204,10 +245,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         if (name === "get_tb_powerpoint_result") {
             const { sessionId } = GetTbPowerpointResultSchema.parse(args);
+            logTask({ tool: name, status: "started", sessionId });
             const apiKey = requireApiKey();
             const client = getClient(apiKey);
             const session = await client.beta.sessions.retrieve(sessionId);
             if (session.status !== "idle") {
+                logTask({
+                    tool: name,
+                    status: "not_ready",
+                    sessionId,
+                    sessionStatus: session.status,
+                    durationMs: Date.now() - startedAt
+                });
                 return {
                     content: [{
                             type: "text",
@@ -219,17 +268,44 @@ 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({
+                    tool: name,
+                    status: "not_end_turn",
+                    sessionId,
+                    stopReason: stopReasonType ?? null,
+                    durationMs: Date.now() - startedAt
+                });
                 return {
                     content: [{
                             type: "text",
@@ -237,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]
@@ -251,7 +329,22 @@ 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,
+                    status: "no_output_file",
+                    sessionId,
+                    fileCount: fileList.length,
+                    durationMs: Date.now() - startedAt
+                });
                 return {
                     content: [{
                             type: "text",
@@ -259,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)
@@ -268,15 +362,50 @@ 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
+            });
             return {
                 content: [{
                         type: "text",
@@ -284,6 +413,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             ready: true,
                             status: "idle",
                             stopReason: "end_turn",
+                            agentMessage: agentMessagePreview,
                             filename: safeName,
                             savedTo: destPath,
                             downloadUrl
@@ -294,17 +424,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw new Error(`Unknown tool: ${name}`);
     }
     catch (error) {
+        const durationMs = Date.now() - startedAt;
         if (error instanceof z.ZodError) {
+            const details = error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+            logTask({ tool: name, status: "invalid_arguments", details, durationMs });
             return {
                 content: [{
                         type: "text",
                         text: JSON.stringify({
                             error: "Invalid arguments",
-                            details: error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ")
+                            details
                         }, null, 2)
                     }]
             };
         }
+        logTask({ tool: name, status: "error", message: error.message, durationMs });
         return {
             content: [{
                     type: "text",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundai/tb-ppt-mgagent",
-  "version": "0.1.1",
+  "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": {