kami/correx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
kami
2026-07-12 19:46:02 +04:00
parent 3a4e577b5b
commit 2912799fe0
7 changed files with 226 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
core/events/src/main/kotlin/com/correx/core/events/events/ToolReceipt.kt
+4
View File
@@ -19,4 +19,8 @@ data class ToolReceipt(
val tier: Tier,
val timestamp: Instant,
val diff: String? = null,
// Artifact-store hash of the FULL tool output when it was truncated for model context (the
// outputSummary above is a bounded preview). Null when nothing was truncated. Lets an agent
// retrieve everything via the tool_output tool without bloating the event log with raw output.
val fullOutputHash: String? = null,
)
core/kernel/src/main/kotlin/com/correx/core/kernel/orchestration/SessionOrchestrator.kt
+65 -12
View File
@@ -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,
),
),
)
core/kernel/src/test/kotlin/com/correx/core/kernel/orchestration/FrameTruncatedToolResultTest.kt
+30
View File
@@ -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)
}
}
core/transitions/src/main/kotlin/com/correx/core/transitions/graph/StageConfig.kt
+2 -1
View File
@@ -66,6 +66,7 @@ data class StageConfig(
companion object {
/** Read-only tools every tool-granting stage may call regardless of its declared set. */
val ALWAYS_AVAILABLE_READ_TOOLS: Set<String> = setOf("file_read", "list_dir", "glob", "grep")
val ALWAYS_AVAILABLE_READ_TOOLS: Set<String> =
setOf("file_read", "list_dir", "glob", "grep", "tool_output")
}
}