fix: truncateToolOutput may exceed maxChars when limit < marker overhead

- Fall back to hard slice when maxChars is too small to fit the marker
- Fix misplaced JSDoc for outputSchema in AgentConfig
- Tighten test assertion to verify length <= maxChars

src/tool/executor.ts

@@ -220,7 +220,13 @@ export function truncateToolOutput(data: string, maxChars: number): string {
   const markerTemplate = '\n\n[...truncated  characters...]\n\n'
   const markerOverhead = markerTemplate.length + String(data.length).length
 
-  const available = Math.max(0, maxChars - markerOverhead)
+  // When maxChars is too small to fit any content alongside the marker,
+  // fall back to a hard slice so the result never exceeds maxChars.
+  if (maxChars <= markerOverhead) {
+    return data.slice(0, maxChars)
+  }
+
+  const available = maxChars - markerOverhead
   const headChars = Math.floor(available * 0.7)
   const tailChars = available - headChars
   const truncatedCount = data.length - headChars - tailChars

src/types.ts

@@ -253,11 +253,6 @@ export interface AgentConfig {
    * calls and text outputs to detect stuck loops before `maxTurns` is reached.
    */
   readonly loopDetection?: LoopDetectionConfig
-  /**
-   * Optional Zod schema for structured output.  When set, the agent's final
-   * output is parsed as JSON and validated against this schema.  A single
-   * retry with error feedback is attempted on validation failure.
-   */
   /**
    * Maximum tool output length in characters for all tools used by this agent.
    * When set, tool outputs exceeding this limit are truncated (head + tail
@@ -265,6 +260,11 @@ export interface AgentConfig {
    * takes priority over this value.
    */
   readonly maxToolOutputChars?: number
+  /**
+   * Optional Zod schema for structured output.  When set, the agent's final
+   * output is parsed as JSON and validated against this schema.  A single
+   * retry with error feedback is attempted on validation failure.
+   */
   readonly outputSchema?: ZodSchema
   /**
    * Called before each agent run. Receives the prompt and agent config.

tests/tool-executor.test.ts

@@ -231,9 +231,9 @@ describe('truncateToolOutput', () => {
 
   it('handles very small maxChars gracefully', () => {
     const data = 'x'.repeat(100)
-    // With maxChars=1, the marker alone exceeds the budget, but it should not crash
+    // With maxChars=1, the marker alone exceeds the budget — falls back to hard slice
     const result = truncateToolOutput(data, 1)
-    expect(result).toContain('[...truncated')
+    expect(result.length).toBeLessThanOrEqual(1)
   })
 })