feat(tools): bound+frame tool results, spill full output to CAS, tool_output retrieval

Tool results injected into model context are now consistently framed and globally bounded. Success output over the floor (TOOL_RESULT_MAX_CHARS=8000) is head/tail-truncated with a marker naming a retrieval ref; the full raw output spills to the artifact store (CAS) and its hash is recorded on the ToolReceipt (fullOutputHash) in the event log. Agents recover the full text via the new read-only tool_output(ref=...) tool. - SessionOrchestrator: frameTruncatedToolResult + renderToolResult; char-cap head/tail so a single pathological long line can't defeat the bound. - ToolReceipt.fullOutputHash (additive, nullable). - ToolOutputTool (Tier T1, no fs capability) resolves ref -> full bytes. - Wired via extraTools in Main.kt; tool_output added to ALWAYS_AVAILABLE_READ_TOOLS. - Failure path keeps ERROR:/FATAL: prefixes (all-rejected breaker dependency). Tests: FrameTruncatedToolResultTest, ToolOutputToolTest.
2026-07-12 19:46:02 +04:00
parent 3a4e577b5b
commit 2912799fe0
7 changed files with 226 additions and 15 deletions
@@ -203,6 +203,31 @@ private const val SCOPE_PROPOSAL_TOOL = "propose_scope"
 private const val READ_BEFORE_WRITE_CODE = "READ_BEFORE_WRITE"
 private const val REFERENCE_EXISTS_CODE = "REFERENCE_EXISTS"
 private const val OUTPUT_SUMMARY_LIMIT = 500
+
+// Global floor on tool-result text entering model context, applied beneath each tool's own
+// outputCompressor. A tool without a compressor (or one whose output survives compression) can still
+// flood a small model's window, so any Success body over this many chars is shown head+tail with a
+// marker and the FULL raw output spilled to the artifact store for retrieval via tool_output.
+// ponytail: fixed constants; lift to OrchestrationTuning if operators need to tune per-deployment.
+private const val TOOL_RESULT_MAX_CHARS = 8_000
+private const val TOOL_RESULT_HEAD_LINES = 60
+private const val TOOL_RESULT_TAIL_LINES = 60
+private const val TOOL_OUTPUT_TOOL = "tool_output"
+
+/**
+ * Frame an over-cap tool output as `header` + head lines + a truncation marker (naming the
+ * [tool_output] ref that retrieves the full text) + tail lines. Head and tail are each char-capped
+ * so a single pathological long line can't defeat the line-count bound. Pure — the caller spills the
+ * full output and supplies its [ref].
+ */
+internal fun frameTruncatedToolResult(header: String, compressed: String, ref: String): String {
+    val lines = compressed.split("\n")
+    val head = lines.take(TOOL_RESULT_HEAD_LINES).joinToString("\n").take(TOOL_RESULT_MAX_CHARS / 2)
+    val tail = lines.takeLast(TOOL_RESULT_TAIL_LINES).joinToString("\n").takeLast(TOOL_RESULT_MAX_CHARS / 2)
+    val marker = "… output truncated (${lines.size} lines); " +
+        "call $TOOL_OUTPUT_TOOL(ref=\"$ref\") for the full output …"
+    return "$header\n$head\n$marker\n$tail"
+}
 // Read-on-demand doc catalog: the top-N docs (by repo-map recency score) surfaced as
 // `path — descriptor` so a stage learns which docs exist and can file_read one when relevant,
 // instead of docs being force-fed (or excluded outright). One line each, hard-capped, so it can
@@ -1101,6 +1126,38 @@ abstract class SessionOrchestrator(
            "\nAccepted parameters for '${it.name}': ${it.parametersSchema}"
        }.orEmpty()

