@librechat/agents 3.1.73 → 3.1.75

package/src/messages/cache.test.ts

@@ -1,8 +1,9 @@
 import {
   AIMessage,
   BaseMessage,
-  ToolMessage,
   HumanMessage,
+  SystemMessage,
+  ToolMessage,
   MessageContentComplex,
 } from '@langchain/core/messages';
 import type Anthropic from '@anthropic-ai/sdk';
@@ -404,7 +405,107 @@ describe('addBedrockCacheControl (Bedrock cache checkpoints)', () => {
     expect(first[1]).toEqual({ cachePoint: { type: 'default' } });
   });
 
-  it('works with the example from the langchain pr (with multi-turn behavior)', () => {
+  it('preserves LangChain system message content unchanged', () => {
+    const systemContent = [
+      { type: ContentTypes.TEXT, text: 'Stable system text' },
+      { cachePoint: { type: 'default' } },
+      { type: ContentTypes.TEXT, text: 'Dynamic system text' },
+    ] as MessageContentComplex[];
+    const messages: BaseMessage[] = [
+      new SystemMessage({ content: systemContent }),
+      new HumanMessage('Hello'),
+      new AIMessage('Hi'),
+    ];
+
+    const result = addBedrockCacheControl(messages);
+
+    expect(result[0]).toBe(messages[0]);
+    expect(result[0].content).toEqual(systemContent);
+  });
+
+  it('preserves serialized system message content unchanged', () => {
+    const systemContent = [
+      { type: ContentTypes.TEXT, text: 'Stable system text' },
+      { cachePoint: { type: 'default' } },
+      { type: ContentTypes.TEXT, text: 'Dynamic system text' },
+    ] as MessageContentComplex[];
+    const messages: TestMsg[] = [
+      { role: 'system', content: systemContent },
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi' },
+    ];
+
+    const result = addBedrockCacheControl(messages);
+
+    expect(result[0]).toBe(messages[0]);
+    expect(result[0].content).toEqual(systemContent);
+  });
+
+  it('strips Anthropic cache_control from LangChain system messages without moving cache points', () => {
+    const systemContent = [
+      {
+        type: ContentTypes.TEXT,
+        text: 'Stable system text',
+        cache_control: { type: 'ephemeral' },
+      } as MessageContentComplex,
+      { cachePoint: { type: 'default' } },
+      {
+        type: ContentTypes.TEXT,
+        text: 'Dynamic system text',
+        cache_control: { type: 'ephemeral' },
+      } as MessageContentComplex,
+    ] as MessageContentComplex[];
+    const messages: BaseMessage[] = [
+      new SystemMessage({ content: systemContent }),
+      new HumanMessage('Hello'),
+      new AIMessage('Hi'),
+    ];
+
+    const result = addBedrockCacheControl(messages);
+
+    expect(result[0]).not.toBe(messages[0]);
+    expect(result[0].content).toEqual([
+      { type: ContentTypes.TEXT, text: 'Stable system text' },
+      { cachePoint: { type: 'default' } },
+      { type: ContentTypes.TEXT, text: 'Dynamic system text' },
+    ]);
+    expect(systemContent[0]).toHaveProperty('cache_control');
+    expect(systemContent[2]).toHaveProperty('cache_control');
+  });
+
+  it('strips Anthropic cache_control from serialized system messages without moving cache points', () => {
+    const systemContent = [
+      {
+        type: ContentTypes.TEXT,
+        text: 'Stable system text',
+        cache_control: { type: 'ephemeral' },
+      } as MessageContentComplex,
+      { cachePoint: { type: 'default' } },
+      {
+        type: ContentTypes.TEXT,
+        text: 'Dynamic system text',
+        cache_control: { type: 'ephemeral' },
+      } as MessageContentComplex,
+    ] as MessageContentComplex[];
+    const messages: TestMsg[] = [
+      { role: 'system', content: systemContent },
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi' },
+    ];
+
+    const result = addBedrockCacheControl(messages);
+
+    expect(result[0]).not.toBe(messages[0]);
+    expect(result[0].content).toEqual([
+      { type: ContentTypes.TEXT, text: 'Stable system text' },
+      { cachePoint: { type: 'default' } },
+      { type: ContentTypes.TEXT, text: 'Dynamic system text' },
+    ]);
+    expect(systemContent[0]).toHaveProperty('cache_control');
+    expect(systemContent[2]).toHaveProperty('cache_control');
+  });
+
+  it('skips serialized system messages while adding cache points to non-system turns', () => {
     const messages: TestMsg[] = [
       {
         role: 'system',
@@ -429,7 +530,7 @@ describe('addBedrockCacheControl (Bedrock cache checkpoints)', () => {
       type: ContentTypes.TEXT,
       text: 'You\'re an advanced AI assistant.',
     });
-    expect(system[1]).toEqual({ cachePoint: { type: 'default' } });
+    expect(system).toHaveLength(1);
     expect(user[0]).toEqual({
       type: ContentTypes.TEXT,
       text: 'What is the capital of France?',

package/src/messages/cache.ts

@@ -14,6 +14,10 @@ type MessageWithContent = {
   content?: string | MessageContentComplex[];
 };
 
+type MessageContentWithCacheControl = MessageContentComplex & {
+  cache_control?: unknown;
+};
+
 /**
  * Deep clones a message's content to prevent mutation of the original.
  */
@@ -101,6 +105,40 @@ function cloneMessage<T extends MessageWithContent>(
   return cloned;
 }
 
+function stripAnthropicCacheControlFromBlocks(
+  content: MessageContentComplex[]
+): { content: MessageContentComplex[]; modified: boolean } {
+  let modified = false;
+  const strippedContent = content.map((block) => {
+    if (!('cache_control' in block)) {
+      return block;
+    }
+
+    const cloned: MessageContentWithCacheControl = { ...block };
+    delete cloned.cache_control;
+    modified = true;
+    return cloned;
+  });
+
+  return { content: strippedContent, modified };
+}
+
+function sanitizeBedrockSystemMessage<T extends MessageWithContent>(
+  message: T
+): T {
+  const content = message.content;
+  if (!Array.isArray(content)) {
+    return message;
+  }
+
+  const stripped = stripAnthropicCacheControlFromBlocks(content);
+  if (!stripped.modified) {
+    return message;
+  }
+
+  return cloneMessage(message, stripped.content);
+}
+
 /**
  * Anthropic API: Adds cache control to the appropriate user messages in the payload.
  * Strips ALL existing cache control (both Anthropic and Bedrock formats) from all messages,
@@ -310,11 +348,24 @@ export function addBedrockCacheControl<
 
   for (let i = updatedMessages.length - 1; i >= 0; i--) {
     const originalMessage = updatedMessages[i];
-    const isToolMessage =
+    const messageType =
       'getType' in originalMessage &&
-      typeof originalMessage.getType === 'function' &&
-      originalMessage.getType() === 'tool';
+      typeof originalMessage.getType === 'function'
+        ? originalMessage.getType()
+        : undefined;
+    const messageRole =
+      'role' in originalMessage && typeof originalMessage.role === 'string'
+        ? originalMessage.role
+        : undefined;
+
+    const isSystemMessage =
+      messageType === 'system' || messageRole === 'system';
+    if (isSystemMessage) {
+      updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage);
+      continue;
+    }
 
+    const isToolMessage = messageType === 'tool' || messageRole === 'tool';
     const content = originalMessage.content;
     const hasArrayContent = Array.isArray(content);
     const isEmptyString = typeof content === 'string' && content === '';

package/src/specs/anthropic.simple.test.ts

@@ -376,6 +376,67 @@ describe(`${capitalizeFirstLetter(provider)} Streaming Tests`, () => {
     );
   });
 
+  test(`${capitalizeFirstLetter(provider)}: follow-up after assistant message with only whitespace text content`, async () => {
+    /**
+     * Regression for LibreChat discussion #12806.
+     *
+     * The Anthropic API has two distinct rejection rules (verified against
+     * the live API):
+     *   1. Strict empty `text: ''`  → rejected anywhere
+     *      "messages: text content blocks must be non-empty"
+     *   2. Whitespace-only `text: ' '` / '\n' / '\t' → rejected when the
+     *      assistant message has no other accepted blocks (no tool blocks,
+     *      no non-whitespace text)
+     *      "messages: text content blocks must contain non-whitespace text"
+     *
+     * Anthropic responses for some prompts include a whitespace-only text
+     * block as the sole text content. Re-sending that history on a
+     * follow-up turn triggers rule 2.
+     *
+     * The wire-send filter in `_formatContent` must drop any text block
+     * whose trimmed content is empty. The previous filter used strict
+     * `text === ''` only, which caught rule 1 but not rule 2.
+     */
+    const llmConfig = getLLMConfig(provider);
+    const customHandlers1 = setupCustomHandlers();
+
+    const followUpRun = await Run.create<t.IState>({
+      runId: 'repro-12806-followup',
+      graphConfig: {
+        type: 'standard',
+        llmConfig,
+        instructions: 'You are a friendly AI assistant.',
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers: customHandlers1,
+    });
+
+    // Build history with an assistant message whose entire content array
+    // is a single whitespace-only text block. This is the precise shape
+    // the API rejects under rule 2 above.
+    conversationHistory = [
+      new HumanMessage('hi'),
+      new (require('@langchain/core/messages').AIMessage)({
+        content: [{ type: 'text', text: ' ' }],
+      }),
+      new HumanMessage('please respond with a short greeting'),
+    ];
+
+    // With the fix: `_formatContent` drops the whitespace text block,
+    // the assistant content becomes an empty array, and the API accepts.
+    // Without the fix: the whitespace block is forwarded and the API
+    // rejects with "messages: text content blocks must contain non-whitespace text".
+    const finalContentParts = await followUpRun.processStream(
+      { messages: conversationHistory },
+      config
+    );
+    expect(finalContentParts).toBeDefined();
+    const finalMessages = followUpRun.getRunMessages();
+    expect(finalMessages).toBeDefined();
+    expect(finalMessages?.length).toBeGreaterThan(0);
+  });
+
   test('should handle errors appropriately', async () => {
     // Test error scenarios
     await expect(async () => {

package/src/specs/summarization.test.ts

@@ -22,6 +22,8 @@ import { formatAgentMessages } from '@/messages/format';
 import { FakeListChatModel } from '@langchain/core/utils/testing';
 import * as providers from '@/llm/providers';
 
+const SUMMARY_WRAPPER_OVERHEAD_TOKENS = 33;
+
 /** Extract plain text from a SummaryContentBlock's content array (test helper). */
 function getSummaryText(summary: t.SummaryContentBlock | undefined): string {
   if (!summary) return '';
@@ -1443,7 +1445,8 @@ describe('Cross-run summary lifecycle (no API keys)', () => {
     expect(completePayload.summary!.tokenCount ?? 0).toBeGreaterThan(0);
 
     const expectedTokenCount =
-      tokenCounter(new SystemMessage(KNOWN_SUMMARY)) + 33;
+      tokenCounter(new SystemMessage(KNOWN_SUMMARY)) +
+      SUMMARY_WRAPPER_OVERHEAD_TOKENS;
     expect(completePayload.summary!.tokenCount).toBe(expectedTokenCount);
 
     const summaryBlock = completePayload.summary!;
@@ -2605,8 +2608,9 @@ const hasAnyApiKey =
     const summaryText = getSummaryText(completePayload.summary);
     const reportedTokenCount = completePayload.summary!.tokenCount ?? 0;
 
-    // Count tokens locally using the same tokenizer
-    const localTokenCount = tokenCounter(new SystemMessage(summaryText));
+    const localTokenCount =
+      tokenCounter(new SystemMessage(summaryText)) +
+      SUMMARY_WRAPPER_OVERHEAD_TOKENS;
 
     console.log(
       `  Token match: reported=${reportedTokenCount}, local=${localTokenCount}`

package/src/tools/BashExecutor.ts

@@ -3,17 +3,23 @@ import fetch, { RequestInit } from 'node-fetch';
 import { HttpsProxyAgent } from 'https-proxy-agent';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
-import { imageExtRegex, getCodeBaseURL } from './CodeExecutor';
+import { getCodeBaseURL, renderFileSection } from './CodeExecutor';
 import { Constants } from '@/common';
 
 config();
 
-const imageMessage = 'Image is already displayed to the user';
 const otherMessage = 'File is already downloaded by the user';
+const inheritedFileMessage =
+  'Available as an input — already known to the user';
 const accessMessage =
   'Note: Files from previous executions are automatically available and can be modified.';
 const emptyOutputMessage =
   'stdout: Empty. Ensure you\'re writing output explicitly.\n';
+const inheritedFilesHeader =
+  'Available files (inputs, not generated by this execution):';
+const generatedFilesHeader = 'Generated files:';
+const inheritedNote =
+  'Note: Files in "Available files" are inputs the user (or a skill) already provided to the sandbox. They were not produced by this execution and you should not present them as new outputs in your response.';
 
 const baseEndpoint = getCodeBaseURL();
 const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
@@ -198,20 +204,38 @@ function createBashExecutionTool(
         }
         if (result.stderr) formattedOutput += `stderr:\n${result.stderr}\n`;
         if (result.files && result.files.length > 0) {
-          formattedOutput += 'Generated files:\n';
+          /* Split inherited (read-only / unchanged-input passthroughs from
+           * codeapi) from genuine generated outputs. The LLM was previously
+           * shown skill files under "Generated files:" with the message
+           * "File is already downloaded by the user", which led it to
+           * (a) believe it had just produced files it merely referenced
+           * and (b) sometimes invent paths like /mnt/user-data/uploads/
+           * trying to find the "originals". Labeling them as inputs makes
+           * the mental model accurate. */
+          const inheritedFiles = result.files.filter(
+            (f) => f.inherited === true
+          );
+          const generatedFiles = result.files.filter(
+            (f) => f.inherited !== true
+          );
 
-          const fileCount = result.files.length;
-          for (let i = 0; i < fileCount; i++) {
-            const file = result.files[i];
-            const isImage = imageExtRegex.test(file.name);
-            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
+          formattedOutput += renderFileSection(
+            generatedFilesHeader,
+            generatedFiles,
+            otherMessage
+          );
+          formattedOutput += renderFileSection(
+            inheritedFilesHeader,
+            inheritedFiles,
+            inheritedFileMessage
+          );
 
-            if (i < fileCount - 1) {
-              formattedOutput += fileCount <= 3 ? ', ' : ',\n';
-            }
+          if (generatedFiles.length > 0) {
+            formattedOutput += `\n\n${accessMessage}`;
+          }
+          if (inheritedFiles.length > 0) {
+            formattedOutput += `\n\n${inheritedNote}`;
           }
-
-          formattedOutput += `\n\n${accessMessage}`;
           return [
             formattedOutput.trim(),
             {

package/src/tools/CodeExecutor.ts

@@ -15,10 +15,41 @@ export const getCodeBaseURL = (): string =>
 
 const imageMessage = 'Image is already displayed to the user';
 const otherMessage = 'File is already downloaded by the user';
+const inheritedFileMessage =
+  'Available as an input — already known to the user';
 const accessMessage =
   'Note: Files from previous executions are automatically available and can be modified.';
 const emptyOutputMessage =
   'stdout: Empty. Ensure you\'re writing output explicitly.\n';
+const inheritedFilesHeader =
+  'Available files (inputs, not generated by this execution):';
+const generatedFilesHeader = 'Generated files:';
+const inheritedNote =
+  'Note: Files in "Available files" are inputs the user (or a skill) already provided to the sandbox. They were not produced by this execution and you should not present them as new outputs in your response.';
+
+/**
+ * Renders one section of the post-execution file listing. Used by the
+ * code/bash tool formatters to keep generated outputs and inherited
+ * inputs visually separated. See BashExecutor for full docs.
+ */
+export function renderFileSection(
+  header: string,
+  files: t.FileRefs,
+  defaultMessage: string
+): string {
+  if (files.length === 0) return '';
+  let out = `${header}\n`;
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    const isImage = imageExtRegex.test(file.name);
+    out += `- /mnt/data/${file.name} | ${isImage ? imageMessage : defaultMessage}`;
+    if (i < files.length - 1) {
+      out += files.length <= 3 ? ', ' : ',\n';
+    }
+  }
+  out += '\n';
+  return out;
+}
 
 const SUPPORTED_LANGUAGES = [
   'py',
@@ -196,20 +227,33 @@ function createCodeExecutionTool(
         }
         if (result.stderr) formattedOutput += `stderr:\n${result.stderr}\n`;
         if (result.files && result.files.length > 0) {
-          formattedOutput += 'Generated files:\n';
+          /* See BashExecutor for the rationale: split inherited (read-only
+           * passthrough) inputs from real generated outputs so the LLM
+           * doesn't conflate skill files with newly-produced artifacts. */
+          const inheritedFiles = result.files.filter(
+            (f) => f.inherited === true
+          );
+          const generatedFiles = result.files.filter(
+            (f) => f.inherited !== true
+          );
 
-          const fileCount = result.files.length;
-          for (let i = 0; i < fileCount; i++) {
-            const file = result.files[i];
-            const isImage = imageExtRegex.test(file.name);
-            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
+          formattedOutput += renderFileSection(
+            generatedFilesHeader,
+            generatedFiles,
+            otherMessage
+          );
+          formattedOutput += renderFileSection(
+            inheritedFilesHeader,
+            inheritedFiles,
+            inheritedFileMessage
+          );
 
-            if (i < fileCount - 1) {
-              formattedOutput += fileCount <= 3 ? ', ' : ',\n';
-            }
+          if (generatedFiles.length > 0) {
+            formattedOutput += `\n\n${accessMessage}`;
+          }
+          if (inheritedFiles.length > 0) {
+            formattedOutput += `\n\n${inheritedNote}`;
           }
-
-          formattedOutput += `\n\n${accessMessage}`;
           return [
             formattedOutput.trim(),
             {

package/src/tools/ProgrammaticToolCalling.ts

@@ -5,7 +5,7 @@ import { HttpsProxyAgent } from 'https-proxy-agent';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
-import { imageExtRegex, getCodeBaseURL } from './CodeExecutor';
+import { getCodeBaseURL, renderFileSection } from './CodeExecutor';
 import { Constants } from '@/common';
 
 config();
@@ -14,8 +14,14 @@ config();
 // Constants
 // ============================================================================
 
-const imageMessage = 'Image is already displayed to the user';
 const otherMessage = 'File is already downloaded by the user';
+const inheritedFileMessage =
+  'Available as an input — already known to the user';
+const inheritedFilesHeader =
+  'Available files (inputs, not generated by this execution):';
+const generatedFilesHeader = 'Generated files:';
+const inheritedNote =
+  'Note: Files in "Available files" are inputs the user (or a skill) already provided to the sandbox. They were not produced by this execution and you should not present them as new outputs in your response.';
 const accessMessage =
   'Note: Files from previous executions are automatically available and can be modified.';
 const emptyOutputMessage =
@@ -552,20 +558,29 @@ export function formatCompletedResponse(
   }
 
   if (response.files && response.files.length > 0) {
-    formatted += 'Generated files:\n';
-
-    const fileCount = response.files.length;
-    for (let i = 0; i < fileCount; i++) {
-      const file = response.files[i];
-      const isImage = imageExtRegex.test(file.name);
-      formatted += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
+    /* See BashExecutor for the rationale: split inherited (read-only
+     * passthrough) inputs from real generated outputs so the LLM doesn't
+     * conflate skill files with newly-produced artifacts. */
+    const inheritedFiles = response.files.filter((f) => f.inherited === true);
+    const generatedFiles = response.files.filter((f) => f.inherited !== true);
+
+    formatted += renderFileSection(
+      generatedFilesHeader,
+      generatedFiles,
+      otherMessage
+    );
+    formatted += renderFileSection(
+      inheritedFilesHeader,
+      inheritedFiles,
+      inheritedFileMessage
+    );
 
-      if (i < fileCount - 1) {
-        formatted += fileCount <= 3 ? ', ' : ',\n';
-      }
+    if (generatedFiles.length > 0) {
+      formatted += `\n\n${accessMessage}`;
+    }
+    if (inheritedFiles.length > 0) {
+      formatted += `\n\n${inheritedNote}`;
     }
-
-    formatted += `\n\n${accessMessage}`;
   }
 
   return [

package/src/tools/__tests__/ProgrammaticToolCalling.test.ts

@@ -664,6 +664,66 @@ for member in team:
       expect(output).toContain('chart.png');
       expect(output).toContain('Image is already displayed to the user');
     });
+
+    it('splits inherited inputs from generated outputs into distinct sections', () => {
+      const response: t.ProgrammaticExecutionResponse = {
+        status: 'completed',
+        stdout: 'analysis done\n',
+        stderr: '',
+        files: [
+          { id: 'g1', name: 'report.pdf' },
+          { id: 'i1', name: 'pptx/SKILL.md', inherited: true },
+          { id: 'i2', name: 'pptx/scripts/clean.py', inherited: true },
+          { id: 'g2', name: 'chart.png' },
+        ],
+        session_id: 'sess_abc123',
+      };
+
+      const [output, artifact] = formatCompletedResponse(response);
+
+      /* Generated section lists only outputs the run produced. */
+      const generatedIdx = output.indexOf('Generated files:');
+      const inheritedIdx = output.indexOf('Available files (inputs');
+      expect(generatedIdx).toBeGreaterThan(-1);
+      expect(inheritedIdx).toBeGreaterThan(generatedIdx);
+
+      /* Slice each section so we can assert membership without
+       * cross-talk between the two listings. */
+      const generatedSection = output.slice(generatedIdx, inheritedIdx);
+      const inheritedSection = output.slice(inheritedIdx);
+
+      expect(generatedSection).toContain('report.pdf');
+      expect(generatedSection).toContain('chart.png');
+      expect(generatedSection).not.toContain('SKILL.md');
+
+      expect(inheritedSection).toContain('pptx/SKILL.md');
+      expect(inheritedSection).toContain('pptx/scripts/clean.py');
+      expect(inheritedSection).toContain('Available as an input');
+
+      /* The artifact still carries every file so the host can still
+       * thread per-file ids through to subsequent calls. */
+      expect(artifact.files).toHaveLength(4);
+    });
+
+    it('omits the Generated files header when every entry is inherited', () => {
+      const response: t.ProgrammaticExecutionResponse = {
+        status: 'completed',
+        stdout: 'cat: ok\n',
+        stderr: '',
+        files: [
+          { id: 'i1', name: 'pptx/SKILL.md', inherited: true },
+          { id: 'i2', name: 'pptx/editing.md', inherited: true },
+        ],
+        session_id: 'sess_abc123',
+      };
+
+      const [output] = formatCompletedResponse(response);
+
+      expect(output).not.toContain('Generated files:');
+      expect(output).toContain('Available files (inputs');
+      expect(output).toContain('pptx/SKILL.md');
+      expect(output).toContain('pptx/editing.md');
+    });
   });
 
   describe('createProgrammaticToolCallingTool - Manual Invocation', () => {

package/src/types/graph.ts

@@ -471,10 +471,12 @@ export interface AgentInputs {
   toolMap?: ToolMap;
   tools?: GraphTools;
   provider: Providers;
+  /** Stable/cacheable system instructions. */
   instructions?: string;
   streamBuffer?: number;
   maxContextTokens?: number;
   clientOptions?: ClientOptions;
+  /** Dynamic system tail appended after stable instructions without provider cache markers. */
   additional_instructions?: string;
   reasoningKey?: 'reasoning_content' | 'reasoning';
   /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */
@@ -500,7 +502,7 @@ export interface AgentInputs {
   summarizationEnabled?: boolean;
   summarizationConfig?: SummarizationConfig;
   /** Cross-run summary from a previous run, forwarded from formatAgentMessages.
-   *  Injected into the system message via AgentContext.buildInstructionsString(). */
+   *  Injected into the dynamic system tail via AgentContext. */
   initialSummary?: { text: string; tokenCount: number };
   contextPruningConfig?: ContextPruningConfig;
   maxToolResultChars?: number;

package/src/types/run.ts

@@ -75,7 +75,9 @@ export interface AgentStateChannels {
   messages: BaseMessage[];
   next: string;
   [key: string]: unknown;
+  /** Stable/cacheable system instructions. */
   instructions?: string;
+  /** Dynamic system tail appended after stable instructions. */
   additional_instructions?: string;
 }
 

package/src/types/tools.ts

@@ -113,6 +113,15 @@ export type FileRef = {
   path?: string;
   /** Session ID this file belongs to (for multi-session file tracking) */
   session_id?: string;
+  /**
+   * `true` when the codeapi sandbox echoed this entry as an unchanged
+   * passthrough of an input the caller already owns (skill files,
+   * downloaded inputs whose hash matched the baseline, inherited
+   * `.dirkeep` markers). The tool-result formatter renders these as
+   * "Available files" rather than "Generated files" so the LLM doesn't
+   * conflate infrastructure inputs with newly-produced outputs.
+   */
+  inherited?: true;
 };
 
 export type FileRefs = FileRef[];