Complete oversized tool-result spill: safe durable default, errors, and all result paths

[antra-tess]

Incident / motivation

Connectome house issue 29 asks for large MCPL/tool results (including nested data and read_file-like tools) to be truncated to a small inline preview, with complete content automatically written to a file and linked from the preview.

On 2026-08-05, Mythos unintentionally received roughly 42k characters from a Tweeter search result. The content itself is private and is not reproduced here. The resident did not ask to ingest a blob of that size.

Existing implementation

AF commit f231bbfaecca4b9528ba0aec2f5c6cdc585b162c (feat(code-execution): background scripts with wake_agent + oversized-result spill, included in v0.8.0) already implements most of the mechanism:

• successful result data is serialized through toolResultDataToHistoryString;
• content above the inline cap is written to the first writable workspace at tool-results/<date>-<callId>.txt;
• model-visible content becomes a truncated head plus an exact file reference;
• history and live wire reuse the same spilled string;
• background-script wake payloads use the same helper;
• agent_settings.tool_result_inline_max_chars supplies a hot per-agent override.

The incident still occurs because the ordinary default is strategy.maxMessageTokens * 4, commonly tens of thousands of characters. The agent-settings override is ephemeral.

Required completion

1. Add a durable recipe/Host-configurable tool-result inline cap with an intentionally safe default (house request: approximately 5k characters), while retaining the hot per-agent override.
2. Report desired/effective/source provenance through agent_settings / runtime status; restarts must not silently restore the large strategy-derived cap when a residence configured a smaller one.
3. Apply one spill policy to all text-bearing result paths, including:
   • ordinary successful MCP/MCPL tools;
   • nested object data;
   • read_file / shell / search-style tools;
   • error results (currently skipped by the successful-result spill loop);
   • background-script wakes;
   • end-turn / short-circuit / alternate completion paths.
4. Preserve the exact full result in a writable workspace file and return a bounded preview plus referential path. If no writable workspace exists, fail safely with explicit plain truncation rather than silently retaining the blob.
5. Audit pre-allocation/network limits separately. Current AF spilling happens only after the complete result has arrived and been serialized; it protects model context, not host memory or adapter bandwidth. Adapters that fetch remote data should support byte-bounded reads where possible.
6. Keep native image-block handling intact; never corrupt base64 through character truncation.
7. Define file lifecycle/privacy semantics: naming/collision behavior, retention, branch/workspace provenance, and whether “temporary” means GC-eligible rather than silently permanent.

Tests

• 42k+ nested MCPL data spills under the configured default and links the exact full file.
• huge success and huge error strings follow the same bounded policy.
• no-writable-workspace fallback is explicit and bounded.
• history and live provider wire remain byte-identical.
• restart preserves configured residence cap.
• hot override and reset semantics remain correct.
• adapter-level byte cap is tested independently from AF context spill.

This is a completion/audit issue, not a request to reimplement spilling from scratch.

[antra-tess]

PR up: #91 — completes items 1–4, 6, 7 of the required list (durable FrameworkConfig.toolResultInlineMaxChars, house default 5000, effective/source provenance via agent_settings get, error-result + guard-path + wake-payload + direct-API coverage, image safety, explicit no-workspace fallback, documented file lifecycle). 9 new tests; full suite 539/540 pass, 0 fail (1 pre-existing skip).

Deliberately NOT auto-closing this issue: item 5 (adapter-level pre-allocation / byte-bounded reads) remains open — AF spilling still happens after the complete result has arrived and been serialized, so it protects model context, not host memory or adapter bandwidth. That's a per-adapter audit (discord-mcpl, portal-mcpl, search/twitter-shaped servers) and worth its own tracking once the AF side lands.

Also pending after merge: an AF release + a connectome-host passthrough PR so residences can set the cap in recipes (will open dependency-separated, host#48-style).