+    private data class RenderedToolResult(val content: String, val fullOutputHash: String?)
+
+    /**
+     * Render a tool result into the consistently-framed, bounded text the model sees. Success output
+     * is run through the tool's [ToolOutputCompressor], then framed with a uniform `[tool exit=N]`
+     * header. If it still exceeds [TOOL_RESULT_MAX_CHARS] the FULL raw output is spilled to the
+     * artifact store (CAS — durable, its hash recorded on the ToolReceipt in the event log) and only a
+     * head+tail preview is shown, with a marker telling the model to call `tool_output(ref=…)` for the
+     * rest. Failures keep their `ERROR:`/`FATAL:` sentinels unchanged — the all-rejected loop breaker
+     * keys on those prefixes.
+     */
+    private suspend fun renderToolResult(toolName: String, tool: Tool?, result: ToolResult): RenderedToolResult =
+        when (result) {
+            is ToolResult.Failure -> RenderedToolResult(
+                if (!result.recoverable) "FATAL: ${result.reason}" else "ERROR: ${result.reason}${toolArgsHint(tool)}",
+                null,
+            )
+            is ToolResult.Success -> {
+                val compressed = tool?.outputCompressor?.compress(result.output, ToolOutputContext(result.exitCode))
+                    ?: result.output
+                val header = "[$toolName exit=${result.exitCode}]"
+                if (compressed.length <= TOOL_RESULT_MAX_CHARS) {
+                    RenderedToolResult("$header\n$compressed", null)
+                } else {
+                    // Spill the full RAW output (most complete) so retrieval returns everything, not the
+                    // already-compressed preview the model saw.
+                    val ref = artifactStore.put(result.output.toByteArray()).value
+                    RenderedToolResult(frameTruncatedToolResult(header, compressed, ref), ref)
+                }
+            }
+        }
+
    private suspend fun dispatchToolCalls(
        sessionId: SessionId,
        stageId: StageId,
@@ -1410,6 +1467,9 @@ abstract class SessionOrchestrator(
                ?.let { request.copy(grantedPaths = grantedOutside + it.toString()) }
                ?: request
            val result = executor.execute(executedRequest)
+            // Frame + bound the result once; on truncation this spills the full output to CAS and
+            // returns its hash, which we record on the receipt so the event log points at the full text.
+            val rendered = renderToolResult(toolCall.function.name, tool, result)

            // Store ProcessResult artifact for every shell execution outcome
            for (slot in processResultSlots) {
@@ -1452,7 +1512,7 @@ abstract class SessionOrchestrator(
            // artifact carries the diff as evidence of the change.
            recordToolExecution(
                sessionId, stageId, toolCall, invocationId, tier, result,
-                tool as? FileAffectingTool, request, fileWrittenSlots,
+                tool as? FileAffectingTool, request, fileWrittenSlots, rendered.fullOutputHash,
            )

            val sourceId = toolCall.id ?: invocationId.value
@@ -1466,22 +1526,13 @@ abstract class SessionOrchestrator(
                role = EntryRole.ASSISTANT,
                reasoning = toolCallReasoning,
            )
-            val resultContent = when (result) {
-                is ToolResult.Success ->
-                    tool?.outputCompressor?.compress(result.output, ToolOutputContext(result.exitCode))
-                        ?: result.output
-                is ToolResult.Failure -> {
-                    if (!result.recoverable) "FATAL: ${result.reason}"
-                    else "ERROR: ${result.reason}${toolArgsHint(tool)}"
-                }
-            }
            val resultEntry = ContextEntry(
                id = ContextEntryId(UUID.randomUUID().toString()),
                layer = ContextLayer.L2,
                sourceType = "toolResult",
                sourceId = sourceId,
-                content = resultContent,
-                tokenEstimate = estimateTokens(resultContent),
+                content = rendered.content,
+                tokenEstimate = estimateTokens(rendered.content),
                role = EntryRole.TOOL,
            )
            val steeringEntry = approvalNote?.takeIf { it.isNotBlank() }?.let {
@@ -2098,6 +2149,7 @@ abstract class SessionOrchestrator(
        fileTool: FileAffectingTool?,
        request: ToolRequest,
        fileWrittenSlots: List<TypedArtifactSlot>,
+        fullOutputHash: String? = null,
    ) {
        // Invariant #5: every tool side effect is captured. This is the single authoritative
        // ToolExecutionCompleted/Failed record and the source the read-before-write gate replays.
@@ -2136,6 +2188,7 @@ abstract class SessionOrchestrator(
                            tier = tier,
                            timestamp = Clock.System.now(),
                            diff = diff,
+                            fullOutputHash = fullOutputHash,
                        ),
                    ),
                )
@@ -0,0 +1,30 @@
+package com.correx.core.kernel.orchestration
+
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
+
+class FrameTruncatedToolResultTest {
+
+    @Test
+    fun `keeps header, head, tail and a marker naming the retrieval ref`() {
+        val body = (1..300).joinToString("\n") { "line-$it" }
+        val out = frameTruncatedToolResult("[grep exit=0]", body, "abc123")
+
+        assertTrue(out.startsWith("[grep exit=0]"), out)
+        assertTrue(out.contains("line-1\n"), "head lines kept")
+        assertTrue(out.contains("line-300"), "tail lines kept")
+        assertTrue(out.contains("output truncated (300 lines)"), out)
+        assertTrue(out.contains("tool_output(ref=\"abc123\")"), out)
+        // Middle is dropped — a line well inside the elided span must be absent.
+        assertTrue(!out.contains("line-150"), "middle elided")
+    }
+
+    @Test
+    fun `char-caps a single pathological long line so the bound is not defeated`() {
+        val giant = "x".repeat(1_000_000)
+        val out = frameTruncatedToolResult("[shell exit=0]", giant, "ref")
+        // One line means head==tail==giant; each is char-capped, so output can't be ~2MB.
+        assertTrue(out.length < 20_000, "length was ${out.length}")
+        assertTrue(out.contains("tool_output(ref=\"ref\")"), out)
+    }
+}