[alfredolopez80]

Summary

Agentic workflow steps paste every tool result into the prompt in full and resend it on each
iteration. This gives WorkflowService.executeStep a per-execution, in-memory store for large
tool results. It returns the first-party summary format and reuses the first-party
clerum__spillover_read tool; mcp-host/src/core/spillover is unchanged. It is on by
default for every recipe that runs an mcp-host.

• A tool result of at least CLERUM_WORKFLOW_TOOL_SPILLOVER_THRESHOLD bytes (default 131072),
  measured on the JSON-serialized result, is kept in the mcp-host process memory for the
  length of the step execution, and the model receives the store's summary (head, tail, size,
  structure hint, spillover_ref). Refs are spillover://<stepId>/<callId>.json. Nothing is
  written to the run's output directory or anywhere else on disk.
• After the first stored result, the step is offered clerum__spillover_read, limited to
  refs of the same step, to results of the same execution, and to reads of at most the
  threshold; larger results must be read with range.
• A step whose results all stay under the threshold is byte-for-byte unchanged: same
  prompts, same offered tools.
• A budget per step execution (CLERUM_WORKFLOW_TOOL_SPILLOVER_BUDGET_BYTES, default 16 MiB,
  1 MiB to 256 MiB) caps the result bytes the store holds. A result that would take the total
  over the budget stays inline, as without spillover; a later result that still fits is
  stored. The budget never stops or fails the step.
• Each step execution has its own store, dropped when the execution ends (completed, failed,
  aborted or timed out). Two executions of the same step never see each other's results. If
  the mcp-host process dies, the results are gone with it; there is nothing to clean up.
• Memory: a stored result is the string the step would otherwise keep in its prompt, so the
  store adds about 7% over inline mode (measured: +17.2 MB for a full 16 MiB budget, +16.0 MB
  inline) and frees it at step end. One mcp-host serves all concurrent runs of a recipe and
  /execute has no concurrency cap, so memory grows with the number of concurrent step
  executions, as it does without spillover. The pod limit (2Gi) bounds it per recipe.
• toolsCalled keeps the original result, so artifact detection and the status report are
  unchanged. clerum__spillover_read calls record the ref and byte count, not the content.
• Workflow steps report to their own counters,
  clerum_workflow_step_spillover_persisted_total{tool} and
  clerum_workflow_step_spillover_reads_total{with_range}. The first-party metrics
  (clerum_spillover_persisted_total, clerum_spillover_reads_total,
  clerum_tool_output_bytes) keep their names and labels and do not receive workflow step
  results.
• CLERUM_WORKFLOW_TOOL_SPILLOVER_ENABLED=false is the operator kill switch and restores the
  previous behaviour. It is a separate variable from the first-party
  CLERUM_TOOL_SPILLOVER_ENABLED because threshold and retention differ.

