📦 fix: Surface Code API Artifact Truncation

src/tools/ArtifactTruncation.ts

@@ -0,0 +1,85 @@
+import type { ArtifactTruncation, ArtifactTruncationReason } from '@/types';
+
+const MAX_REPORTED_TRUNCATED_PATHS = 20;
+const ARTIFACT_TRUNCATION_REASONS = new Set<string>([
+  'max_files',
+  'depth',
+  'size',
+  'path',
+  'unreadable',
+]);
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+export function normalizeArtifactTruncation(
+  value: unknown
+): ArtifactTruncation | undefined {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const candidate = value as Partial<ArtifactTruncation>;
+  if (
+    candidate.code !== 'artifact_truncated' ||
+    !isNonNegativeInteger(candidate.skipped_count) ||
+    candidate.skipped_count === 0 ||
+    candidate.reasons == null ||
+    typeof candidate.reasons !== 'object' ||
+    Array.isArray(candidate.reasons) ||
+    !Array.isArray(candidate.skipped) ||
+    candidate.skipped.length > MAX_REPORTED_TRUNCATED_PATHS ||
+    candidate.skipped.length > candidate.skipped_count ||
+    candidate.skipped.some((path) => typeof path !== 'string')
+  ) {
+    return undefined;
+  }
+
+  const reasons: ArtifactTruncation['reasons'] = {};
+  let reasonTotal = 0;
+  for (const [reason, count] of Object.entries(candidate.reasons)) {
+    if (
+      !ARTIFACT_TRUNCATION_REASONS.has(reason) ||
+      !isNonNegativeInteger(count)
+    ) {
+      return undefined;
+    }
+    reasonTotal += count;
+    if (reasonTotal > candidate.skipped_count) {
+      return undefined;
+    }
+    reasons[reason as ArtifactTruncationReason] = count;
+  }
+
+  if (reasonTotal !== candidate.skipped_count) {
+    return undefined;
+  }
+
+  return {
+    code: candidate.code,
+    reasons,
+    skipped: [...candidate.skipped],
+    skipped_count: candidate.skipped_count,
+  };
+}
+
+export function appendArtifactTruncationWarning(
+  output: string,
+  truncation: ArtifactTruncation | undefined
+): string {
+  if (truncation == null) {
+    return output;
+  }
+
+  const reasons = Object.entries(truncation.reasons)
+    .map(([reason, count]) => `${reason}: ${count}`)
+    .join(', ');
+  const shown = truncation.skipped.length;
+  const paths =
+    shown > 0
+      ? ` Not delivered: ${truncation.skipped.join(', ')}${shown < truncation.skipped_count ? ` (${shown} of ${truncation.skipped_count} shown)` : ''}.`
+      : '';
+  const warning = `Note: ${truncation.skipped_count} file(s) were omitted from delivery${reasons ? ` (${reasons})` : ''}.${paths} Write fewer files per execution or combine them into an archive. The code itself ran; do not rerun automatically because it may have had side effects.`;
+  return `${output.trimEnd()}\n${warning}\n`;
+}

src/tools/BashExecutor.ts

@@ -23,14 +23,18 @@ import {
   appendArtifactDeliveryWarning,
   normalizeArtifactDeliveryFailure,
 } from '@/tools/ArtifactDelivery';
-import { logCodeApiDiagnostic } from '@/tools/diagnostics';
+import {
+  appendArtifactTruncationWarning,
+  normalizeArtifactTruncation,
+} from '@/tools/ArtifactTruncation';
 import { appendExecutionArtifactFileSummary } from '@/tools/CodeSessionFileSummary';
 import { resolveAttachedWorkspaceInstanceId } from '@/tools/workspaceIdentity';
+import { prepareBashProgrammaticCode } from './BashProgrammaticToolCalling';
+import { logCodeApiDiagnostic } from '@/tools/diagnostics';
+import { makeRequest } from './ProgrammaticToolCalling';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
-import { prepareBashProgrammaticCode } from './BashProgrammaticToolCalling';
-import { makeRequest } from './ProgrammaticToolCalling';
 
 config();
 
@@ -407,6 +411,13 @@ function createBashExecutionTool(
           outputWithReminder,
           artifactDelivery
         );
+        const artifactTruncation = normalizeArtifactTruncation(
+          result.artifact_truncation
+        );
+        const outputWithWarnings = appendArtifactTruncationWarning(
+          outputWithDeliveryWarning,
+          artifactTruncation
+        );
         const hasFiles = result.files != null && result.files.length > 0;
         const deletionEcho =
           result.deleted_files != null
