stacklok / stacklok/mecatl

Reevaluate filesystem spillover for oversized tool results

Open
#902 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
152
Forks
16
Avg merge
14h 48m
Merged PRs (30d)
536

Description

Problem\n\nMecatl currently truncates model-facing tool output (or, for oversized structured MCP JSON, returns a fail-closed error). The cascade compactor can later replace old file-read bodies with a re-fetch pointer, but there is no general mechanism to preserve an oversized result outside the context window for selective follow-up.\n\nDisk spill was previously rejected because the no-fs profile and storage-free deployments must remain supported. That constraint does not necessarily rule out an optional capability: many sessions have a workspace filesystem.\n\n## Proposal to evaluate\n\nInvestigate an optional, generic oversized-tool-result spill facility:\n\n- When a session has an appropriate filesystem/workspace, persist an oversized result to a controlled session-scoped location and return a compact, model-visible reference plus retrieval affordance.\n- When the session is no-fs or its filesystem is unavailable, disable spill explicitly and retain the current truncation/fail-closed behavior.\n- Preserve the existing security and workspace invariants: no arbitrary path exposure, bounded storage/lifetime, safe cleanup, and no silent loss of structured-result semantics.\n- Establish how spilled data interacts with session persistence, compaction, event logs, delegated environments, and cloud-native/storage-free deployments.\n\n## Alternatives\n\nContinue relying only on remote pagination/filtering (including CallMcpWithQuery for MCP JSON) and truncation/compaction.\n\n## Relevant prior decision\n\nADR 0063 rejected unconditional scratch-file spill for portability reasons. This issue is to reconsider that decision in light of an optional filesystem capability, not to remove no-fs support.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading ADR 0063 and reviewing the current truncation, fail-closed, compaction, and CallMcpWithQuery behavior described in the issue. Done means a documented evaluation and decision covering optional filesystem use, no-fs behavior, security and workspace invariants, bounded cleanup, persistence, event logs, delegated environments, and storage-free deployments.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
backend, cloud, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.