Merge order: the workflow-recipes change that adds these variables to
MCP_HOST_ENV_PASSTHROUGH (#1453) is merged and deployed in the dev cluster, and dev is
merged into this branch, so the kill switch reaches recipe pods.

Owner decisions (2026-11-14):

1. With allowedTools.include, the read tool becomes callable once a result has been
   spilled. Accepted as a deliberate exception to "the allowlist is the complete toolset".
2. Threshold default: 128 KiB. The first-party default is 8 KiB, but that loop also compacts.
   A result below 128 KiB stays inline; a larger one is read back in slices of at most
   128 KiB, so one read can add up to 128 KiB to every later iteration of the step.

Blocking before merge: the validation below, run by a maintainer first on the local
Minikube T2 lane and then in the dev cluster, comparing off / 128 KiB / 32 KiB. Results to be
attached here.

Also for owners: per-execution budget (16 MiB) and dropping stored results at step end.
Decided 2026-11-13: stored results live in the mcp-host process memory, not on the output volume.

Known limit: this bounds each result, not their sum. Context still grows with the number of
calls until steps run on the agent loop with compaction. When that lands, revisit lowering
the threshold to the first-party 8 KiB.

Validation script (run by a maintainer; cloud sessions cannot run it)

Prerequisite (met): the MCP_HOST_ENV_PASSTHROUGH change (#1453) is merged and dev is
merged into this branch, so the three variables set on the WRC Deployment reach recipe
mcp-host pods.

Stage 1 — local Minikube T2 (see AGENTS.md and docs/testing/minikube-t2-runbook.md;
host terminal, owned branch profile):

1. make minikube-t2-preflight MINIKUBE_PROFILE=<owned-profile>
2. make minikube-t2 MINIKUBE_PROFILE=<owned-profile> and keep the exact-head T2 verdict.
3. With the profile on this HEAD, run the matrix below.

Stage 2 — dev cluster: repeat the matrix once Stage 1 is accepted.

Matrix. Two recipes: (a) a code-review recipe whose agentic step reads files and diffs
through MCP tools; (b) a recipe that reads one document of about 100 KiB and summarizes it.
Three configurations, set as environment on the WRC Deployment (new runs pick them up):

Configuration	CLERUM_WORKFLOW_TOOL_SPILLOVER_ENABLED	CLERUM_WORKFLOW_TOOL_SPILLOVER_THRESHOLD
off	false	—
128 KiB (default)	unset	unset
32 KiB	unset	32768

Runs: for (a), three inputs (small, medium and large change), five runs each per configuration
in the dev cluster and two each on Minikube; for (b), five and two.

Record per run:

• step outcome, and whether it hit the iteration limit (Step reached max iterations);
• iterations used (iteration in the LLM call started log);
• input and output tokens (LLM response received log, or tokensUsed in the step result);
• step duration;
• results persisted and read back (clerum_workflow_step_spillover_persisted_total,
  clerum_workflow_step_spillover_reads_total, or the step logs);
• status report size (bodyBytes in the coordinator logs, when available);
• output quality: for (a), findings about large files are still present; for (b), the summary
  covers the end of the document;
• during and after the step: no .spill entry under <output dir>, and no log line with result content.

Accept the default with a given threshold when all hold:

1. success rate is not lower than with spillover off, for every input;
2. no run hits the iteration limit that did not hit it with spillover off;
3. median input tokens are at most 10% above "off" for the small and medium inputs, and below
   "off" for the large one;
4. for (b), summary quality does not get worse;
5. nothing is written to disk and no log contains result content.

If 128 KiB fails and 32 KiB passes, the default becomes 32768. If neither passes, the default
goes back to false.

Testing

• npm test passes for changed services
• npx tsc --noEmit clean

Run on Node 24.22.1 at e9a30777a:

• npm run typecheck (mcp-host): pass. eslint and prettier --check on the changed files:
  clean.
• Spillover suites: 11 files, 143 tests, pass. stepSpillover.test.ts (40),
  stepSpilloverInMemory.test.ts (12), workflowServiceSpillover.test.ts (16),
  artifactOutput.test.ts (26), spilloverRead.test.ts (8), toolUseLoop.spillover.test.ts
  (7), core/spillover (5 files, 34).
• Full npm test (mcp-host): 609 files, 9115 passed, 1 skipped, 1 todo.
• mcp-host/src/core/spillover, artifactOutput.ts and its test are identical to the
  merge-base with dev (git diff --quiet 1b1b1131e).
• Mutations, each removing one behaviour (results not dropped, release not called, result
  written to disk, one store for all executions, summary drift, call id not checked,
  first-party read counter default, step read counter, default threshold back to 32 KiB,
  spillover off by default against the 100 KiB inline test): all caught.
• scripts/minikube/t0.sh: T0_AFFECTED_PACKAGES=mcp-host, T0_AFFECTED_CHECKS=PASS,
  exit 0.

Checklist

• This is not a new third-party MCP server / WorkflowRecipe (those go to the registry)

---

Generated by Claude Code