@@ -422,11 +433,11 @@ function createBashExecutionTool(
         return [
           hasWorkspace
             ? appendExecutionArtifactFileSummary(
-              outputWithDeliveryWarning,
+              outputWithWarnings,
               result.files
             )
             : appendCodeSessionFileSummary(
-              outputWithDeliveryWarning,
+              outputWithWarnings,
               result.files
             ),
           (hasFiles
@@ -436,6 +447,9 @@ function createBashExecutionTool(
               ...(artifactDelivery != null
                 ? { artifact_delivery: artifactDelivery }
                 : {}),
+              ...(artifactTruncation != null
+                ? { artifact_truncation: artifactTruncation }
+                : {}),
               ...deletionEcho,
               ...runtimeEcho,
             }
@@ -444,6 +458,9 @@ function createBashExecutionTool(
               ...(artifactDelivery != null
                 ? { artifact_delivery: artifactDelivery }
                 : {}),
+              ...(artifactTruncation != null
+                ? { artifact_truncation: artifactTruncation }
+                : {}),
               ...deletionEcho,
               ...runtimeEcho,
             }) satisfies t.CodeExecutionArtifact,

src/tools/CodeExecutor.ts

@@ -9,6 +9,10 @@ import {
   appendArtifactDeliveryWarning,
   normalizeArtifactDeliveryFailure,
 } from '@/tools/ArtifactDelivery';
+import {
+  appendArtifactTruncationWarning,
+  normalizeArtifactTruncation,
+} from '@/tools/ArtifactTruncation';
 import {
   describeCodeApiError,
   logCodeApiDiagnostic,
@@ -671,6 +675,13 @@ function createCodeExecutionTool(
           outputWithReminder,
           artifactDelivery
         );
+        const artifactTruncation = normalizeArtifactTruncation(
+          result.artifact_truncation
+        );
+        const outputWithWarnings = appendArtifactTruncationWarning(
+          outputWithDeliveryWarning,
+          artifactTruncation
+        );
         const hasFiles = result.files != null && result.files.length > 0;
         const deletionEcho =
           result.deleted_files != null
@@ -687,14 +698,17 @@ function createCodeExecutionTool(
             }
             : {};
         return [
-          appendCodeSessionFileSummary(outputWithDeliveryWarning, result.files),
+          appendCodeSessionFileSummary(outputWithWarnings, result.files),
           (hasFiles
             ? {
               session_id: result.session_id,
               files: result.files,
               ...(artifactDelivery != null
                 ? { artifact_delivery: artifactDelivery }
                 : {}),
+              ...(artifactTruncation != null
+                ? { artifact_truncation: artifactTruncation }
+                : {}),
               ...deletionEcho,
               ...runtimeEcho,
             }
@@ -703,6 +717,9 @@ function createCodeExecutionTool(
               ...(artifactDelivery != null
                 ? { artifact_delivery: artifactDelivery }
                 : {}),
+              ...(artifactTruncation != null
+                ? { artifact_truncation: artifactTruncation }
+                : {}),
               ...deletionEcho,
               ...runtimeEcho,
             }) satisfies t.CodeExecutionArtifact,

src/tools/ProgrammaticToolCalling.ts

@@ -22,7 +22,6 @@ import {
   resolveCodeApiAuthHeaders,
   selectRuntimeSessionHint,
 } from './CodeExecutor';
-import { appendExecutionArtifactFileSummary } from './CodeSessionFileSummary';
 import {
   assertUnambiguousIdentifiers,
   projectProgrammaticToolMap,
@@ -39,10 +38,15 @@ import {
   appendArtifactDeliveryWarning,
   normalizeArtifactDeliveryFailure,
 } from '@/tools/ArtifactDelivery';
+import {
+  appendArtifactTruncationWarning,
+  normalizeArtifactTruncation,
+} from '@/tools/ArtifactTruncation';
 import {
   describeCodeApiError,
   logCodeApiDiagnostic,
 } from '@/tools/diagnostics';
+import { appendExecutionArtifactFileSummary } from './CodeSessionFileSummary';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
@@ -946,11 +950,18 @@ export function formatCompletedResponse(
     outputWithReminder,
     artifactDelivery
   );
+  const artifactTruncation = normalizeArtifactTruncation(
+    response.artifact_truncation
+  );
+  const outputWithWarnings = appendArtifactTruncationWarning(
+    outputWithDeliveryWarning,
+    artifactTruncation
+  );
 
   return [
     filePersistence === 'execution'
-      ? appendExecutionArtifactFileSummary(outputWithDeliveryWarning, response.files)
-      : appendCodeSessionFileSummary(outputWithDeliveryWarning, response.files),
+      ? appendExecutionArtifactFileSummary(outputWithWarnings, response.files)
+      : appendCodeSessionFileSummary(outputWithWarnings, response.files),
     {
       session_id: response.session_id,
       files: response.files,
@@ -960,6 +971,9 @@ export function formatCompletedResponse(
       ...(artifactDelivery != null
         ? { artifact_delivery: artifactDelivery }
         : {}),
+      ...(artifactTruncation != null
+        ? { artifact_truncation: artifactTruncation }
+        : {}),
       ...(response.runtime_session_id != null
         ? {
           runtime_session_id: response.runtime_session_id,

src/tools/__tests__/ArtifactTruncation.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from '@jest/globals';
+import {
+  appendArtifactTruncationWarning,
+  normalizeArtifactTruncation,
+} from '../ArtifactTruncation';
+
+const marker = {
+  code: 'artifact_truncated',
+  reasons: { max_files: 70 },
+  skipped: ['report_070.csv', 'report_068.csv'],
+  skipped_count: 70,
+};
+
+describe('artifact truncation', () => {
+  it('normalizes the Code API marker without echoing unexpected fields', () => {
+    expect(
+      normalizeArtifactTruncation({ ...marker, detail: 'private data' })
+    ).toEqual(marker);
+  });
+
+  it.each([
+    null,
+    [],
+    { ...marker, code: 'not_truncated' },
+    { ...marker, skipped_count: -1 },
+    { ...marker, skipped_count: 0, skipped: [] },
+    { ...marker, skipped_count: 1 },
+    { ...marker, skipped_count: 1.5 },
+    { ...marker, skipped_count: '70' },
+    { ...marker, reasons: null },
+    { ...marker, reasons: {} },
+    { ...marker, reasons: { max_files: 0 } },
+    { ...marker, reasons: { max_files: 69 } },
+    { ...marker, reasons: { max_files: 71 } },
+    { ...marker, reasons: { max_files: 35, size: 36 } },
+    { ...marker, reasons: { max_files: 35, size: 34 } },
+    {
+      ...marker,
+      skipped: ['report.csv'],
+      skipped_count: 1,
+    },
+    {
+      ...marker,
+      reasons: { max_files: Number.MAX_SAFE_INTEGER + 1 },
+      skipped_count: Number.MAX_SAFE_INTEGER + 1,
+    },
+    {
+      ...marker,
+      reasons: { max_files: Number.MAX_SAFE_INTEGER, size: 1 },
+      skipped_count: Number.MAX_SAFE_INTEGER,
+    },
+    { ...marker, skipped_count: NaN },
+    { ...marker, reasons: { max_files: Infinity } },
+    { ...marker, reasons: { max_files: 1, unexpected: 1 } },
+    { ...marker, reasons: { size: -1 } },
+    { ...marker, reasons: { path: 1.2 } },
+    { ...marker, skipped: [null] },
+    {
+      ...marker,
+      skipped: Array.from({ length: 21 }, (_, index) => `report_${index}.csv`),
+    },
+  ])('rejects a malformed or oversized marker: %j', (value) => {
+    expect(normalizeArtifactTruncation(value)).toBeUndefined();
+  });
+
+  it('accepts omission counts that match or exceed the reported paths', () => {
+    const fullyReported = {
+      ...marker,
+      reasons: { max_files: 2 },
+      skipped_count: 2,
+    };
+    expect(normalizeArtifactTruncation(fullyReported)).toEqual(fullyReported);
+    expect(normalizeArtifactTruncation({ ...marker, skipped: [] })).toEqual({
+      ...marker,
+      skipped: [],
+    });
+  });
+
+  it.each([
+    { max_files: 14, depth: 14, size: 14, path: 14, unreadable: 14 },
+    { max_files: 70, size: 0 },
+  ])('accepts consistent reason totals: %j', (reasons) => {
+    const value = { ...marker, reasons };
+    expect(normalizeArtifactTruncation(value)).toEqual(value);
+  });
+
+  it('accepts the largest exactly representable omission count', () => {
+    const value = {
+      ...marker,
+      reasons: { max_files: Number.MAX_SAFE_INTEGER - 1, size: 1 },
+      skipped_count: Number.MAX_SAFE_INTEGER,
+    };
+    expect(normalizeArtifactTruncation(value)).toEqual(value);
+  });
+
+  it('copies metadata without sharing mutable state across responses', () => {
+    const value = {
+      ...marker,
+      reasons: { ...marker.reasons },
+      skipped: [...marker.skipped],
+    };
+    const first = normalizeArtifactTruncation(value);
+    const second = normalizeArtifactTruncation(value);
+    value.reasons.max_files = 1;
+    value.skipped.push('later.csv');
+
+    expect(first).toEqual(marker);
+    expect(second).toEqual(marker);
+    expect(first?.reasons).not.toBe(second?.reasons);
+    expect(first?.skipped).not.toBe(second?.skipped);
+  });
+
+  it('reports omissions and bounds the displayed paths without suggesting a rerun', () => {
+    const truncation = normalizeArtifactTruncation(marker);
+    const output = appendArtifactTruncationWarning(
+      'stdout:\ndone\n',
+      truncation
+    );
+
+    expect(output).toContain('70 file(s) were omitted from delivery');
+    expect(output).toContain('(max_files: 70)');
+    expect(output).toContain('report_070.csv, report_068.csv (2 of 70 shown)');
+    expect(output).toContain('do not rerun automatically');
+    expect(appendArtifactTruncationWarning('done', undefined)).toBe('done');
+  });
+});