fix: truncated step summary to stay under GitHub's 1024k limit

- added truncateStepSummary() that checks byte size against GitHub's
  hard limit and cuts at the last section boundary (---) when possible
- uses 1000k budget (not 1024k) to leave headroom for content from
  earlier steps in the same job
- appends a truncation notice pointing users to display_report: false
- handles multi-byte characters correctly via TextEncoder/TextDecoder
- applied to both the formatted report and the raw JSON fallback path
- added 5 tests covering: under-limit passthrough, over-limit truncation,
  section boundary cutting, multi-byte character safety, default limit

fixes #927

Author: sunnypatell

src/entrypoints/format-turns.ts

@@ -412,6 +412,46 @@ export function formatGroupedContent(groupedContent: GroupedContent[]): string {
   return markdown;
 }
 
+// GitHub's hard limit for $GITHUB_STEP_SUMMARY content.
+// Using 1000k instead of 1024k to leave headroom for any existing content
+// that may have been appended by earlier steps in the same job.
+const STEP_SUMMARY_MAX_BYTES = 1000 * 1024;
+
+/**
+ * Truncate markdown to fit within GitHub's step summary size limit (1024k).
+ * Cuts at the last complete section boundary (---) before the limit,
+ * then appends a truncation notice.
+ */
+export function truncateStepSummary(
+  markdown: string,
+  maxBytes: number = STEP_SUMMARY_MAX_BYTES,
+): string {
+  const encoded = new TextEncoder().encode(markdown);
+  if (encoded.byteLength <= maxBytes) {
+    return markdown;
+  }
+
+  const truncationNotice =
+    "\n\n---\n\n" +
+    "> **Note:** This report was truncated to fit within GitHub's step summary size limit (1024k).\n" +
+    "> To disable the report entirely, set `display_report: false` in your workflow.\n";
+
+  const noticeBytes = new TextEncoder().encode(truncationNotice).byteLength;
+  const budget = maxBytes - noticeBytes;
+
+  // Decode back to string at the byte budget boundary
+  const truncated = new TextDecoder().decode(encoded.slice(0, budget));
+
+  // Find the last section separator to cut at a clean boundary
+  const lastSeparator = truncated.lastIndexOf("\n---\n");
+  const cutPoint =
+    lastSeparator > truncated.length * 0.5
+      ? lastSeparator
+      : truncated.length;
+
+  return truncated.substring(0, cutPoint) + truncationNotice;
+}
+
 export function formatTurnsFromData(data: Turn[]): string {
   // Group turns naturally
   const groupedContent = groupTurnsNaturally(data);

src/entrypoints/run.ts

@@ -23,7 +23,7 @@ import { prepareAgentMode } from "../modes/agent";
 import { checkContainsTrigger } from "../github/validation/trigger";
 import { collectActionInputsPresence } from "./collect-inputs";
 import { updateCommentLink } from "./update-comment-link";
-import { formatTurnsFromData } from "./format-turns";
+import { formatTurnsFromData, truncateStepSummary } from "./format-turns";
 import type { Turn } from "./format-turns";
 // Base-action imports (used directly instead of subprocess)
 import { validateEnvironmentVariables } from "../../base-action/src/validate-env";
@@ -103,7 +103,7 @@ async function writeStepSummary(executionFile: string): Promise<void> {
   try {
     const fileContent = readFileSync(executionFile, "utf-8");
     const data: Turn[] = JSON.parse(fileContent);
-    const markdown = formatTurnsFromData(data);
+    const markdown = truncateStepSummary(formatTurnsFromData(data));
     await appendFile(summaryFile, markdown);
     console.log("Successfully formatted Claude Code report");
   } catch (error) {
@@ -116,7 +116,7 @@ async function writeStepSummary(executionFile: string): Promise<void> {
       fallback += "```json\n";
       fallback += readFileSync(executionFile, "utf-8");
       fallback += "\n```\n";
-      await appendFile(summaryFile, fallback);
+      await appendFile(summaryFile, truncateStepSummary(fallback));
     } catch {
       console.error("Failed to write raw output to step summary");
     }

test/format-turns.test.ts

@@ -8,6 +8,7 @@ import {
   detectContentType,
   formatResultContent,
   formatToolWithResult,
+  truncateStepSummary,
   type Turn,
   type ToolUse,
   type ToolResult,
@@ -417,6 +418,57 @@ describe("formatTurnsFromData", () => {
   });
 });
 
+describe("truncateStepSummary", () => {
+  test("returns markdown unchanged when under the limit", () => {
+    const small = "## Report\n\nSome content\n";
+    expect(truncateStepSummary(small, 1024)).toBe(small);
+  });
+
+  test("truncates markdown that exceeds the byte limit", () => {
+    const large = "x".repeat(2000);
+    const result = truncateStepSummary(large, 500);
+    const resultBytes = new TextEncoder().encode(result).byteLength;
+    expect(resultBytes).toBeLessThanOrEqual(500);
+    expect(result).toContain("truncated");
+    expect(result).toContain("display_report");
+  });
+
+  test("cuts at last section separator when possible", () => {
+    // Build content with section separators
+    let content = "## Section 1\n\nContent A\n\n---\n\n";
+    content += "## Section 2\n\nContent B\n\n---\n\n";
+    content += "## Section 3\n\n" + "C".repeat(500);
+
+    // Set limit so it fits section 1+2 but not section 3
+    const section12 = "## Section 1\n\nContent A\n\n---\n\n## Section 2\n\nContent B\n";
+    const limit = new TextEncoder().encode(section12).byteLength + 300;
+
+    const result = truncateStepSummary(content, limit);
+    // Should have cut at the separator after section 2
+    expect(result).toContain("Section 1");
+    expect(result).toContain("Section 2");
+    expect(result).toContain("truncated");
+  });
+
+  test("handles multi-byte characters without corruption", () => {
+    // Unicode content with multi-byte chars
+    const content = "## Report\n\n" + "\u{1F600}".repeat(300) + "\n\n---\n\n" + "end";
+    const result = truncateStepSummary(content, 500);
+    // Should not throw or produce invalid UTF-8
+    expect(result).toContain("Report");
+    expect(result).toContain("truncated");
+    // Verify it's valid UTF-8 by encoding/decoding
+    const roundTrip = new TextDecoder().decode(new TextEncoder().encode(result));
+    expect(roundTrip).toBe(result);
+  });
+
+  test("uses default limit matching GitHub's 1024k constraint", () => {
+    // Just verify the default doesn't throw for small content
+    const small = "## Report\n";
+    expect(truncateStepSummary(small)).toBe(small);
+  });
+});
+
 describe("integration tests", () => {
   test("formats real conversation data correctly", () => {
     // Load the sample JSON data