From eb312554c173204c08fd406e4b3d9f6a6b5fe951 Mon Sep 17 00:00:00 2001 From: "anthropic-code-agent[bot]" <242468646+Claude@users.noreply.github.com> Date: Wed, 11 Feb 2026 00:44:07 +0000 Subject: [PATCH 1/2] Initial plan From 7de67b94930b4bab2397400fae76a9b3dc66646f Mon Sep 17 00:00:00 2001 From: "anthropic-code-agent[bot]" <242468646+Claude@users.noreply.github.com> Date: Wed, 11 Feb 2026 00:47:31 +0000 Subject: [PATCH 2/2] Improve large payload instructions for agents - Updated agentInstructions to explicitly state that payload.json contains the complete original response data in valid JSON format - Clarified that payloadSchema shows structure/types but NOT actual values - Added explicit guidance on how to read and parse the JSON file - Updated AGENTS.md with new section explaining payload.json file structure - Updated .github/agentics/large-payload-tester.md with detailed response format explanation - Updated internal/middleware/README.md with code examples for reading payload files Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com> --- .github/agentics/large-payload-tester.md | 11 +++++++++++ AGENTS.md | 8 ++++++++ internal/middleware/README.md | 23 ++++++++++++++++++++++- internal/middleware/jqschema.go | 2 +- 4 files changed, 42 insertions(+), 2 deletions(-) diff --git a/.github/agentics/large-payload-tester.md b/.github/agentics/large-payload-tester.md index 36e9b497..dc7031b1 100644 --- a/.github/agentics/large-payload-tester.md +++ b/.github/agentics/large-payload-tester.md @@ -11,6 +11,17 @@ Use the filesystem MCP server to access a file called `large-test-file.json`, wh If a payload is too large to return over MCP, the server will return a path in the local filesystem to the payload file instead. Use the path in the local filesystem to access the full payload and extract the secret. +## Understanding the Response Format + +When a payload is too large, the MCP server returns a JSON object with these fields: +- `agentInstructions`: Explains what happened and how to access the full data +- `payloadPath`: Absolute file path to the complete response data (a JSON file) +- `payloadPreview`: First 500 characters of the response for quick reference +- `payloadSchema`: Shows the structure and types of fields (e.g., "string", "number") but NOT the actual values +- `originalSize`: Size of the full response in bytes + +**Important:** The `payload.json` file at `payloadPath` contains the complete original response data in valid JSON format. You can read and parse this file directly to access all values. + ## Important Notes - **Keep all outputs concise** - Use brief, factual statements diff --git a/AGENTS.md b/AGENTS.md index ecbc19e8..a5f1b9f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -390,6 +390,14 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml - This allows agents to mount their session-specific subdirectory to access full payloads - The jq middleware returns: preview (first 500 chars), schema, payloadPath, queryID, originalSize, truncated flag +**Understanding the payload.json File:** +- The `payload.json` file contains the **complete original response data** in valid JSON format +- You can read and parse this file directly using standard JSON parsing tools (e.g., `cat payload.json | jq .` or `JSON.parse(fs.readFileSync(path))`) +- The `payloadSchema` in the metadata response shows the **structure and types** of fields (e.g., "string", "number", "boolean", "array", "object") +- The `payloadSchema` does NOT contain the actual data values - those are only in the `payload.json` file +- The `payloadPreview` shows the first 500 characters of the JSON for quick reference +- To access the full data with all actual values, read the JSON file at `payloadPath` + ## Error Debugging **Enhanced Error Context**: Command failures include: diff --git a/internal/middleware/README.md b/internal/middleware/README.md index e1b2a8e7..2bb00cf1 100644 --- a/internal/middleware/README.md +++ b/internal/middleware/README.md @@ -51,7 +51,7 @@ The middleware is automatically applied to all backend MCP server tools (except **Transformed response:** ```json { - "agentInstructions": "The payload was too large for an MCP response. The payloadSchema approximates the structure of the full payload. The full response can be accessed through the local file system at the payloadPath.", + "agentInstructions": "The payload was too large for an MCP response. The complete original response data is saved as a JSON file at payloadPath. The file contains valid JSON that can be parsed directly. The payloadSchema shows the structure and types of fields in the full response, but not the actual values. To access the full data with all values, read and parse the JSON file at payloadPath.", "payloadPath": "/tmp/gh-awmg/tools-calls/a1b2c3d4e5f6.../payload.json", "payloadPreview": "{\"total_count\":1000,\"items\":[{\"login\":\"user1\",\"id\":123,\"verified\":true}...", "payloadSchema": { @@ -68,6 +68,27 @@ The middleware is automatically applied to all backend MCP server tools (except } ``` +**Understanding the response:** +- `payloadPath`: Points to a JSON file containing the **complete original response data** +- `payloadSchema`: Shows the **structure and types** (e.g., "string", "number", "boolean") but NOT the actual values +- `payloadPreview`: First 500 characters of the JSON for quick reference +- `originalSize`: Size of the full response in bytes + +**Reading the payload.json file:** +The file at `payloadPath` contains the original response data in valid JSON format. You can read it using standard tools: +```bash +# Using cat and jq +cat /tmp/gh-awmg/tools-calls/a1b2c3d4e5f6.../payload.json | jq . + +# Using Node.js +const data = JSON.parse(fs.readFileSync(payloadPath, 'utf8')); + +# Using Python +import json +with open(payload_path) as f: + data = json.load(f) +``` + ## Implementation Details ### jq Schema Filter diff --git a/internal/middleware/jqschema.go b/internal/middleware/jqschema.go index cf8d4ec9..b5765802 100644 --- a/internal/middleware/jqschema.go +++ b/internal/middleware/jqschema.go @@ -19,7 +19,7 @@ var logMiddleware = logger.New("middleware:jqschema") // PayloadTruncatedInstructions is the message returned to clients when a payload // has been truncated and saved to the filesystem -const PayloadTruncatedInstructions = "The payload was too large for an MCP response. The payloadSchema approximates the structure of the full payload. The full response can be accessed through the local file system at the payloadPath." +const PayloadTruncatedInstructions = "The payload was too large for an MCP response. The complete original response data is saved as a JSON file at payloadPath. The file contains valid JSON that can be parsed directly. The payloadSchema shows the structure and types of fields in the full response, but not the actual values. To access the full data with all values, read and parse the JSON file at payloadPath." // PayloadMetadata represents the metadata response returned when a payload is too large // and has been saved to the filesystem