Skip to content

Self-improving AI Employees for everyone

fix(agent): cap tool results and bound the agent transcript

trohitg45841021c83b
diff --git a/.env.template b/.env.template
index d57324ce..e4dd03df 100644
--- a/.env.template
+++ b/.env.template
@@ -183,16 +183,25 @@ TEMPORAL_WORKER_RESTART_BACKOFF_MAX_SECONDS=30.0
# the legacy event_waiter path -- see docs-internal/event_framework.md.
EVENT_FRAMEWORK_ENABLED=true
-# Memory compaction. ``true`` (default) auto-compacts agent
-# conversation memory when cumulative tokens exceed the model's
-# context-window threshold. Per-session overrides via the UI.
+# Memory compaction. ``true`` (default) auto-compacts an agent's
+# conversation when it nears the model's context-window threshold (see
+# COMPACTION_RATIO). Per-session overrides via the UI.
COMPACTION_ENABLED=true
# Compaction trigger threshold as a fraction of the model's context
-# window (0.05 - 0.99). 0.8 = compact when cumulative tokens hit 80%.
+# window (0.05 - 0.99). 0.8 = compact at 80%: AgentWorkflow measures the
+# size of its next request, the in-process path the run's summed usage.
# Per-user overrides via the UserSettings row (Settings tab).
COMPACTION_RATIO=0.8
+# Largest result (in characters) one external tool call may add to an
+# agent's conversation. Longer results are cut, with a note telling the
+# model to call the tool again with narrower parameters; only the model's
+# copy is cut, never the tool's own result. Delegated-agent answers, skill
+# loads and Task Manager results are never cut. 0 disables the cap.
+# Per-user overrides via the UserSettings row (Settings tab).
+TOOL_RESULT_MAX_CHARS=100000
+
# Agent loop hard step cap. AI Agent + Chat Agent stop the LLM/tool
# iteration loop after this many rounds and return a truncation note.
# Per-user overrides via the UserSettings row (Settings tab).
diff --git a/CLAUDE.md b/CLAUDE.md
index c68f2d16..2b5375a8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,7 +22,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Agent Architecture](./docs-internal/agent_architecture.md)** | How AI Agent and Chat Agent discover skills/tools, inject them into LLM prompts, and execute through the provider-neutral `run_native_agent_loop` |
| **[Agent Delegation](./docs-internal/agent_delegation.md)** | How memory, parameters, and execution context flow when one AI agent delegates work to another agent connected as a tool |
| **[Agent Teams](./docs-internal/agent_teams.md)** | Claude SDK Agent Teams pattern - AI Employee and Orchestrator nodes with input-teammates handle for multi-agent coordination |
-| **[Agent Context Flow](./docs-internal/agent_context_flow.md)** | Normative continuity reference — how a conversation survives firings, delegations, and rollovers on both paths. Plain conversation store: one `agent_conversations` row per `(workflow_id, generation, agent_node_id)` → messages JSON, loaded at run start and saved per turn (LangGraph thread_id / OpenAI conversation_id pattern; the journal/thread/epoch machinery is gone). Seeding precedence (carried rollover transcript > stored conversation > bare build, 1 MB guards), LOUD load failures (`ConversationLoadFailed` / `ConversationTooLarge`) vs best-effort saves, the specialized-provider bridge, and the August 2026 "lead forgot its plan" regression. Read before touching `services/agent_context/`, `nodes/context/`, `services/cli_agent/context_bridge.py`, `agent.prepare_payload`, or the team-completion event chain. |
+| **[Agent Context Flow](./docs-internal/agent_context_flow.md)** | Normative continuity reference — how a conversation survives firings, delegations, and rollovers on both paths. Plain conversation store: one `agent_conversations` row per `(workflow_id, generation, agent_node_id)` → messages JSON, loaded at run start and saved per turn (LangGraph thread_id / OpenAI conversation_id pattern; the journal/thread/epoch machinery is gone). Seeding precedence (carried rollover transcript > stored conversation > bare build, 1 MB guards), LOUD load failures (`ConversationLoadFailed` / `ConversationTooLarge`) vs best-effort saves, transcript size bounds (per-call tool-result cap, byte budget that clears old results, `context_pressure_version` replay contract), the specialized-provider bridge, and the August 2026 "lead forgot its plan" regression. Read before touching `services/agent_context/`, `nodes/context/`, `services/cli_agent/context_bridge.py`, `services/tool_output.py`, `agent.prepare_payload`, or the team-completion event chain. |
| **[Memory Compaction](./docs-internal/memory_compaction.md)** | Native usage aggregation plus shared client-side summarization through `ChatUnifier` for memory-connected agents. Threshold = `Settings.compaction_ratio` (env `COMPACTION_RATIO`, default 0.8) × model context length; see the document for the per-session override limitation on Temporal runs. |
| **[Pricing Service](./docs-internal/pricing_service.md)** | Centralized cost tracking for LLM tokens and API services (Twitter, Google Maps) with HTTPX event hooks |
| **[Proxy Service](./docs-internal/proxy_service.md)** | Residential proxy provider management with template-based URL formatting, health scoring, and transparent HTTP node injection |
@@ -1386,7 +1386,9 @@ Both paths implement the same contract: Temporal via `prepare_agent_payload` (lo
**The store also stamps timestamps.** `save_conversation` attaches a `ts` (UTC ISO) to every stored message: callers regenerate wires from live `Message` objects each turn, so the store keeps the original stamp for the unchanged prefix and stamps only the appended turn — a message's time is when it first persisted, not when the conversation last saved. `ts` is a stored-view field only; `message_from_wire` ignores it, so it never reaches a provider on any path.
-**Compaction never touches the system prompt, and its summary rides a USER message.** The AgentWorkflow's threshold compaction swaps `messages` for `[original system (verbatim), user(summary + current request)]`. The system prompt is the agent's byte-stable contract (prompt caching, behavioral consistency), and the seeding filter drops stored system messages — so a summary stored under the system role (the earlier design) silently vanished on the next firing while the noisy tool tail survived it. Prior tool calls/results are dropped at the swap and live only inside the summary; tool messages after the summary in the panel are new post-compaction work (their `ts` postdates it). Trigger, swap (before→after counts), and summarizer usage all log at INFO. Locked in `tests/temporal/test_agent_workflow.py`. See [agent_context_flow.md → Compaction](./docs-internal/agent_context_flow.md).
+**Compaction never touches the system prompt, and its summary rides a USER message.** The AgentWorkflow's threshold compaction swaps `messages` for `[original system (verbatim), user(summary + current request)]`, followed by the latest turn verbatim on runs recorded with `context_pressure_version` 1 (its tool results are still unread). The system prompt is the agent's byte-stable contract (prompt caching, behavioral consistency), and the seeding filter drops stored system messages — so a summary stored under the system role (the earlier design) silently vanished on the next firing while the noisy tool tail survived it. Tool calls/results of the summarized turns are dropped at the swap and live only inside the summary; tool messages after the summary in the panel are the kept latest turn or new post-compaction work. Trigger, swap (before→after counts), and summarizer usage all log at INFO; a summarizer failure after the activity's retries fails the run (`CompactionError`), it is not best-effort. Locked in `tests/temporal/test_agent_workflow.py` and `tests/temporal/test_agent_workflow_pressure.py`. See [agent_context_flow.md → Compaction](./docs-internal/agent_context_flow.md).
+
+**The transcript is bounded in bytes, not only in tokens** (`docs-internal/errors.md` #28: uncapped TikHub results grew a saved row past the 1 MB seed cap, and every later firing failed with `ConversationTooLarge`). Each external tool result is cut to `tool_result_max_chars` characters (per-user Settings > Tool Result Limit, else env `TOOL_RESULT_MAX_CHARS`, default 100,000; delegated-agent answers, skill loads and Task Manager are exempt) by `server/services/tool_output.py`, on both paths. On Temporal, `agent.prepare_payload` records `tool_result_max_chars`, `transcript_budget_bytes` (three quarters of `TEMPORAL_PAYLOAD_WARN_BYTES`) and `context_pressure_version`; after each tool turn over the budget the workflow clears earlier turns' results to a placeholder (oldest and external first), gates summarization on the NEXT request (the last step's `total_tokens` plus the turn's added characters, never a running sum of every step), summarizes only earlier turns, and cuts an overflowing latest turn to fit (`server/services/temporal/agent_context_pressure.py`). The recorded version selects these rules on replay: a history recorded without it replays the original cumulative gate, so any change to the rules needs a new version. See [agent_context_flow.md → Transcript size](./docs-internal/agent_context_flow.md).
**Memory** (node type `simpleMemory`, displayed as **"Memory"** — the wire type is stored verbatim in graphs/pool keys and must not be renamed; plugin `server/nodes/tool/simple_memory/`) is a `ToolNode` on `input-tools` — durable facts the agent explicitly remembers, recalls, updates and forgets. It is not conversation history and has no markdown surface; `SimpleMemoryParams` declares only `reset_policy` (with `extra="ignore"`, so leftover legacy keys on migrated graphs are inert). `reset_policy` is in `server_controlled_fields`, which stops the **model** overriding it through tool arguments — it does not stop the operator editing it. Two model-facing contracts are load-bearing: (1) the `tool_description` ClassVar is imperative — *check memory (recall/list) before answering anything about the user; never claim ignorance without checking* — because with a passive "store and retrieve when useful" wording, models answered "I don't know who you are" from priors while the user's name sat one recall away (`tool_schema_locked = True` pins this description against stale ToolSchema rows). (2) Every durable mutation (remember/update/forget/clear, from the agent tool call or the panel) broadcasts the identity-only `memory.updated` CloudEvent ([`_events.py`](./server/nodes/tool/simple_memory/_events.py), same direct-broadcast rationale as `context.updated`), which `WebSocketContext.tsx` routes to invalidate the `memoryItems`/`memoryItem` queries.
diff --git a/client/src/components/ui/SettingsPanel.tsx b/client/src/components/ui/SettingsPanel.tsx
index 3a092041..9661bc56 100644
--- a/client/src/components/ui/SettingsPanel.tsx
+++ b/client/src/components/ui/SettingsPanel.tsx
@@ -30,6 +30,7 @@ import {
defaultSettings,
fromServerRow,
toServerRow,
+ TOOL_RESULT_MAX_CHARS_RANGE,
type WorkflowSettings,
} from './settingsPanel/schema';
@@ -58,6 +59,9 @@ const TONE_CLASSES: Record<SectionTone, string> = {
tool: 'bg-node-tool-soft text-node-tool',
};
+/** The Tool Result Limit slider shows and edits characters in thousands. */
+const toThousands = (chars: number): number => Math.round(chars / 1000);
+
interface SectionProps {
title: string;
Icon: React.ElementType;
@@ -355,6 +359,44 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({
<div className="my-1 border-b border-border-default" />
+ <div className="py-2">
+ <div className="mb-2 flex items-center justify-between">
+ <div className="flex-1">
+ <div className="text-sm font-medium text-fg-default">Tool Result Limit</div>
+ <div className="mt-0.5 text-xs text-fg-muted">
+ Most characters one tool call can add to an agent's conversation
+ </div>
+ </div>
+ <span className="min-w-[42px] text-right text-sm font-semibold text-node-model">
+ {toThousands(settings.toolResultMaxChars)}K
+ </span>
+ </div>
+ <Slider
+ min={toThousands(TOOL_RESULT_MAX_CHARS_RANGE.min)}
+ max={toThousands(TOOL_RESULT_MAX_CHARS_RANGE.max)}
+ step={toThousands(TOOL_RESULT_MAX_CHARS_RANGE.step)}
+ value={[toThousands(settings.toolResultMaxChars)]}
+ onValueChange={(value) =>
+ handleChange(
+ 'toolResultMaxChars',
+ value[0] === undefined ? defaultSettings.toolResultMaxChars : value[0] * 1000,
+ )
+ }
+ disabled={isSaving}
+ className="my-3"
+ />
+ <div className="flex justify-between text-[10px] text-fg-muted">
+ <span>{toThousands(TOOL_RESULT_MAX_CHARS_RANGE.min)}K</span>
+ <span>{toThousands(defaultSettings.toolResultMaxChars)}K</span>
+ <span>{toThousands(TOOL_RESULT_MAX_CHARS_RANGE.max)}K</span>
+ </div>
+ <div className="mt-1 text-xs leading-snug text-fg-muted">
+ Longer results are cut before the agent reads them, with a note asking it to narrow the request. Answers from delegated agents, skills and Task Manager are never cut.
+ </div>
+ </div>
+
+ <div className="my-1 border-b border-border-default" />
+
<Row
label="AI Agent Max Steps"
description="Hard cap on the agent loop's LLM-iteration count per run. The token-based compaction threshold is usually the real termination signal; this is the safety backstop."
diff --git a/client/src/components/ui/settingsPanel/schema.test.ts b/client/src/components/ui/settingsPanel/schema.test.ts
new file mode 100644
index 00000000..10eb3ec8
--- /dev/null
+++ b/client/src/components/ui/settingsPanel/schema.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import {
+ TOOL_RESULT_MAX_CHARS_RANGE,
+ defaultSettings,
+ fromServerRow,
+ toServerRow,
+ workflowSettingsSchema,
+} from './schema';
+
+describe('workflow settings schema', () => {
+ it('round-trips every setting through the server row', () => {
+ const settings = {
+ ...defaultSettings,
+ compactionRatio: 0.6,
+ agentRecursionLimit: 300,
+ toolResultMaxChars: 50_000,
+ };
+
+ expect(fromServerRow(toServerRow(settings))).toEqual(settings);
+ });
+
+ it('maps the tool result limit to the snake_case server key', () => {
+ expect(toServerRow({ ...defaultSettings, toolResultMaxChars: 20_000 }).tool_result_max_chars).toBe(20_000);
+ expect(fromServerRow({ tool_result_max_chars: 150_000 }).toolResultMaxChars).toBe(150_000);
+ });
+
+ it('defaults the tool result limit for a row saved before it existed', () => {
+ expect(fromServerRow({ compaction_ratio: 0.5 }).toolResultMaxChars).toBe(defaultSettings.toolResultMaxChars);
+ });
+
+ it('rejects a tool result limit outside the slider range', () => {
+ const { min, max } = TOOL_RESULT_MAX_CHARS_RANGE;
+
+ for (const toolResultMaxChars of [min - 1, max + 1, 15_000.5]) {
+ expect(workflowSettingsSchema.safeParse({ toolResultMaxChars }).success).toBe(false);
+ }
+ });
+
+ it('puts the default on the slider grid', () => {
+ const { min, max, step } = TOOL_RESULT_MAX_CHARS_RANGE;
+ const value = defaultSettings.toolResultMaxChars;
+
+ expect(value).toBeGreaterThanOrEqual(min);
+ expect(value).toBeLessThanOrEqual(max);
+ expect((value - min) % step).toBe(0);
+ });
+});
diff --git a/client/src/components/ui/settingsPanel/schema.ts b/client/src/components/ui/settingsPanel/schema.ts
index 6eb2801a..a9931bb2 100644
--- a/client/src/components/ui/settingsPanel/schema.ts
+++ b/client/src/components/ui/settingsPanel/schema.ts
@@ -10,6 +10,12 @@
import { z } from 'zod';
+/**
+ * Tool Result Limit range in characters, shared by the schema below and the
+ * Settings slider so validation and the control cannot drift apart.
+ */
+export const TOOL_RESULT_MAX_CHARS_RANGE = { min: 10_000, max: 200_000, step: 10_000 } as const;
+
export const workflowSettingsSchema = z.object({
autoSave: z.boolean().default(true),
autoSaveInterval: z.number().int().min(10).max(300).default(30),
@@ -19,6 +25,13 @@ export const workflowSettingsSchema = z.object({
memoryWindowSize: z.number().int().min(1).max(100).default(100),
compactionRatio: z.number().min(0.05).max(0.99).default(0.8),
agentRecursionLimit: z.number().int().min(1).max(5000).default(200),
+ // Mirrors the server's TOOL_RESULT_MAX_CHARS default.
+ toolResultMaxChars: z
+ .number()
+ .int()
+ .min(TOOL_RESULT_MAX_CHARS_RANGE.min)
+ .max(TOOL_RESULT_MAX_CHARS_RANGE.max)
+ .default(100_000),
maxProcesses: z.number().int().min(1).max(50).default(10),
autoAddSkillForTools: z.boolean().default(true),
autoRebindToolsAfterCanvasChange: z.boolean().default(true),
@@ -46,6 +59,7 @@ export function fromServerRow(row: Record<string, any> | null | undefined): Work
autoAddSkillForTools: row.auto_add_skill_for_tools,
autoRebindToolsAfterCanvasChange: row.auto_rebind_tools_after_canvas_change,
agentRecursionLimit: row.agent_recursion_limit,
+ toolResultMaxChars: row.tool_result_max_chars,
});
}
@@ -66,5 +80,6 @@ export function toServerRow(s: WorkflowSettings): Record<string, any> {
auto_add_skill_for_tools: s.autoAddSkillForTools,
auto_rebind_tools_after_canvas_change: s.autoRebindToolsAfterCanvasChange,
agent_recursion_limit: s.agentRecursionLimit,
+ tool_result_max_chars: s.toolResultMaxChars,
};
}
diff --git a/docs-internal/ARCHIVE/AGENT_COMPACTION_FIX_PLAN.md b/docs-internal/ARCHIVE/AGENT_COMPACTION_FIX_PLAN.md
new file mode 100644
index 00000000..87b25fa0
--- /dev/null
+++ b/docs-internal/ARCHIVE/AGENT_COMPACTION_FIX_PLAN.md
@@ -0,0 +1,91 @@
+# Fix: agent transcripts outgrow compaction and brick the next firing
+
+> **ARCHIVED 2026-09-24 — Shipped** (branch `fix/agent-compaction-pressure`, merged to main). The approved plan plus an as-built record, including where the implementation departed from the plan. Not maintained.
+>
+> For current state see:
+>
+> - [agent_context_flow.md → Transcript size](../agent_context_flow.md): the rules and the replay contract.
+> - [errors.md entry 28](../errors.md): the incident, the fix, and the one-time recovery for rows saved before it.
+
+## Context
+
+`errors.log` (2026-09-05) records one deployed chat workflow, `AI_Assistant_1`: an `aiAgent` on gemini-3.8-flash with writeTodos, simpleMemory and tikhubAction. Each tikhubAction call appended its whole upstream response (roughly 400,000 characters) to the transcript. The `agent.execute_llm_step` input reached 528 KB at iteration 5 and 1.4 MB from iteration 6 on, with a Temporal `PayloadSizeWarning` every turn. Compaction never fired, because its only trigger is 80% of a 1,048,576-token window, compared with a running sum. The 1.4 MB transcript was saved to `agent_conversations`, and the next chat message failed in `agent.prepare_payload` with non-retryable `ConversationTooLarge` (1,429,978 bytes against a 1,000,000 cap). Every later firing failed the same way until the user cleared the Context panel.
+
+## Decisions
+
+Confirmed by the user 2026-09-09:
+1. `ConversationTooLarge` stays a hard, non-retryable failure; the fix prevents new transcripts from reaching it.
+2. The tool-result cap is per-user through a Settings slider, with an env fallback.
+3. The wire dedupe (every tool message stores its text twice) is deferred to its own change.
+4. Compaction's token gate measures the live context, not a cumulative sum.
+
+Approved with the plan on 2026-09-24:
+5. **Byte pressure clears the oldest tool results rather than summarizing the turn the model has not read.** Clearing is free, cannot fail, and is the pattern of Anthropic's context editing (`clear_tool_uses`) and Claude Code's micro-compaction. The summarizer keeps the latest turn verbatim.
+6. **New behavior is gated on values recorded in the `agent.prepare_payload` result, not on a `workflow.patched` marker.** Histories recorded before the change carry none of the new keys and replay through the original code (the technique `capture_temporal_routing_input` uses to freeze routing flags).
+7. **Default cap 100,000 characters, external tools only**, matching the shell and browser output caps. Exempt: delegated agents (`AI_AGENT_TYPES`), `_builtin_skill`, `taskManager`, `_builtin_check_delegated_tasks`.
+
+## Root causes
+
+1. Nothing bounded a tool result before it entered the transcript: the workflow appended `_serialise_tool_result(tool_result)` whole, the in-process loop `json.dumps(result)` whole.
+2. Every tool message is stored twice (`content` plus a default `tool_result` block). Deferred (decision 3).
+3. The token gate compared a running sum of every step's usage (`context_usage_total`) with the threshold, and never looked at bytes.
+4. The seed guard's comment said the run degrades with a warning; the code raises. `save_conversation` had no size check.
+5. `_serialise_tool_result` is shared with the delegation brief and the child's answer text, so the cap could not live inside it.
+
+## As built
+
+**Phase 1, cap external tool results (both paths).**
+- `server/services/tool_output.py`: `bound_tool_output(text, limit)` keeps the first `limit` characters and appends `[Tool result truncated: showing the first N of M characters. Call the tool again with narrower parameters to see the rest.]`. Re-bounding keeps the original M. `tool_output_is_capped(node_type)` exempts decision 7's list. `resolve_tool_output_limit(user_settings, settings)` applies per-user `tool_result_max_chars` > `Settings.tool_result_max_chars`, with the `agent_recursion_limit` guard (a positive int).
+- Settings: `Settings.tool_result_max_chars` (env `TOOL_RESULT_MAX_CHARS`, default 100,000, `0` disables), `.env.template`, `UserSettings.tool_result_max_chars`, a migration whose column default is read from the model field, and the hand-written `Database.get_user_settings` dict.
+- Temporal: `prepare_agent_payload` records `tool_result_max_chars`; `AgentWorkflow.run` bounds `tool_content` right after `_serialise_tool_result` for capped, non-delegation calls.
+- In-process: `run_native_agent_loop(..., tool_output_limit=None)` bounds the serialized result; image blocks are read from the untouched result, so `llm_media` refs survive. `AIService.execute_agent` and `execute_chat_agent` resolve and pass the limit.
+- Client: `toolResultMaxChars` in `client/src/components/ui/settingsPanel/schema.ts` (range in the shared `TOOL_RESULT_MAX_CHARS_RANGE`), and a "Tool Result Limit" slider (10K to 200K, step 10K) in the Memory & Compaction section of `SettingsPanel.tsx`.
+
+**Phase 2, transcript pressure in `AgentWorkflow` (runs recorded with `context_pressure_version` 1).**
+- `prepare_agent_payload` also records `transcript_budget_bytes` (three quarters of `TEMPORAL_PAYLOAD_WARN_BYTES`, derived in `transcript_budget_bytes()`) and `context_pressure_version`.
+- `server/services/temporal/agent_context_pressure.py` (pure, workflow-safe). After each tool turn:
+ 1. `clear_old_tool_results`: over the budget, results from earlier turns become a placeholder, oldest first, external before agent-internal, down to half the budget. `tool_call_id` and `name` survive; the wire is rebuilt so the duplicated block goes too.
+ 2. Summarize when `projected_request_tokens` (the step's `total_tokens`, plus the turn's added characters net of what was cleared, at four per token) reaches the threshold, or when `earlier_turns_over_budget` (still over budget with the earlier turns holding more than half of it). Only the turns before the latest are summarized (`summarizer_view`), and the swap is `[system, user(summary + current request), latest turn verbatim]`. With nothing older than the latest turn (`has_summarizable_history`), it skips.
+ 3. `clip_latest_turn`: if the latest turn alone still overflows, its external results are cut to one shared length found by bisection on the exact serialized size, never below 2,000 characters.
+- Without the key, the original cumulative gate and whole-transcript swap run unchanged.
+
+**Phase 3, seed guard.** Comment rewritten to describe the raise. The message now reads "Clear the conversation from the Context panel, then run again. Settings > Tool Result Limit caps how much one tool call can add to it." `_save_conversation` logs a WARNING over half of `_SEED_TRANSCRIPT_MAX_BYTES`. `prepare_agent_payload` logs a WARNING instead of silently dropping the threshold when it cannot be computed.
+
+**Phase 4, docs.** `errors.md` entry 28; `agent_context_flow.md` (new "Transcript size" section, compaction rewrite, invariant 10); `memory_compaction.md`; `TEMPORAL_ARCHITECTURE.md` (the loop pseudo-code, the `agent.prepare_payload` and `agent.compact_context` rows: compaction failure is terminal, not best-effort); `data_node.md`; `CLAUDE.md`; `.env.template`.
+
+## Differences from the approved plan, and why
+
+- **Module location.** `server/services/tool_output.py`, not under `services/llm/` as planned: importing anything there runs that package's `__init__`, which reads `llm_defaults.json` from disk. The new module needs only `constants` and the standard library, so workflow code imports it at module level like `get_node_class`.
+- **Truncation note.** The approved text said "The full result is in this tool's node output panel". That is false for tools that hide their Output section (`simpleMemory`, `dataSource`, `visionAnalyze`, `processManager`) and only true for a tool's latest call, so the note only tells the model how to get the rest.
+- **Order: clear, then summarize, then clip.** The plan clipped the latest turn inside the clearing step, before any summary; that could cut unread results to fit a history the summary was about to replace. Clipping now runs last, against the room that remains.
+- **Byte-forced summary.** The plan summarized for token pressure only. A transcript whose bulk is text (long user or assistant messages) cannot be brought under budget by clearing tool results, so it also summarizes when the earlier turns alone keep it over budget, but not when the latest turn is the excess (clipping handles that without a paid call).
+- **Token arithmetic.** Checked per provider: every provider's `total_tokens` is the whole prompt, cache reads and writes included, plus output (Anthropic adds the cache counters itself; OpenAI and Gemini already count them in input). The gate uses the step's `total_tokens`; no provider change was needed.
+- **Settings getter.** `Database.get_user_settings` builds its dict by hand, so it needed the new key (the plan said no edit); `server/tests/test_user_settings_contract.py` enforces it.
+
+## Tests
+
+- `server/tests/services/test_tool_output.py`: bounding and re-bounding, the note, exemptions, limit precedence, and one test that keeps the four copies of the default (`.env.template`, `Settings`, `UserSettings`, client schema) equal.
+- `server/tests/temporal/test_agent_context_pressure.py`: clearing order and target, pairing, clipping to one length, the minimum length, token arithmetic, summarizer view.
+- `server/tests/temporal/test_agent_workflow_pressure.py`: `AgentWorkflow.run` end to end with scripted activities: cap and exemptions, legacy histories untouched, clearing across turns, clipping a single overflowing turn, the next-request gate against the legacy running sum, the kept latest turn, byte-forced summary, compaction off.
+- `server/tests/temporal/test_prepare_payload_pressure.py`: the recorded keys and precedence, the seed guard at and over the cap, the threshold warning, the save warning.
+- `server/tests/temporal/test_agent_workflow.py`: `TestTranscriptPressureReplaySafety` source guards.
+- `server/tests/services/test_native_agent_runtime.py`: in-process cap, `llm_media` survival, skill exemption, no limit.
+- `client/src/components/ui/settingsPanel/schema.test.ts`: round trip, mapping, default for old rows, range.
+
+## Verification
+
+```
+cd server && uv run pytest tests/ -q
+bun run typecheck
+bun --cwd=client run test
+```
+
+End to end, for the user to run (it needs the real app and data directory): clear the oversized conversation once from the Context panel, run the tikhub prompt that caused the incident, and expect no `PayloadSizeWarning`, tool messages ending with the truncation note, an INFO line when old results are cleared, and a second chat message that runs.
+
+## Deferred and found along the way
+
+- Wire dedupe (decision 3).
+- Pressure relief on the in-process path, which gets only the cap. `CompactionService.track()` also sums every request's `total_tokens` across a session, the same running-sum problem the workflow had.
+- Chunked summarization for models whose window is smaller than the budget.
+- From reading `services/pricing.py` and `config/pricing.json` (not exercised by a test): pricing assumes Anthropic's usage semantics for every provider: OpenAI and OpenAI-compatible cached tokens are charged at the input rate and again at the cache rate, o4-mini reasoning tokens are charged twice, and Gemini thinking tokens are never charged. Separate billing change.
+- Not verified: `BaseNode.execute_as_tool` may hand the model `{"result": None}` for Task Manager calls whose payload has `success` but no `result` key.
diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.md
index 014bb739..ac655fde 100644
--- a/docs-internal/TEMPORAL_ARCHITECTURE.md
+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md
@@ -383,7 +383,10 @@ AgentWorkflow.run(context):
_serialise_tool_result unwraps F4.A's {success, result, ...}
envelope so the LLM sees only the handler's return value
(matches the in-process tool-call serialisation in
- services/agent_runtime.py:run_native_agent_loop).
+ services/agent_runtime.py:run_native_agent_loop), then an
+ external tool's text is cut to payload["tool_result_max_chars"]
+ (services/tool_output.py; delegations, skill loads and Task
+ Manager are never cut).
4. for each tool result with an ``operations`` field
(canvas-mutating tools — today only ``agentBuilder``):
if payload["auto_rebind_tools"] is True:
@@ -400,10 +403,19 @@ AgentWorkflow.run(context):
append_to_memory_markdown(content, "human", prompt) +
(content, "ai", response); trim window; broadcast
node_parameters_updated CloudEvents (source_hint="agent").
- 6. if token_total >= compaction_threshold:
- execute_activity("agent.compact_context")
- null-guarded against worker-bootstrap race; replaces messages
- with summary only when result.success is True.
+ 6. transcript pressure, rules picked by the recorded
+ payload["context_pressure_version"] (agent_context_pressure.py):
+ version 1: clear earlier turns' tool results past
+ payload["transcript_budget_bytes"]; if the next request reaches
+ compaction_threshold, or the earlier turns alone keep the
+ transcript over budget, execute_activity("agent.compact_context")
+ on the earlier turns only and keep the latest turn verbatim;
+ then cut the latest turn's external results to fit.
+ no version (histories recorded before it): if the running sum of
+ every step's tokens >= compaction_threshold, summarize the
+ whole transcript.
+ A summarizer failure after the activity's retries ends the run
+ with error_type="CompactionError".
execute_activity("agent.store_output")
wraps workflow_service.store_node_output for output_main /
output_top / output_0 — same writes NodeExecutor.execute does
@@ -438,11 +450,11 @@ addition. Seven are the core loop activities:
| Activity | Purpose |
|---|---|
-| `agent.prepare_payload` | Resolves the DB-backed payload (provider / model / system_message / user_prompt / `AgentToolSpec`-derived tool definitions / memory_node_id / memory_content / memory_window_size / max_iterations / thinking_config / compaction_threshold / auto_rebind_tools), and leaves credential resolution at the LLM activity boundary. Reads `UserSettings.agent_recursion_limit` + `UserSettings.auto_rebind_tools_after_canvas_change`. Applies the optional `invocation` field (delegation children) after config resolution — per-invocation input always beats stored parameters. |
+| `agent.prepare_payload` | Resolves the DB-backed payload (provider / model / system_message / user_prompt / `AgentToolSpec`-derived tool definitions / memory_node_id / memory_content / memory_window_size / max_iterations / thinking_config / compaction_threshold / tool_result_max_chars / transcript_budget_bytes / context_pressure_version / auto_rebind_tools), and leaves credential resolution at the LLM activity boundary. Reads `UserSettings.agent_recursion_limit`, `auto_rebind_tools_after_canvas_change`, `tool_result_max_chars`, `max_concurrent_subagents` and `max_delegation_depth`. Recording the three transcript-pressure keys here is what lets a history recorded before them replay the original rules. Applies the optional `invocation` field (delegation children) after config resolution — per-invocation input always beats stored parameters. |
| `agent.execute_llm_step` | One LLM turn. The native branch decodes Message Wire V2, rebuilds `ToolDef` values, calls `run_native_llm_step(ChatUnifier, ...)` with SDK retries disabled, heartbeats while awaiting the provider, and returns the exact assistant message + tool calls + normalized usage. Guards against un-invokable payloads: post-filter system-only message lists raise `ApplicationError(type="EmptyAgentPrompt", non_retryable=True)`. |
| `agent.refresh_tools` | Translates `workflow_ops` add_node ops (`component_kind="tool"` OR `usable_as_tool=True`) into fresh `AgentToolSpec`-derived `tool_payload` entries via `_build_tool_from_node`. Workflow extends `tools` + `tool_index` from the result. |
| `agent.persist_turn` | Appends the latest human/assistant exchange to memory markdown, trims the window, broadcasts `node.parameters.updated`. |
-| `agent.compact_context` | Context-pressure compaction when cumulative active-context tokens hit the threshold (the shared client-side summarizer). Best-effort: continues with un-compacted history on failure; it is not an agent termination control. |
+| `agent.compact_context` | The shared client-side summarizer, run under transcript pressure (step 6 above). Not best-effort: after the activity's retries a failure ends the run with `CompactionError`, because past that point the transcript could only grow until the provider rejected it. |
| `agent.store_output` | Writes `output_main` / `output_top` / `output_0` so downstream nodes resolve `{{aiAgent.response}}` via `ParameterResolver`. |
| `agent.broadcast_progress` | Emits `WorkflowEvent.agent_progress` (CloudEvents v1.0) + optional raw-dict `update_node_status` for canvas-glow color. Single helper drives every phase emit. |
@@ -479,9 +491,12 @@ in the per-type activity payload so ToolNodes validate against their
`ToolInput` via `execute_as_tool` (see `tests/nodes/test_tool_call_dispatch.py`).
The F4.B compaction threshold is prepared from the model context length and
-the ratio configuration. It currently does not read
-`SessionTokenState.custom_threshold` or `compaction_enabled`; those stored
-per-session controls are therefore not authoritative for this path.
+the ratio configuration, and is absent when the global `COMPACTION_ENABLED`
+is off. It does not read `SessionTokenState.custom_threshold` or the
+per-session `compaction_enabled`; those stored per-session controls are
+therefore not authoritative for this path. The transcript's byte budget and
+the tool-result cap apply whether or not compaction is on (see
+[agent_context_flow.md → Transcript size](./agent_context_flow.md)).
**Broadcasts inside the loop** wrap `WorkflowEvent` (CloudEvents v1.0) per RFC §6.4: `agent_progress` events (`com.opencompany.agent.progress`) and `node_parameters_updated` events (`com.opencompany.node.parameters.updated`) flow through the `StatusBroadcaster.broadcast_agent_progress` and `StatusBroadcaster.broadcast_node_parameters_updated` wrappers respectively. The latter is reused by the legacy `routers/websocket.py:handle_save_node_parameters` (user-source) and `services/cli_agent/service.py:_persist_memory` (cli-source) — all three emission sites share the same envelope, distinguished by `source_hint` (`"user"` / `"cli"` / `"agent"`).
diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.md
index 6eb8dd67..356878c6 100644
--- a/docs-internal/agent_architecture.md
+++ b/docs-internal/agent_architecture.md
@@ -190,10 +190,12 @@ Resolved per-execution, and the two runtimes differ. **Temporal** (`prepare_agen
4. **JSON** `llm_defaults.json:agent.recursion_limit` — in-process only, reached when `Settings` cannot instantiate; the Temporal path uses a hardcoded 200 instead.
The iteration limit is the termination backstop. Compaction is a post-turn
-context-pressure control for agents with connected memory; it summarizes active
-history so a loop can continue within the model's context window, but it does
-not decide when the loop terminates. See
-[memory_compaction.md](memory_compaction.md).
+context-pressure control (on the Temporal path for every agent, in-process for
+agents with connected memory); it summarizes active history so a loop can
+continue within the model's context window, but it does not decide when the
+loop terminates. Tool results are bounded separately, per call, by the Tool
+Result Limit. See [memory_compaction.md](memory_compaction.md) and
+[agent_context_flow.md → Transcript size](agent_context_flow.md).
### Hot rebind after canvas mutation
diff --git a/docs-internal/agent_context_flow.md b/docs-internal/agent_context_flow.md
index edc886d4..7fc02348 100644
--- a/docs-internal/agent_context_flow.md
+++ b/docs-internal/agent_context_flow.md
@@ -105,12 +105,52 @@ The carried transcript caps at ~1 MB serialized
2 MiB for the whole continue-as-new argument; over-cap degrades to the
opening prompt with a warning — never a failure.
+## Transcript size: capped results, cleared old results
+
+The transcript is the `agent.execute_llm_step` input on every turn and the
+row the next firing seeds from, so its size is bounded in bytes, not only in
+tokens (the failure this prevents is `errors.md` #28: uncapped tool results
+grew a saved row past the 1 MB seed cap and every later firing failed).
+
+- **Tool results are capped before they enter the transcript.** Each
+ external tool result is cut to `tool_result_max_chars` characters (per-user
+ Settings > Tool Result Limit, else env `TOOL_RESULT_MAX_CHARS`, default
+ 100,000) with a note telling the model to call the tool again with narrower
+ parameters (`services/tool_output.py`). Delegated agents' answers, skill
+ loads and Task Manager results are never cut. Both paths apply it: the
+ workflow right after `_serialise_tool_result`, the in-process loop in
+ `run_native_agent_loop`.
+- **Old results are cleared past a byte budget** (Temporal path).
+ `agent.prepare_payload` records `transcript_budget_bytes` (three quarters of
+ `TEMPORAL_PAYLOAD_WARN_BYTES`). After each tool turn over that budget,
+ results from earlier turns become a short placeholder, oldest first and
+ external tools first, down to half the budget. Each keeps its
+ `tool_call_id` and `name`, so every call still has its answer. The saved
+ conversation holds the placeholder too, and the store re-stamps that
+ message's `ts` when it changes. If the latest turn alone still overflows,
+ its external results are cut to one shared length
+ (`services/temporal/agent_context_pressure.py`).
+- **The rules are selected by the recorded payload.** `agent.prepare_payload`
+ also records `context_pressure_version` and `tool_result_max_chars`; a run
+ recorded before those keys existed replays the original rules (no cap,
+ cumulative token gate, whole-transcript summary), because the rules decide
+ which activities are scheduled. Any change to them needs a new version.
+
## Compaction: one system prompt, summary as a user message
-When the loop's token total crosses the threshold, `agent.compact_context`
-summarizes the live transcript and the workflow swaps `messages` for
-`[original system (verbatim), user("## Compacted conversation summary" +
-summary + current request)]`. Two rules are load-bearing (locked by
+Version 1 summarizes when the next request (the last request's
+`total_tokens`, which every provider fills with the whole prompt including
+cache reads, plus what the turn added) reaches the threshold, or when the
+earlier turns alone keep the transcript over its byte budget. It sends
+`agent.compact_context` only the turns before the latest one and swaps
+`messages` for `[original system (verbatim), user("## Compacted
+conversation summary" + summary + current request), latest turn verbatim]`:
+the latest turn's tool results have not been read yet, so summarizing them
+would lose what the model just asked for. With nothing older than the latest
+turn, it skips (a summary of the opening alone gains nothing). Runs recorded
+before version 1 keep the original rule: summarize everything when the
+running sum of every step's usage crosses the threshold. Two rules are
+load-bearing (locked by
`TestConversationIdentity::test_compaction_preserves_the_system_prompt_and_summary_survival`):
- **The system prompt is never modified or duplicated.** It is the agent's
@@ -124,26 +164,34 @@ summary + current request)]`. Two rules are load-bearing (locked by
- **The summary rides a user message**, so the compacted knowledge persists
through seeding and crosses firings with the conversation it summarizes.
-Prior tool calls/results are dropped from the live list at the swap — they
-survive only inside the summary text. Tool messages that appear *after* the
-summary in the panel are **new work the agent did post-compaction**, not
-survivors (their `ts` stamps postdate the summary). Both the trigger
-(`tokens >= threshold`, live message count) and the applied swap (before →
-after counts, summary size) log at INFO, as does the activity (rendered
-chars in, summary chars + summarizer usage out).
+Tool calls/results from the summarized turns are dropped from the live list
+at the swap; they survive only inside the summary text. Tool messages that
+appear *after* the summary in the panel are the kept latest turn or **new
+work the agent did post-compaction**, not survivors of the summarized turns.
+The trigger (projected tokens against the threshold, transcript bytes against
+the budget), the applied swap (before → after counts, summary size, kept
+messages), each clear and each cut log at INFO, as does the activity
+(rendered chars in, summary chars + summarizer usage out). A summarizer
+failure after the activity's retries is terminal for the run
+(`CompactionError`), not best-effort: past that point the transcript could
+only grow until the provider rejected it.
- **Load failures raise.** `agent.prepare_payload` raises
`ApplicationError("ConversationLoadFailed")` (retryable) when the row
cannot be read, and `ApplicationError("ConversationTooLarge")`
- (non-retryable, `_SEED_TRANSCRIPT_MAX_BYTES` = 1 MB — clear it from the
- Context panel) when it is oversized. Running on silently instead would
- burn tokens on an amnesiac prompt — the exact failure mode this design
- replaced.
+ (non-retryable, `_SEED_TRANSCRIPT_MAX_BYTES` = 1 MB; the message sends the
+ user to the Context panel and the Tool Result Limit) when it is oversized.
+ Running on silently instead would burn tokens on an amnesiac prompt — the
+ exact failure mode this design replaced. With the cap and the byte budget
+ above, new transcripts stay far below the limit; a row saved before them
+ needs one clear.
- **Save failures warn and continue.** The save happens *after* the
provider was called and billed, so raising there would fail a completed
turn over a bookkeeping write. `_save_conversation`
(`agent_activities.py`), the loop's `save_now()` (`agent_runtime.py`),
and every specialized-provider `record_turn` call site swallow and log.
+ `_save_conversation` also logs a WARNING when a saved row passes half of
+ `_SEED_TRANSCRIPT_MAX_BYTES`, while the next firing can still load it.
## Both execution paths, one contract
@@ -218,6 +266,7 @@ workflow, not only the removed Context's agent.
| 7 | `input-memory` is retired; the conversation store is the continuity carrier. Do not resurrect markdown seeding. | `normalize_workflow_graph` migrates it away and the validator rejects it; two carriers would drift. |
| 8 | Specialized bridges record the ORIGINAL prompt, never the augmented one. | Recording the rendered transcript nests the conversation inside itself and grows without bound. |
| 9 | The store never imports `nodes/`; the plugin registers its broadcaster via `register_conversation_listener`, and a listener failure can never fail a save. | Same layering rule as every plugin registry; a UI notification must not break execution. |
+| 10 | External tool results are capped before they enter the transcript; the latest turn is never cleared or summarized; the pressure rules are chosen by the recorded `context_pressure_version`. | Uncapped results bricked every later firing (`errors.md` #28); an unread turn summarized away loses what the model asked for; a replay must schedule the commands it recorded. |
## How this broke (August 2026 regression), and why the journal went away
diff --git a/docs-internal/data_node.md b/docs-internal/data_node.md
index 602d0290..b7fb89ca 100644
--- a/docs-internal/data_node.md
+++ b/docs-internal/data_node.md
@@ -41,8 +41,10 @@ suffixes `-1`, `-2`, …) imports a mount file into the workspace and mints a
real `FileRef` — the bridge to previews, drags, and vision.
**Read tiers** (`_readers.py`, all bounded; `bound_result` caps the
-serialized envelope at ~200 KB because tool results have no downstream
-truncation): text (line window, encoding fallback + `encoding_guessed`),
+serialized envelope at ~200 KB, which also keeps the node's own output small;
+the agent loops then cut what reaches the model to the Tool Result Limit,
+100,000 characters by default, see `services/tool_output.py`): text (line
+window, encoding fallback + `encoding_guessed`),
csv (Sniffer, 500 rows / 100 cols / 2k-char cells), json (≤5 MiB, depth 8,
`pruned_paths`), pdf (pypdf via the `docs` extra, 20 pages/req), html
(bs4), xlsx (openpyxl `read_only`, 500 rows), image (Pillow **metadata
diff --git a/docs-internal/errors.md b/docs-internal/errors.md
index 1babc4d8..ff7d23e1 100644
--- a/docs-internal/errors.md
+++ b/docs-internal/errors.md
@@ -557,3 +557,34 @@ bun add -g @zeenie-ai/opencompany
**Root cause**: bun's own installer refuses to run without `unzip`, and `install.sh` hands off to it without checking. The script also calls `sudo` unconditionally for apt, which does not exist in containers that run as root.
**Workaround**: `apt-get install -y unzip` (or the distro equivalent) before the one-liner. **Fix, when shipped**: install `unzip` via the detected package manager before calling bun's installer, and run package-manager commands directly when already root.
+
+## 28. Every chat message fails with `ConversationTooLarge` after an agent made a few large tool calls
+
+**Symptom**: A deployed chat workflow whose AI Agent has a Context node answers a few turns, and each `agent.execute_llm_step` logs a Temporal `PayloadSizeWarning: [TMPRL1103] ... Size: 528134 bytes, Limit: 524288 bytes` as the input grows (1.4 MB by the sixth tool call). The next chat message fails in `agent.prepare_payload`, and so does every message after it:
+
+```
+ApplicationError: ConversationTooLarge: Stored conversation for agent '1:aiAgent:1' is 1429978 bytes (limit 1000000). Clear the conversation from the Context panel or lower the compaction threshold, then run again.
+```
+
+Seen 2026-09-05 with a `tikhubAction` tool whose results were about 400,000 characters each.
+
+**Root cause**: four gaps lined up.
+- Nothing bounded a tool result before it entered the transcript. Both agent loops appended the serialized result whole, and every later turn re-sent it.
+- Compaction never fired. `AgentWorkflow` compared the running SUM of every step's token usage with 80% of the model's window (838,860 tokens for a 1,048,576-token Gemini model), while the limits actually being hit were in bytes: Temporal's payload sizes and the 1 MB seed cap.
+- The LLM step saves `[...sent, assistant]` after each turn with no size check, so the 1.4 MB transcript was stored.
+- The seed guard in `agent.prepare_payload` is a hard, non-retryable failure by design, because an agent that silently runs without its memory is worse. So one oversized row broke every later firing.
+
+**Fix**:
+- Each external tool result is cut to `TOOL_RESULT_MAX_CHARS` characters (default 100,000; per user under Settings > Tool Result Limit; `0` disables) before it enters the model's conversation, with a note telling the model to call the tool again with narrower parameters. Delegated agents' answers, skill loads and Task Manager results are never cut, and the tool's own result is untouched (`services/tool_output.py`, used by both loops).
+- `AgentWorkflow` runs whose prepare-payload result records `context_pressure_version` 1 keep the transcript under a byte budget of three quarters of Temporal's payload warning (`services/temporal/agent_context_pressure.py`):
+ - past the budget, results from earlier turns become a short placeholder, oldest first and external tools first;
+ - the compaction gate measures the next request instead of a running sum;
+ - a summary covers only the earlier turns and keeps the latest one verbatim;
+ - a latest turn that alone overflows is cut to fit.
+
+ Runs recorded before the key existed replay the original rules unchanged.
+- `ConversationTooLarge` stays a hard failure. Its message now points at the Context panel and the Tool Result Limit, and a save over half the cap logs a WARNING.
+
+Locked by `server/tests/services/test_tool_output.py`, `server/tests/temporal/test_agent_context_pressure.py`, `server/tests/temporal/test_agent_workflow_pressure.py` and `server/tests/temporal/test_prepare_payload_pressure.py`. Design record: [ARCHIVE/AGENT_COMPACTION_FIX_PLAN.md](./ARCHIVE/AGENT_COMPACTION_FIX_PLAN.md).
+
+**Recovery for a row saved before the fix**: clear the conversation once from the Context panel (or Reset the deployment). New transcripts stay well under the cap.
diff --git a/docs-internal/memory_compaction.md b/docs-internal/memory_compaction.md
index 09572514..a0b934d5 100644
--- a/docs-internal/memory_compaction.md
+++ b/docs-internal/memory_compaction.md
@@ -16,7 +16,9 @@ All providers use the same client-side summarization path:
`run_native_llm_step(ChatUnifier, ...)`, then replaces the active memory
history with a structured five-section summary. The current agent runtime does
not enable Anthropic or OpenAI provider-managed compaction. Compaction reduces
-active context pressure; it does not terminate an agent loop.
+active context pressure and never stops an agent early, but on the Temporal
+path a summarizer that still fails after the activity's retries ends the run
+with `CompactionError` (past that point the transcript could only grow).
**Inspired by:** Claude Code's structured compaction pattern
@@ -40,8 +42,12 @@ native agent loop
│ compact_context()
└─ Temporal AgentWorkflow
├─ returns aggregate usage in the workflow result
- └─ when its context counter reaches the prepared threshold:
- agent.compact_context → compact_context()
+ ├─ caps each external tool result; past the transcript's byte
+ │ budget, clears results from earlier turns
+ └─ when the next request reaches the prepared threshold, or the
+ earlier turns alone overflow the byte budget:
+ agent.compact_context → compact_context() on the earlier
+ turns; the latest turn is kept verbatim
compact_context()
└─ run_native_llm_step(ChatUnifier, selected provider/model)
@@ -54,8 +60,10 @@ compact_context()
## Runtime Compaction Path
`compact_context()` uses the same native provider boundary as ordinary agent
-turns. It sends one user message containing the current memory markdown through
-`run_native_llm_step`, with SDK-internal retries disabled. The in-process path
+turns. It sends one user message containing the text to summarize (the memory
+markdown on the in-process path; on the Temporal path, the earlier turns of
+the live transcript, which the `agent.compact_context` activity renders as
+text) through `run_native_llm_step`, with SDK-internal retries disabled. The in-process path
allows the native step helper's bounded explicit retry policy; the Temporal
activity passes `explicit_max_retries=0` because Temporal owns activity
delivery and a repeated summarizer request can be billed twice.
@@ -272,9 +280,9 @@ path-dependent:
- `AgentWorkflow` (F4.B) calculates a ratio-based threshold during
`agent.prepare_payload`; it does not read `custom_threshold`.
- `compaction_enabled` is stored but is not consulted by `track()` or F4.B.
- Only the global `COMPACTION_ENABLED` value controls `track()` today, and F4.B
- does not currently honor that global enabled flag when it extracts the
- numeric threshold.
+ Only the global `COMPACTION_ENABLED` value controls them; F4.B prepares no
+ threshold when it is off (its transcript byte budget and tool-result cap
+ still apply).
Treat the WebSocket settings as persistence/UI controls until those execution
paths are unified; do not promise that they disable or override every run.
@@ -330,11 +338,15 @@ ws.send(JSON.stringify({
### Environment Variables
```bash
-# In the repo-root .env (defaults live in the root .env.template:189-194)
+# In the repo-root .env (defaults live in the root .env.template)
COMPACTION_ENABLED=true # Enable/disable compaction globally (default: true)
COMPACTION_RATIO=0.8 # Fraction of context window that triggers compaction
# (default: 0.8 — was 0.5 pre-2026.06). Range 0.05-0.99.
# Read by core.config.Settings.compaction_ratio.
+TOOL_RESULT_MAX_CHARS=100000 # Most characters one external tool result may add
+ # to an agent's conversation; 0 disables the cap.
+ # Per-user override: UserSettings.tool_result_max_chars
+ # (Settings tab > Tool Result Limit, 10K-200K).
```
**In-process `track()` threshold priority chain** (highest → lowest):
@@ -532,11 +544,17 @@ if tracking.get('needs_compaction') and memory_content and api_key:
memory_data['memory_content'] = result['summary']
```
-F4.B performs a parallel check inside `AgentWorkflow` using the workflow's
-active-context usage counter and the ratio-based threshold recorded by
-`agent.prepare_payload`. It invokes the same `compact_context()` method
-through the `agent.compact_context` activity
-(`services/temporal/agent_activities.py:1945`).
+F4.B performs its own check inside `AgentWorkflow` after each tool turn,
+against the ratio-based threshold recorded by `agent.prepare_payload`. Runs
+recorded with `context_pressure_version` 1 measure the next request (the
+last step's `total_tokens`, which every provider fills with the whole prompt
+including cache reads, plus the characters the turn added, at four per
+token), and also summarize when the earlier turns alone overflow the
+transcript's byte budget; runs recorded before that key replay the original
+running sum of every step's usage. It invokes the same `compact_context()`
+method through the `agent.compact_context` activity (`compact_context` in
+`services/temporal/agent_activities.py`). The full rules are in
+[agent_context_flow.md → Transcript size](./agent_context_flow.md).
### AI Service Wiring
diff --git a/server/core/config.py b/server/core/config.py
index f8aee57f..419ea76e 100644
--- a/server/core/config.py
+++ b/server/core/config.py
@@ -459,6 +459,11 @@ class Settings(BaseSettings):
compaction_enabled: bool = Field(default=True, env="COMPACTION_ENABLED")
compaction_ratio: float = Field(default=0.8, env="COMPACTION_RATIO", ge=0.05, le=0.99)
+ # Largest result, in characters, one external tool call may add to an
+ # agent's conversation; longer results are cut with a note. 0 disables
+ # the cap. Per-user UserSettings row overrides at runtime.
+ tool_result_max_chars: int = Field(default=100_000, env="TOOL_RESULT_MAX_CHARS", ge=0)
+
# Agent loop hard step cap. Per-user UserSettings row overrides
# at runtime; per-agent-node ``parameters.max_iterations`` is the
# innermost override.
diff --git a/server/core/database.py b/server/core/database.py
index 9e8d8234..32791383 100644
--- a/server/core/database.py
+++ b/server/core/database.py
@@ -231,6 +231,13 @@ class Database:
await conn.execute(text("ALTER TABLE user_settings ADD COLUMN agent_recursion_limit INTEGER DEFAULT 200"))
logger.info("Added agent_recursion_limit column to user_settings")
+ if "tool_result_max_chars" not in columns:
+ # The model field's default is the source of truth; existing
+ # rows need a real value because the client parser rejects null.
+ default_chars = int(UserSettings.model_fields["tool_result_max_chars"].default)
+ await conn.execute(text(f"ALTER TABLE user_settings ADD COLUMN tool_result_max_chars INTEGER DEFAULT {default_chars}"))
+ logger.info("Added tool_result_max_chars column to user_settings")
+
if "max_concurrent_subagents" not in columns:
await conn.execute(text("ALTER TABLE user_settings ADD COLUMN max_concurrent_subagents INTEGER DEFAULT 3"))
if "max_delegation_depth" not in columns:
@@ -2115,6 +2122,7 @@ class Database:
"auto_add_skill_for_tools": settings.auto_add_skill_for_tools,
"auto_rebind_tools_after_canvas_change": settings.auto_rebind_tools_after_canvas_change,
"agent_recursion_limit": settings.agent_recursion_limit,
+ "tool_result_max_chars": settings.tool_result_max_chars,
"max_concurrent_subagents": settings.max_concurrent_subagents,
"max_delegation_depth": settings.max_delegation_depth,
"created_at": settings.created_at.isoformat() if settings.created_at else None,
diff --git a/server/models/database.py b/server/models/database.py
index 1dea6856..fa1cab59 100644
--- a/server/models/database.py
+++ b/server/models/database.py
@@ -302,6 +302,7 @@ class UserSettings(SQLModel, table=True):
memory_window_size: int = Field(default=100) # Message pairs in short-term memory (1-100)
compaction_ratio: float = Field(default=0.8) # Fraction of context window triggering compaction (0.05-0.99). Mirrors COMPACTION_RATIO env default.
agent_recursion_limit: int = Field(default=200) # Hard step cap for the agent loop. Mirrors AGENT_RECURSION_LIMIT env default.
+ tool_result_max_chars: int = Field(default=100000) # Largest external tool result (characters) kept in an agent's conversation. Mirrors TOOL_RESULT_MAX_CHARS env default.
max_concurrent_subagents: int = Field(default=3)
max_delegation_depth: int = Field(default=2)
examples_loaded: bool = Field(default=False) # Track if example workflows were imported
diff --git a/server/services/agent_runtime.py b/server/services/agent_runtime.py
index 7d69f9ba..561a8866 100644
--- a/server/services/agent_runtime.py
+++ b/server/services/agent_runtime.py
@@ -39,6 +39,7 @@ from services.llm.protocol import (
Usage,
)
from services.tool_identity import DuplicateToolNameError
+from services.tool_output import bound_tool_output, tool_output_is_capped
logger = get_logger(__name__)
@@ -213,12 +214,17 @@ async def run_native_agent_loop(
conversation_saver: Optional[
Callable[[List[Message]], Awaitable[None]]
] = None,
+ tool_output_limit: Optional[int] = None,
) -> Dict[str, Any]:
"""Run the shared buffered native tool-agent loop.
The complete assistant message returned by a provider is appended verbatim
before tool execution. This is essential for Gemini thought signatures,
Anthropic signed thinking blocks, and OpenAI reasoning continuation state.
+
+ ``tool_output_limit`` caps, in characters, what one external tool result
+ adds to ``messages`` (see ``services.tool_output``); ``None`` or ``0``
+ keeps results whole.
"""
current_tools: List[AgentToolSpec] = list(tools or ())
@@ -393,14 +399,21 @@ async def run_native_agent_loop(
"[Agent loop] tool rebind failed: %s", exc, exc_info=True
)
+ content = json.dumps(result, default=str)
+ called_spec = specs.get(call.name)
+ if tool_output_limit and tool_output_is_capped(
+ called_spec.execution.get("node_type") if called_spec else None
+ ):
+ content = bound_tool_output(content, tool_output_limit)
tool_message = Message(
role="tool",
- content=json.dumps(result, default=str),
+ content=content,
tool_call_id=call.id,
name=call.name,
)
# Tools opt into vision via `llm_media` refs; blocks stay ~450 B
- # in durable state (hydration happens per provider call).
+ # in durable state (hydration happens per provider call). Read
+ # from the untouched result, so a capped text keeps its images.
tool_message.blocks.extend(image_blocks_from_tool_result(result))
messages.append(tool_message)
diff --git a/server/services/ai.py b/server/services/ai.py
index ee551342..e9b58e7a 100644
--- a/server/services/ai.py
+++ b/server/services/ai.py
@@ -61,6 +61,7 @@ from services.llm.config import (
resolve_temperature as native_resolve_temperature,
)
from services.agent_runtime import AgentToolSpec, run_native_agent_loop
+from services.tool_output import resolve_tool_output_limit
# =============================================================================
@@ -1260,6 +1261,7 @@ class AIService:
# feature doesn't silently disable itself on a transient DB hiccup.
auto_rebind_enabled = True
user_recursion_limit: Optional[int] = None
+ tool_output_limit = resolve_tool_output_limit(None, self.settings)
try:
user_settings = await self.database.get_user_settings()
if user_settings is not None:
@@ -1269,6 +1271,9 @@ class AIService:
_raw_limit = user_settings.get("agent_recursion_limit")
if isinstance(_raw_limit, int) and _raw_limit > 0:
user_recursion_limit = _raw_limit
+ tool_output_limit = resolve_tool_output_limit(
+ user_settings, self.settings
+ )
except Exception as exc: # noqa: BLE001 — defensive read
logger.debug("[Agent] user_settings read failed: %s", exc)
@@ -1406,6 +1411,7 @@ class AIService:
if context_runtime is not None
else None
),
+ tool_output_limit=tool_output_limit,
)
# Extract the AI response (last message in the accumulated messages)
@@ -1978,6 +1984,7 @@ class AIService:
# machinery as ``execute_agent``.
auto_rebind_enabled = True
user_recursion_limit: Optional[int] = None
+ tool_output_limit = resolve_tool_output_limit(None, self.settings)
try:
user_settings = await self.database.get_user_settings()
if user_settings is not None:
@@ -1987,6 +1994,9 @@ class AIService:
_raw_limit = user_settings.get("agent_recursion_limit")
if isinstance(_raw_limit, int) and _raw_limit > 0:
user_recursion_limit = _raw_limit
+ tool_output_limit = resolve_tool_output_limit(
+ user_settings, self.settings
+ )
except Exception as exc: # noqa: BLE001 — defensive read
logger.debug("[ChatAgent] user_settings read failed: %s", exc)
@@ -2086,6 +2096,7 @@ class AIService:
if context_runtime is not None
else None
),
+ tool_output_limit=tool_output_limit,
)
# Extract response
diff --git a/server/services/temporal/agent_activities.py b/server/services/temporal/agent_activities.py
index bb8a2635..838808d8 100644
--- a/server/services/temporal/agent_activities.py
+++ b/server/services/temporal/agent_activities.py
@@ -51,10 +51,14 @@ from temporalio.exceptions import ApplicationError
logger = logging.getLogger(__name__)
# Byte ceiling for the stored conversation returned by ``prepare_agent_payload``
-# as a fresh-run seed. Conversations are compaction-bounded in tokens but not
-# in bytes, and Temporal's payload error limit is 2 MiB for the whole activity
-# result — over the cap the run degrades to its opening prompt with a warning
-# instead of dying. Mirrors ``_CAN_TRANSCRIPT_MAX_BYTES`` on the rollover path.
+# as a fresh-run seed; the whole activity result must stay under Temporal's
+# 2 MiB payload error limit. Over the cap the load raises the non-retryable
+# ``ConversationTooLarge`` so the user clears the conversation from the
+# Context panel, rather than the agent silently running without its memory.
+# New transcripts stay well below it: each external tool result is capped and
+# ``AgentWorkflow`` clears old results past ``transcript_budget_bytes`` (see
+# ``agent_context_pressure``). Same value as ``_CAN_TRANSCRIPT_MAX_BYTES`` on
+# the rollover path.
_SEED_TRANSCRIPT_MAX_BYTES = 1_000_000
# Activity result shapes — keep these in sync with AgentWorkflow's
@@ -384,12 +388,24 @@ async def _save_conversation(
from core.container import container
from services.agent_context import save_conversation
+ messages = [*sent, assistant_wire]
+ saved_bytes = len(json.dumps(messages, default=str).encode("utf-8"))
+ if saved_bytes > _SEED_TRANSCRIPT_MAX_BYTES // 2:
+ # The next firing refuses to load a row over the cap
+ # (ConversationTooLarge), so say so while there is still room.
+ activity.logger.warning(
+ f"Saved conversation for agent {key.get('agent_node_id')!r} "
+ f"(workflow {key.get('workflow_id')!r}, generation "
+ f"{key.get('generation')}) is {saved_bytes} bytes, over half "
+ f"the {_SEED_TRANSCRIPT_MAX_BYTES}-byte limit a later run can "
+ "load"
+ )
await save_conversation(
container.database(),
workflow_id=str(key.get("workflow_id") or ""),
generation=int(key.get("generation") or 0),
agent_node_id=str(key.get("agent_node_id") or ""),
- messages=[*sent, assistant_wire],
+ messages=messages,
)
except Exception:
# Persistence must never fail the run. The provider has already
@@ -1041,8 +1057,9 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
f"Stored conversation for agent {node_id!r} is "
f"{seed_bytes} bytes (limit "
f"{_SEED_TRANSCRIPT_MAX_BYTES}). Clear the conversation "
- "from the Context panel or lower the compaction "
- "threshold, then run again.",
+ "from the Context panel, then run again. Settings > "
+ "Tool Result Limit caps how much one tool call can add "
+ "to it.",
type="ConversationTooLarge",
non_retryable=True,
)
@@ -1154,6 +1171,11 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
compaction_threshold = int(cfg.get("context_token_threshold") or 0) or None
except Exception: # noqa: BLE001 — defensive, optional feature
compaction_threshold = None
+ activity.logger.warning(
+ f"Compaction threshold unavailable for agent {node_id!r}; this "
+ "run will not summarize its conversation",
+ exc_info=True,
+ )
# ---- Optional auto-prompt fallback from input_data -----------------
# When `prompt` is empty AND a chatTrigger / whatsappReceive / etc.
@@ -1175,19 +1197,26 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
# same value.
# - agent_recursion_limit: applied to the agent loop's hard step
# cap. Per-user override beats env Settings.
+ # - tool_result_max_chars: the most one external tool result may add
+ # to the transcript. Per-user override beats env Settings.
auto_rebind_tools = True
settings_recursion_limit: Optional[int] = None
from core.config import Settings as _DelegationSettings
+ from services.tool_output import resolve_tool_output_limit
delegation_settings = _DelegationSettings()
max_concurrent_subagents = int(delegation_settings.max_concurrent_subagents)
max_delegation_depth = int(delegation_settings.max_delegation_depth)
+ tool_result_max_chars = resolve_tool_output_limit(None, delegation_settings)
try:
user_settings = await database.get_user_settings()
if user_settings is not None:
auto_rebind_tools = bool(
user_settings.get("auto_rebind_tools_after_canvas_change", True)
)
+ tool_result_max_chars = resolve_tool_output_limit(
+ user_settings, delegation_settings
+ )
raw_limit = user_settings.get("agent_recursion_limit")
if isinstance(raw_limit, int) and raw_limit > 0:
settings_recursion_limit = raw_limit
@@ -1214,6 +1243,11 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
except Exception: # noqa: BLE001 — last-resort fallback
effective_recursion_limit = 200
+ from services.temporal.agent_context_pressure import (
+ CONTEXT_PRESSURE_VERSION,
+ transcript_budget_bytes,
+ )
+
return {
"node_id": node_id,
"node_type": node_type,
@@ -1235,6 +1269,12 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
"max_iterations": effective_recursion_limit,
"thinking_config": thinking_config_dict,
"compaction_threshold": compaction_threshold,
+ # Transcript-pressure controls. Recording them in this result pins
+ # the run's behavior on replay: a history recorded before these keys
+ # existed replays through AgentWorkflow's original paths.
+ "tool_result_max_chars": tool_result_max_chars,
+ "transcript_budget_bytes": transcript_budget_bytes(),
+ "context_pressure_version": CONTEXT_PRESSURE_VERSION,
"auto_rebind_tools": auto_rebind_tools,
"max_concurrent_subagents": max_concurrent_subagents,
"max_delegation_depth": max_delegation_depth,
diff --git a/server/services/temporal/agent_context_pressure.py b/server/services/temporal/agent_context_pressure.py
new file mode 100644
index 00000000..263efb50
--- /dev/null
+++ b/server/services/temporal/agent_context_pressure.py
@@ -0,0 +1,342 @@
+"""Transcript-pressure relief for ``AgentWorkflow`` (pure, workflow-safe).
+
+Every function here is a pure computation over MessageWire dicts: no I/O, no
+clock, no randomness. ``AgentWorkflow`` calls them from workflow code, and a
+replay gets the same answer.
+
+Why this exists (docs-internal/errors.md, entry 28): each tool result is
+appended to the agent's transcript and re-sent on every later turn. The
+transcript is the ``agent.execute_llm_step`` input and, after each turn, the
+saved conversation, so an unbounded one first draws Temporal payload
+warnings, then payload errors, and finally fails the next firing at the 1 MB
+seed cap. After each tool turn the workflow applies, in order:
+
+1. :func:`clear_old_tool_results`: past the byte budget, results from earlier
+ turns are replaced by a short placeholder, oldest first and external tools
+ before agent-internal ones, until the transcript is at half the budget.
+ Each keeps its ``tool_call_id`` and ``name``, so every tool call still has
+ its answer. The latest turn is never cleared: the model has not read it.
+2. Summarization, when the next request (:func:`projected_request_tokens`)
+ reaches the compaction threshold, or when the transcript is still over
+ budget because of what the earlier turns hold. Only the turns before the
+ latest one are summarized.
+3. :func:`clip_latest_turn`: if the latest turn alone still does not fit, its
+ external results are cut to one shared length.
+
+Replay contract: ``agent.prepare_payload`` records ``context_pressure_version``
+in the run's history, and the recorded value selects this code path. These
+rules decide whether ``agent.compact_context`` is scheduled, so any change to
+the clearing order, the placeholder, the targets or the token arithmetic must
+ship under a new version number, with the previous rules kept for runs that
+recorded the old one.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence
+
+from services.tool_output import bound_tool_output
+
+CONTEXT_PRESSURE_VERSION = 1
+
+# Rough characters per token for text that has not been through a tokenizer
+# yet (the same estimate ``skill_runtime`` reports for skill loads).
+CHARS_PER_TOKEN = 4
+
+CLEARED_TOOL_RESULT = (
+ "[Earlier tool result cleared to keep this conversation within its size "
+ "budget. Call the tool again if you still need it.]"
+)
+
+# Shortest length a latest-turn result is cut to. Below it the model gets too
+# little to act on; the result is kept at this length even if the transcript
+# then stays over budget.
+MIN_CLIPPED_RESULT_CHARS = 2_000
+
+
+def transcript_budget_bytes() -> int:
+ """Byte budget for a transcript, recorded by ``agent.prepare_payload``.
+
+ The transcript rides every ``agent.execute_llm_step`` input next to the
+ tool definitions and a second copy of the system prompt, so it gets three
+ quarters of the size at which Temporal starts warning about a payload.
+ Imported lazily: ``services.media`` loads its whole package on import,
+ which workflow code does not need.
+ """
+ from services.media.limits import TEMPORAL_PAYLOAD_WARN_BYTES
+
+ return TEMPORAL_PAYLOAD_WARN_BYTES * 3 // 4
+
+
+def transcript_bytes(messages: Sequence[Any]) -> int:
+ """Serialized size, measured the way the rollover guard measures it."""
+ return len(json.dumps(list(messages), default=str).encode("utf-8"))
+
+
+@dataclass(frozen=True)
+class Relief:
+ """What one relief step changed."""
+
+ bytes_before: int
+ bytes_after: int
+ # Tool results cleared or cut.
+ changed: int = 0
+ # Content characters removed, net of placeholders and notes.
+ chars_removed: int = 0
+
+
+def clear_old_tool_results(
+ messages: List[Dict[str, Any]],
+ *,
+ turn_start: int,
+ budget_bytes: int,
+ is_capped: Callable[[Optional[str]], bool],
+) -> Relief:
+ """Clear results from turns before ``turn_start`` once over the budget.
+
+ Replaces entries of ``messages`` in place. ``turn_start`` is the index of
+ the latest turn's assistant message; that message and the results after
+ it are left alone. ``is_capped`` maps a tool message's ``name`` to
+ whether the tool is external. Clears down to half the budget, because
+ every clear changes the prompt the provider has cached, so one larger
+ clear beats a small one every turn.
+ """
+ size = transcript_bytes(messages)
+ before = size
+ if not budget_bytes or size <= budget_bytes:
+ return Relief(bytes_before=before, bytes_after=size)
+
+ target = budget_bytes // 2
+ boundary = max(0, min(turn_start, len(messages)))
+ changed = 0
+ removed = 0
+ for external in (True, False):
+ for index in range(boundary):
+ if size <= target:
+ break
+ message = messages[index]
+ if not _is_tool_result(message):
+ continue
+ if bool(is_capped(message.get("name"))) is not external:
+ continue
+ content = _content(message)
+ if content == CLEARED_TOOL_RESULT:
+ continue
+ replacement = _with_content(message, CLEARED_TOOL_RESULT)
+ saved = _item_bytes(message) - _item_bytes(replacement)
+ if saved <= 0:
+ continue
+ messages[index] = replacement
+ size -= saved
+ changed += 1
+ removed += len(content) - len(CLEARED_TOOL_RESULT)
+ return Relief(
+ bytes_before=before,
+ bytes_after=size,
+ changed=changed,
+ chars_removed=removed,
+ )
+
+
+def earlier_turns_over_budget(
+ messages: Sequence[Any],
+ *,
+ turn_start: int,
+ budget_bytes: int,
+ size: int,
+) -> bool:
+ """Whether the earlier turns, not the latest one, keep ``messages`` over budget.
+
+ ``size`` is the transcript's size after :func:`clear_old_tool_results`.
+ Still over the budget with the turns before ``turn_start`` holding more
+ than half of it, the transcript carries text that only a summary can
+ shrink. Otherwise the latest turn is the excess, and
+ :func:`clip_latest_turn` handles it without a summarizer call.
+ """
+ if not budget_bytes or size <= budget_bytes:
+ return False
+ return transcript_bytes(messages[: max(0, turn_start)]) > budget_bytes // 2
+
+
+def clip_latest_turn(
+ messages: List[Dict[str, Any]],
+ *,
+ turn_start: int,
+ budget_bytes: int,
+ is_capped: Callable[[Optional[str]], bool],
+) -> Relief:
+ """Cut the latest turn's external results to one shared length that fits.
+
+ For when earlier turns are already as small as clearing and summarizing
+ can make them. Results shorter than the shared length stay whole, and
+ none is cut below ``MIN_CLIPPED_RESULT_CHARS``. The length is found by
+ bisection on the exact serialized size, so the note each cut appends and
+ the repeated ``tool_result`` block are accounted for.
+ """
+ size = transcript_bytes(messages)
+ before = size
+ if not budget_bytes or size <= budget_bytes:
+ return Relief(bytes_before=before, bytes_after=size)
+ turn = {
+ index: messages[index]
+ for index in range(max(0, turn_start), len(messages))
+ if _is_tool_result(messages[index])
+ and is_capped(messages[index].get("name"))
+ }
+ if not turn:
+ return Relief(bytes_before=before, bytes_after=size)
+ others = size - sum(_item_bytes(message) for message in turn.values())
+
+ def cut(share: int) -> Dict[int, Dict[str, Any]]:
+ return {index: _bounded(message, share) for index, message in turn.items()}
+
+ def size_at(share: int) -> int:
+ return others + sum(_item_bytes(message) for message in cut(share).values())
+
+ low = MIN_CLIPPED_RESULT_CHARS
+ high = max(len(_content(message)) for message in turn.values())
+ if high <= low:
+ return Relief(bytes_before=before, bytes_after=size)
+ if size_at(low) <= budget_bytes:
+ while low < high:
+ middle = (low + high + 1) // 2
+ if size_at(middle) <= budget_bytes:
+ low = middle
+ else:
+ high = middle - 1
+
+ changed = 0
+ removed = 0
+ for index, replacement in cut(low).items():
+ original = turn[index]
+ if replacement is original:
+ continue
+ messages[index] = replacement
+ changed += 1
+ removed += len(_content(original)) - len(_content(replacement))
+ return Relief(
+ bytes_before=before,
+ bytes_after=transcript_bytes(messages),
+ changed=changed,
+ chars_removed=removed,
+ )
+
+
+def request_tokens(usage: Optional[Mapping[str, Any]]) -> int:
+ """Tokens in the request that produced ``usage``, plus its reply.
+
+ Every provider fills ``total_tokens`` with the whole prompt, prompt-cache
+ reads and writes included, plus the output. Never add the cache counters
+ to ``input_tokens``: OpenAI and Gemini already count cached tokens inside
+ it, while Anthropic does not.
+ """
+ usage = usage or {}
+ return max(
+ _int(usage.get("total_tokens")),
+ _int(usage.get("input_tokens")) + _int(usage.get("output_tokens")),
+ )
+
+
+def projected_request_tokens(
+ usage: Optional[Mapping[str, Any]],
+ added_chars: int,
+) -> int:
+ """Estimated size of the next request.
+
+ The last request and its reply, plus the characters this turn added to
+ the transcript, net of what relief removed, at ``CHARS_PER_TOKEN``.
+ """
+ return max(0, request_tokens(usage) + added_chars // CHARS_PER_TOKEN)
+
+
+def turn_tool_chars(messages: Sequence[Any], turn_start: int) -> int:
+ """Characters of tool-result content in the latest turn."""
+ return sum(
+ len(_content(message))
+ for message in messages[max(0, turn_start):]
+ if _is_tool_result(message)
+ )
+
+
+def has_summarizable_history(messages: Sequence[Any], turn_start: int) -> bool:
+ """Whether turns older than the latest one exist to fold into a summary.
+
+ Before its first turn a run holds the system prompt and one user message
+ (the request, or an earlier summary carrying it). Summarizing only that
+ gains nothing, and a short one is rejected by the summarizer, which fails
+ the run.
+ """
+ return (
+ sum(
+ 1
+ for message in messages[: max(0, turn_start)]
+ if isinstance(message, Mapping) and message.get("role") != "system"
+ )
+ > 1
+ )
+
+
+_SUMMARIZER_FIELDS = ("role", "content", "tool_calls", "tool_call_id", "name")
+
+
+def summarizer_view(messages: Sequence[Any]) -> List[Dict[str, Any]]:
+ """The fields ``agent.compact_context`` renders, and nothing more.
+
+ Drops the duplicated content blocks and the provider continuation state,
+ which the summarizer never reads but which would double its input.
+ """
+ return [
+ {key: message[key] for key in _SUMMARIZER_FIELDS if key in message}
+ for message in messages
+ if isinstance(message, Mapping)
+ ]
+
+
+def _is_tool_result(message: Any) -> bool:
+ return isinstance(message, Mapping) and message.get("role") == "tool"
+
+
+def _content(message: Mapping[str, Any]) -> str:
+ return str(message.get("content") or "")
+
+
+def _item_bytes(message: Any) -> int:
+ return len(json.dumps(message, default=str).encode("utf-8"))
+
+
+def _bounded(message: Dict[str, Any], share: int) -> Dict[str, Any]:
+ """``message`` itself when it fits ``share``, else a cut copy."""
+ content = _content(message)
+ bounded = bound_tool_output(content, share)
+ return message if bounded == content else _with_content(message, bounded)
+
+
+def _with_content(message: Mapping[str, Any], content: str) -> Dict[str, Any]:
+ """Rebuild a tool result around ``content`` through the wire codec.
+
+ Rebuilding, rather than editing ``content`` alone, regenerates the
+ ``tool_result`` block that repeats the text and drops any image blocks,
+ so the old payload is really gone.
+ """
+ from services.llm.protocol import Message, message_to_wire
+
+ return dict(
+ message_to_wire(
+ Message(
+ role="tool",
+ content=content,
+ tool_call_id=_optional_str(message.get("tool_call_id")),
+ name=_optional_str(message.get("name")),
+ )
+ )
+ )
+
+
+def _optional_str(value: Any) -> Optional[str]:
+ return None if value is None else str(value)
+
+
+def _int(value: Any) -> int:
+ return value if isinstance(value, int) and not isinstance(value, bool) else 0
diff --git a/server/services/temporal/agent_workflow.py b/server/services/temporal/agent_workflow.py
index a2543ea9..5d3011f7 100644
--- a/server/services/temporal/agent_workflow.py
+++ b/server/services/temporal/agent_workflow.py
@@ -56,6 +56,7 @@ from temporalio.common import RetryPolicy # kept for type hints
from temporalio.workflow import ActivityCancellationType, ParentClosePolicy
from services.node_registry import get_node_class
+from services.tool_output import bound_tool_output, tool_output_is_capped
from ._retry_policies import (
DEFAULT_ACTIVITY_RETRY,
@@ -63,6 +64,15 @@ from ._retry_policies import (
LLM_STEP_RETRY,
PERMIT_WAIT_RETRY,
)
+from .agent_context_pressure import (
+ clear_old_tool_results,
+ clip_latest_turn,
+ earlier_turns_over_budget,
+ has_summarizable_history,
+ projected_request_tokens,
+ summarizer_view,
+ turn_tool_chars,
+)
from .workflow import AGENT_WORKFLOW_TYPES
@@ -593,6 +603,11 @@ class AgentWorkflow:
"max_iterations": int,
"thinking_config": Optional[dict],
"compaction_threshold": Optional[int],
+ # Transcript-pressure controls; absent on histories recorded
+ # before they existed, which then replay the original paths.
+ "tool_result_max_chars": int, # 0 keeps results whole
+ "transcript_budget_bytes": int,
+ "context_pressure_version": int,
}
Returns the final agent response, mirroring the shape
@@ -744,6 +759,22 @@ class AgentWorkflow:
tool_index: Dict[str, Dict[str, Any]] = {t["name"]: t for t in tools}
compaction_threshold = payload.get("compaction_threshold")
+
+ # Transcript-pressure controls recorded by prepare-payload. A history
+ # recorded before these keys existed reads 0 for each, so it keeps
+ # whole tool results and replays the original compaction gate below.
+ tool_output_limit = int(payload.get("tool_result_max_chars") or 0)
+ pressure_version = int(payload.get("context_pressure_version") or 0)
+ transcript_budget = int(payload.get("transcript_budget_bytes") or 0)
+
+ def _result_is_capped(tool_name: Optional[str]) -> bool:
+ """Whether the tool message named ``tool_name`` holds external output."""
+ name = str(tool_name or "")
+ if name.startswith("delegate_to_"):
+ return False
+ info = tool_index.get(name)
+ return tool_output_is_capped(info.get("node_type") if info else None)
+
thinking_accumulated = ""
final_content: Optional[str] = None
# Billing/observability is cumulative for the entire execution and
@@ -936,6 +967,10 @@ class AgentWorkflow:
# cache markers, OpenAI reasoning content — everything the next
# turn's request needs.
assistant_message = step_result.get("assistant_message")
+ # Where this turn starts. Transcript-pressure relief never clears
+ # or summarizes the turn whose tool results the model has not
+ # read yet.
+ turn_start = len(messages)
if assistant_message:
messages.append(assistant_message)
@@ -1841,6 +1876,16 @@ class AgentWorkflow:
"delegation_usage": delegated.get("usage"),
}
tool_content = _serialise_tool_result(tool_result)
+ if (
+ tool_output_limit
+ and not is_delegation
+ and tool_output_is_capped(tool_info["node_type"])
+ ):
+ # Only the model's copy is cut; the tool node keeps
+ # its whole result.
+ tool_content = bound_tool_output(
+ tool_content, tool_output_limit
+ )
await self._emit_phase(
agent_node_id,
agent_workflow_id,
@@ -2045,35 +2090,95 @@ class AgentWorkflow:
interim=True,
)
- # ---- Compaction check --------------------------------------
- # Simple by design: token threshold -> summarize the live
- # conversation -> swap messages. No memory-node gate, no
+ # ---- Transcript pressure and compaction ----------------------
+ # Summarize, then swap messages: no memory-node gate, no
# checkpoint machinery. A later rollover resumes from the
- # compacted state for free, because the next LLM turn journals
- # a fresh request.snapshot containing the compacted messages.
- token_total = int(
- context_usage_total.get("total_tokens") or 0
- )
- if not token_total:
- token_total = sum(
- int(context_usage_total.get(key) or 0)
- for key in (
- "input_tokens",
- "cache_creation_tokens",
- "cache_read_tokens",
- "output_tokens",
+ # compacted state for free, because the next LLM turn sends and
+ # saves the compacted messages. The recorded
+ # ``context_pressure_version`` picks the rules:
+ # - version 1 (agent_context_pressure): clear old tool results
+ # past the byte budget, summarize when the NEXT request
+ # reaches the threshold or the earlier turns alone keep the
+ # transcript over budget, and never summarize this turn,
+ # whose tool results the model has not read yet;
+ # - no version (a history recorded before it existed): the
+ # original rule, cumulative tokens -> summarize everything,
+ # so a replay schedules exactly the commands it recorded.
+ compact_source: Optional[List[Dict[str, Any]]] = None
+ kept_turn: List[Dict[str, Any]] = []
+ if pressure_version >= 1:
+ clearing = clear_old_tool_results(
+ messages,
+ turn_start=turn_start,
+ budget_bytes=transcript_budget,
+ is_capped=_result_is_capped,
+ )
+ if clearing.changed:
+ workflow.logger.info(
+ f"AgentWorkflow cleared {clearing.changed} earlier "
+ f"tool result(s) at iteration {iteration + 1}: "
+ f"{clearing.bytes_before} -> {clearing.bytes_after} "
+ f"bytes (budget {transcript_budget})"
)
+ token_total = projected_request_tokens(
+ step_result.get("usage"),
+ turn_tool_chars(messages, turn_start)
+ - clearing.chars_removed,
)
- if compaction_threshold and token_total >= compaction_threshold:
- workflow.logger.info(
- f"AgentWorkflow compaction triggered at iteration "
- f"{iteration + 1}: {token_total} tokens >= threshold "
- f"{compaction_threshold} ({len(messages)} live messages)"
+ history_over_budget = earlier_turns_over_budget(
+ messages,
+ turn_start=turn_start,
+ budget_bytes=transcript_budget,
+ size=clearing.bytes_after,
)
+ if compaction_threshold and (
+ token_total >= compaction_threshold or history_over_budget
+ ):
+ if has_summarizable_history(messages, turn_start):
+ workflow.logger.info(
+ f"AgentWorkflow compaction triggered at iteration "
+ f"{iteration + 1}: next request about "
+ f"{token_total} tokens (threshold "
+ f"{compaction_threshold}), transcript "
+ f"{clearing.bytes_after} bytes (budget "
+ f"{transcript_budget}); summarizing {turn_start} "
+ f"earlier message(s), keeping this turn's "
+ f"{len(messages) - turn_start}"
+ )
+ compact_source = summarizer_view(messages[:turn_start])
+ kept_turn = messages[turn_start:]
+ else:
+ workflow.logger.info(
+ f"AgentWorkflow compaction skipped at iteration "
+ f"{iteration + 1}: nothing older than this turn "
+ "to summarize"
+ )
+ else:
+ token_total = int(
+ context_usage_total.get("total_tokens") or 0
+ )
+ if not token_total:
+ token_total = sum(
+ int(context_usage_total.get(key) or 0)
+ for key in (
+ "input_tokens",
+ "cache_creation_tokens",
+ "cache_read_tokens",
+ "output_tokens",
+ )
+ )
+ if compaction_threshold and token_total >= compaction_threshold:
+ workflow.logger.info(
+ f"AgentWorkflow compaction triggered at iteration "
+ f"{iteration + 1}: {token_total} tokens >= threshold "
+ f"{compaction_threshold} ({len(messages)} live messages)"
+ )
+ compact_source = messages
+ if compact_source is not None:
compact_payload = {
"session_id": payload.get("session_id", "default"),
"node_id": payload["node_id"],
- "messages": messages,
+ "messages": compact_source,
"provider": payload["provider"],
"model": payload["model"],
}
@@ -2146,7 +2251,7 @@ class AgentWorkflow:
# The activity raises on any failure, so a result here
# always carries a non-empty summary.
summary = compact_result.get("summary", "")
- dropped_count = len(messages)
+ dropped_count = len(messages) - len(kept_turn)
# Rebuild as: the ORIGINAL system prompt, verbatim, plus ONE
# user message carrying the summary and the live request.
#
@@ -2185,16 +2290,53 @@ class AgentWorkflow:
role="user",
content=compacted_content,
),
+ # Version 1 keeps this turn verbatim, because its tool
+ # results are still unread. Empty on the original path.
+ *kept_turn,
]
context_usage_total = {}
+ turn_start = len(messages) - len(kept_turn)
workflow.logger.info(
f"AgentWorkflow compaction applied at iteration "
f"{iteration + 1}: {dropped_count} messages -> "
- f"{len(messages)} (summary {len(summary)} chars; prior "
- "tool calls/results now live only inside the summary; "
- "system prompt preserved verbatim)"
+ f"{len(messages)} (summary {len(summary)} chars; "
+ f"{len(kept_turn)} message(s) of this turn kept verbatim; "
+ "earlier tool calls/results now live only inside the "
+ "summary; system prompt preserved verbatim)"
)
+ if pressure_version >= 1:
+ # Last resort, against whatever room the earlier turns now
+ # leave: cut this turn's external results to one length that
+ # fits. Clipping only after summarizing keeps as much of the
+ # unread results as possible.
+ clipping = clip_latest_turn(
+ messages,
+ turn_start=turn_start,
+ budget_bytes=transcript_budget,
+ is_capped=_result_is_capped,
+ )
+ if clipping.changed:
+ workflow.logger.info(
+ f"AgentWorkflow cut {clipping.changed} tool result(s) "
+ f"of this turn at iteration {iteration + 1}: "
+ f"{clipping.bytes_before} -> {clipping.bytes_after} "
+ f"bytes (budget {transcript_budget})"
+ )
+ if transcript_budget and clipping.bytes_after > transcript_budget:
+ workflow.logger.warning(
+ f"AgentWorkflow transcript is still "
+ f"{clipping.bytes_after} bytes after relief at "
+ f"iteration {iteration + 1} (budget "
+ f"{transcript_budget}"
+ + (
+ ""
+ if compaction_threshold
+ else "; compaction is off for this run"
+ )
+ + ")"
+ )
+
# ---- Continue-as-new -------------------------------------
# Only at a clean turn boundary, and never while a delegation
# is in flight: delegation_handles and the Task-Manager task
diff --git a/server/services/tool_output.py b/server/services/tool_output.py
new file mode 100644
index 00000000..8b8c55c5
--- /dev/null
+++ b/server/services/tool_output.py
@@ -0,0 +1,107 @@
+"""Bound what one tool result may add to an agent's LLM conversation.
+
+Both agent loops, the in-process ``run_native_agent_loop``
+(``services/agent_runtime.py``) and the Temporal ``AgentWorkflow``, append a
+tool's serialized result to the conversation, and every later model turn
+re-sends it. An external tool can return far more text than a model needs: a
+single TikHub call returned about 400,000 characters, and a handful of those
+pushed the ``agent.execute_llm_step`` input past Temporal's payload warning
+and the saved conversation past the 1 MB seed cap that ``agent.prepare_payload``
+enforces (docs-internal/errors.md, entry 28).
+
+:func:`bound_tool_output` keeps the first ``limit`` characters of the copy the
+model sees and appends a note saying so. The tool's own result is never
+touched; the cut happens where the loop turns that result into a message.
+
+Stdlib and ``constants`` only, so workflow code can import it freely
+(importing anything under ``services/llm`` runs that package's ``__init__``,
+which reads ``llm_defaults.json``).
+
+Agent-internal channels are exempt (:func:`tool_output_is_capped`): a
+delegated agent's answer, a skill load, and Task Manager results. Each is
+bounded by other means, and cutting one would hand the model a broken brief.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping, Optional, Tuple
+
+from constants import AI_AGENT_TYPES
+
+# Built-in agent tools whose results are never cut. Delegated agents are
+# exempt through ``AI_AGENT_TYPES``.
+_UNCAPPED_TOOL_TYPES = frozenset(
+ {
+ "_builtin_skill",
+ "_builtin_check_delegated_tasks",
+ "taskManager",
+ }
+)
+
+_NOTE_PREFIX = "\n\n[Tool result truncated: showing the first "
+_NOTE = (
+ _NOTE_PREFIX
+ + "{shown:,} of {total:,} characters. Call the tool again with narrower "
+ "parameters to see the rest.]"
+)
+_NOTE_PATTERN = re.compile(
+ re.escape(_NOTE_PREFIX) + r"[\d,]+ of ([\d,]+) characters\.[^\]]*\]"
+)
+
+
+def tool_output_is_capped(node_type: Optional[str]) -> bool:
+ """Whether a result from a tool of ``node_type`` is bounded.
+
+ Unknown or missing types count as external tools, so the exemptions are
+ exactly the listed agent-internal channels.
+ """
+ node_type = str(node_type or "")
+ return node_type not in _UNCAPPED_TOOL_TYPES and node_type not in AI_AGENT_TYPES
+
+
+def bound_tool_output(text: str, limit: Optional[int]) -> str:
+ """Keep the first ``limit`` characters of ``text`` and say what was cut.
+
+ A falsy or negative ``limit`` means no cap. Bounding a result that
+ already carries this note keeps the original total in the new note, so a
+ later, tighter cut still tells the model how much the tool returned.
+ """
+ if not limit or limit <= 0:
+ return text
+ body, total = _split_note(text)
+ if len(body) <= limit:
+ return text
+ return body[:limit] + _NOTE.format(
+ shown=limit,
+ total=total if total is not None else len(body),
+ )
+
+
+def _split_note(text: str) -> Tuple[str, Optional[int]]:
+ """Split a previously bounded result into its kept text and full length."""
+ start = text.rfind(_NOTE_PREFIX)
+ if start < 0:
+ return text, None
+ match = _NOTE_PATTERN.fullmatch(text, start)
+ if match is None:
+ return text, None
+ return text[:start], int(match.group(1).replace(",", ""))
+
+
+def resolve_tool_output_limit(
+ user_settings: Optional[Mapping[str, Any]],
+ settings: Any,
+) -> int:
+ """Per-user ``tool_result_max_chars``, else ``Settings.tool_result_max_chars``.
+
+ Same guard as ``agent_recursion_limit``: only a positive integer in the
+ user's row overrides the env value. ``0`` means no cap.
+ """
+ raw = (user_settings or {}).get("tool_result_max_chars")
+ if isinstance(raw, int) and not isinstance(raw, bool) and raw > 0:
+ return raw
+ try:
+ return max(0, int(getattr(settings, "tool_result_max_chars", 0) or 0))
+ except (TypeError, ValueError):
+ return 0
diff --git a/server/tests/services/test_native_agent_runtime.py b/server/tests/services/test_native_agent_runtime.py
index fba58625..37e2b05d 100644
--- a/server/tests/services/test_native_agent_runtime.py
+++ b/server/tests/services/test_native_agent_runtime.py
@@ -687,3 +687,98 @@ async def test_long_term_retrieval_preserves_execution_context_on_save(
assert append_turns.await_args.kwargs["mutation_id"].startswith(
"ai-memory:" if method_name == "execute_agent" else "chat-memory:"
)
+
+
+def _typed_tool(name: str, node_type: str) -> AgentToolSpec:
+ spec = _tool(name)
+ spec.execution["node_type"] = node_type
+ return spec
+
+
+async def _one_tool_call(tool: AgentToolSpec, result: Any, **loop_kwargs):
+ """Run one tool call through the loop and return the tool message."""
+ call = ToolCall(id="call-1", name=tool.name, args={"value": 1})
+ unifier = _FakeUnifier(
+ [
+ LLMResponse(
+ tool_calls=[call],
+ assistant_message=Message(role="assistant", tool_calls=[call]),
+ ),
+ LLMResponse(content="done"),
+ ]
+ )
+
+ async def execute(_name, _args):
+ return result
+
+ loop = await run_native_agent_loop(
+ unifier,
+ provider="openai",
+ api_key="test",
+ model="gpt-test",
+ temperature=0,
+ max_tokens=100,
+ initial_messages=[Message(role="user", content="go")],
+ tools=[tool],
+ tool_executor=execute,
+ **loop_kwargs,
+ )
+ (tool_message,) = [m for m in loop["messages"] if m.role == "tool"]
+ return tool_message
+
+
+async def test_native_loop_cuts_an_external_tool_result():
+ message = await _one_tool_call(
+ _typed_tool("scrape", "tikhubAction"),
+ {"data": "x" * 5_000},
+ tool_output_limit=1_000,
+ )
+
+ assert "showing the first 1,000 of 5,012 characters" in message.content
+ assert len(message.content) < 1_200
+ assert message.blocks[0].text == message.content
+
+
+async def test_native_loop_keeps_llm_media_when_the_text_is_cut():
+ ref = {
+ "kind": "image",
+ "path": "images/chart.png",
+ "workflow_id": "wf-media",
+ "filename": "chart.png",
+ "mime_type": "image/png",
+ "size_bytes": 1234,
+ }
+ message = await _one_tool_call(
+ _typed_tool("scrape", "tikhubAction"),
+ {"data": "x" * 5_000, "llm_media": [{"ref": ref}]},
+ tool_output_limit=1_000,
+ )
+
+ assert "Tool result truncated" in message.content
+ images = [block for block in message.blocks if block.type == "image"]
+ assert images and images[0].source["ref"]["path"] == "images/chart.png"
+
+
+async def test_native_loop_never_cuts_a_skill_load():
+ message = await _one_tool_call(
+ _typed_tool("Skill", "_builtin_skill"),
+ {"instructions": "i" * 5_000},
+ tool_output_limit=1_000,
+ )
+
+ assert "Tool result truncated" not in message.content
+ assert "i" * 5_000 in message.content
+
+
+async def test_native_loop_without_a_limit_keeps_results_whole():
+ message = await _one_tool_call(
+ _typed_tool("scrape", "tikhubAction"),
+ {"data": "x" * 5_000},
+ )
+
+ assert "Tool result truncated" not in message.content
+ assert "x" * 5_000 in message.content
diff --git a/server/tests/services/test_tool_output.py b/server/tests/services/test_tool_output.py
new file mode 100644
index 00000000..a4152032
--- /dev/null
+++ b/server/tests/services/test_tool_output.py
@@ -0,0 +1,182 @@
+"""What one tool result may add to an agent's conversation.
+
+``services.tool_output`` is shared by the in-process loop and the Temporal
+``AgentWorkflow``. The incident behind it (docs-internal/errors.md, entry 28):
+single TikHub results of about 400,000 characters grew a saved conversation
+past the 1 MB seed cap, and every later firing failed to load it.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from services.tool_output import (
+ bound_tool_output,
+ resolve_tool_output_limit,
+ tool_output_is_capped,
+)
+
+pytestmark = pytest.mark.unit
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+
+
+class TestBoundToolOutput:
+ def test_short_result_is_unchanged(self):
+ assert bound_tool_output("abc", 10) == "abc"
+
+ @pytest.mark.parametrize("limit", [0, None, -1])
+ def test_no_limit_keeps_the_whole_result(self, limit):
+ text = "x" * 500
+ assert bound_tool_output(text, limit) == text
+
+ def test_long_result_keeps_the_head_and_says_what_was_cut(self):
+ text = "a" * 150_000 + "TAIL"
+
+ bounded = bound_tool_output(text, 100_000)
+
+ assert bounded.startswith("a" * 100_000)
+ assert "TAIL" not in bounded
+ assert "showing the first 100,000 of 150,004 characters" in bounded
+ assert "Call the tool again with narrower parameters" in bounded
+
+ def test_the_note_makes_no_promise_about_an_output_panel(self):
+ """Several capped tools hide their Output section, and the panel
+ only ever shows a tool's latest call."""
+ bounded = bound_tool_output("z" * 50, 10)
+
+ assert "panel" not in bounded
+
+ def test_a_tighter_second_cut_keeps_the_original_total(self):
+ once = bound_tool_output("b" * 400_000, 100_000)
+
+ twice = bound_tool_output(once, 20_000)
+
+ assert twice.startswith("b" * 20_000)
+ assert "showing the first 20,000 of 400,000 characters" in twice
+ assert twice.count("[Tool result truncated") == 1
+
+ def test_a_looser_second_cut_is_a_no_op(self):
+ once = bound_tool_output("c" * 50_000, 10_000)
+
+ assert bound_tool_output(once, 10_000) == once
+ assert bound_tool_output(once, 20_000) == once
+
+
+class TestExemptions:
+ @pytest.mark.parametrize(
+ "node_type",
+ ["tikhubAction", "httpRequest", "simpleMemory", "dataSource", "", None],
+ )
+ def test_external_and_unknown_tools_are_capped(self, node_type):
+ assert tool_output_is_capped(node_type) is True
+
+ @pytest.mark.parametrize(
+ "node_type",
+ [
+ "_builtin_skill",
+ "_builtin_check_delegated_tasks",
+ "taskManager",
+ "aiAgent",
+ "orchestrator_agent",
+ "claude_code_agent",
+ "rlm_agent",
+ ],
+ )
+ def test_agent_internal_channels_are_never_cut(self, node_type):
+ assert tool_output_is_capped(node_type) is False
+
+ def test_every_agent_type_is_exempt(self):
+ from constants import AI_AGENT_TYPES
+
+ assert not any(tool_output_is_capped(kind) for kind in AI_AGENT_TYPES)
+
+
+class TestResolveLimit:
+ def test_the_user_setting_wins(self):
+ settings = SimpleNamespace(tool_result_max_chars=100_000)
+
+ limit = resolve_tool_output_limit(
+ {"tool_result_max_chars": 30_000}, settings
+ )
+
+ assert limit == 30_000
+
+ def test_the_env_setting_applies_without_a_user_row(self):
+ settings = SimpleNamespace(tool_result_max_chars=100_000)
+
+ assert resolve_tool_output_limit(None, settings) == 100_000
+
+ @pytest.mark.parametrize("raw", [0, -5, True, "50000", None, 2.5])
+ def test_only_a_positive_integer_overrides_the_env_value(self, raw):
+ settings = SimpleNamespace(tool_result_max_chars=100_000)
+
+ limit = resolve_tool_output_limit(
+ {"tool_result_max_chars": raw}, settings
+ )
+
+ assert limit == 100_000
+
+ def test_a_zero_env_value_disables_the_cap(self):
+ settings = SimpleNamespace(tool_result_max_chars=0)
+
+ assert resolve_tool_output_limit({}, settings) == 0
+
+ def test_settings_without_the_field_disable_the_cap(self):
+ """The AIService tests construct it with ``settings=object()``."""
+ assert resolve_tool_output_limit(None, object()) == 0
+
+
+class TestDefaultParity:
+ """The default is written in four places and two languages.
+
+ ``.env.template`` is canonical; ``Settings`` mirrors it for bare
+ construction, ``UserSettings`` for new rows (and the migration derives
+ the column default from it), and the client schema for the Settings
+ slider. They cannot share a constant, so this test keeps them equal.
+ """
+
+ def test_every_copy_of_the_default_agrees(self):
+ from models.database import UserSettings
+
+ template = (REPO_ROOT / ".env.template").read_text(encoding="utf-8")
+ config = (REPO_ROOT / "server" / "core" / "config.py").read_text(
+ encoding="utf-8"
+ )
+ schema = (
+ REPO_ROOT
+ / "client"
+ / "src"
+ / "components"
+ / "ui"
+ / "settingsPanel"
+ / "schema.ts"
+ ).read_text(encoding="utf-8")
+
+ env_match = re.search(r"^TOOL_RESULT_MAX_CHARS=(\d+)\s*$", template, re.M)
+ config_match = re.search(
+ r"tool_result_max_chars: int = Field\(default=([\d_]+), "
+ r'env="TOOL_RESULT_MAX_CHARS"',
+ config,
+ )
+ schema_match = re.search(
+ r"toolResultMaxChars: z[^,]*?\.default\(([\d_]+)\)", schema, re.S
+ )
+ assert env_match and config_match and schema_match, (
+ "Could not find a copy of the TOOL_RESULT_MAX_CHARS default. If "
+ "one moved, update this extraction; the invariant still holds."
+ )
+
+ copies = {
+ ".env.template": int(env_match.group(1)),
+ "Settings": int(config_match.group(1).replace("_", "")),
+ "UserSettings": int(
+ UserSettings.model_fields["tool_result_max_chars"].default
+ ),
+ "client schema": int(schema_match.group(1).replace("_", "")),
+ }
+ assert len(set(copies.values())) == 1, copies
diff --git a/server/tests/temporal/test_agent_context_pressure.py b/server/tests/temporal/test_agent_context_pressure.py
new file mode 100644
index 00000000..89f2eccb
--- /dev/null
+++ b/server/tests/temporal/test_agent_context_pressure.py
@@ -0,0 +1,467 @@
+"""Transcript-pressure rules for ``AgentWorkflow`` (pure functions).
+
+These rules are recorded behavior: ``context_pressure_version`` in a run's
+prepare-payload result selects them on replay, so a change here needs a new
+version (see the module docstring).
+
+Sizes below are chosen against the wire format: a tool message stores its
+text twice (``content`` and the ``tool_result`` block), so a result of N
+characters costs about 2N bytes.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List
+
+import pytest
+
+from services.llm.protocol import (
+ Message,
+ ToolCall,
+ message_from_wire,
+ message_to_wire,
+)
+from services.temporal.agent_context_pressure import (
+ CHARS_PER_TOKEN,
+ CLEARED_TOOL_RESULT,
+ MIN_CLIPPED_RESULT_CHARS,
+ clear_old_tool_results,
+ clip_latest_turn,
+ earlier_turns_over_budget,
+ has_summarizable_history,
+ projected_request_tokens,
+ request_tokens,
+ summarizer_view,
+ transcript_budget_bytes,
+ transcript_bytes,
+ turn_tool_chars,
+)
+
+pytestmark = pytest.mark.unit
+
+EXTERNAL = {"scrape", "search"}
+
+
+def _is_capped(name):
+ return name in EXTERNAL
+
+
+def _wire(**kwargs) -> Dict[str, Any]:
+ return dict(message_to_wire(Message(**kwargs)))
+
+
+def _assistant(*call_ids: str, tool: str = "scrape") -> Dict[str, Any]:
+ return _wire(
+ role="assistant",
+ tool_calls=[
+ ToolCall(id=call_id, name=tool, args={"q": call_id})
+ for call_id in call_ids
+ ],
+ )
+
+
+def _result(call_id: str, tool: str, size: int) -> Dict[str, Any]:
+ return _wire(
+ role="tool",
+ content="r" * size,
+ tool_call_id=call_id,
+ name=tool,
+ )
+
+
+def _opening(user_chars: int = 0) -> List[Dict[str, Any]]:
+ return [
+ _wire(role="system", content="You are useful."),
+ _wire(role="user", content="h" * user_chars or "Research this."),
+ ]
+
+
+def _turns(*turns) -> List[Dict[str, Any]]:
+ """The opening plus one (assistant, result) pair per ``(tool, size)``."""
+ messages = _opening()
+ for index, (tool, size) in enumerate(turns, start=1):
+ messages.append(_assistant(f"call-{index}", tool=tool))
+ messages.append(_result(f"call-{index}", tool, size))
+ return messages
+
+
+def _one_turn(*sizes, tool: str = "scrape", user_chars: int = 0):
+ """The opening plus ONE turn that called ``tool`` once per size."""
+ call_ids = [f"call-{index}" for index, _ in enumerate(sizes, start=1)]
+ messages = _opening(user_chars)
+ messages.append(_assistant(*call_ids, tool=tool))
+ for call_id, size in zip(call_ids, sizes):
+ messages.append(_result(call_id, tool, size))
+ return messages
+
+
+def _kept(message: Dict[str, Any]) -> str:
+ return message["content"].split("\n\n[Tool result truncated")[0]
+
+
+class TestBudget:
+ def test_budget_is_three_quarters_of_temporal_payload_warning(self):
+ from services.media.limits import TEMPORAL_PAYLOAD_WARN_BYTES
+
+ assert transcript_budget_bytes() == TEMPORAL_PAYLOAD_WARN_BYTES * 3 // 4
+
+ def test_transcript_bytes_matches_the_rollover_guard(self):
+ messages = _turns(("scrape", 100))
+
+ assert transcript_bytes(messages) == len(
+ json.dumps(messages, default=str).encode("utf-8")
+ )
+
+
+class TestClearOldToolResults:
+ def test_under_budget_nothing_changes(self):
+ messages = _turns(("scrape", 1_000))
+ before = [dict(message) for message in messages]
+
+ relief = clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=1_000_000,
+ is_capped=_is_capped,
+ )
+
+ assert messages == before
+ assert relief.changed == 0
+ assert relief.bytes_before == relief.bytes_after
+
+ def test_oldest_results_go_first_and_the_latest_turn_is_kept(self):
+ messages = _turns(("scrape", 20_000), ("scrape", 20_000), ("scrape", 20_000))
+
+ relief = clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=100_000,
+ is_capped=_is_capped,
+ )
+
+ # Half the budget takes both earlier results; the latest turn stays.
+ assert relief.changed == 2
+ assert messages[3]["content"] == CLEARED_TOOL_RESULT
+ assert messages[5]["content"] == CLEARED_TOOL_RESULT
+ assert messages[7]["content"] == "r" * 20_000
+ assert relief.bytes_after <= 50_000
+ assert relief.bytes_after == transcript_bytes(messages)
+
+ def test_clearing_stops_at_half_the_budget(self):
+ messages = _turns(("scrape", 60_000), ("scrape", 10_000), ("scrape", 1_000))
+
+ relief = clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=100_000,
+ is_capped=_is_capped,
+ )
+
+ assert relief.changed == 1
+ assert messages[3]["content"] == CLEARED_TOOL_RESULT
+ assert messages[5]["content"] == "r" * 10_000
+
+ def test_external_results_are_cleared_before_internal_ones(self):
+ messages = _turns(("load_skill", 10_000), ("scrape", 60_000), ("scrape", 100))
+
+ clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=100_000,
+ is_capped=_is_capped,
+ )
+
+ assert messages[3]["content"] == "r" * 10_000 # internal, and older
+ assert messages[5]["content"] == CLEARED_TOOL_RESULT # external
+
+ def test_internal_results_go_when_external_ones_are_not_enough(self):
+ messages = _turns(("load_skill", 60_000), ("scrape", 1_000), ("scrape", 100))
+
+ relief = clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=100_000,
+ is_capped=_is_capped,
+ )
+
+ assert relief.changed == 2
+ assert messages[3]["content"] == CLEARED_TOOL_RESULT
+
+ def test_a_cleared_result_still_answers_its_call(self):
+ messages = _turns(("scrape", 60_000), ("scrape", 100))
+
+ clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=100_000,
+ is_capped=_is_capped,
+ )
+
+ cleared = messages[3]
+ assert cleared["role"] == "tool"
+ assert cleared["tool_call_id"] == "call-1"
+ assert cleared["name"] == "scrape"
+ # The duplicated tool_result block is rebuilt too, so the old text
+ # is really gone from the wire.
+ assert [block["text"] for block in cleared["blocks"]] == [
+ CLEARED_TOOL_RESULT
+ ]
+ assert message_from_wire(cleared).content == CLEARED_TOOL_RESULT
+
+ def test_counts_the_characters_it_removed(self):
+ messages = _turns(("scrape", 60_000), ("scrape", 100))
+
+ relief = clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=100_000,
+ is_capped=_is_capped,
+ )
+
+ assert relief.chars_removed == 60_000 - len(CLEARED_TOOL_RESULT)
+
+ def test_already_cleared_results_are_left_alone(self):
+ messages = _turns(("scrape", 60_000), ("scrape", 100))
+ clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=100_000,
+ is_capped=_is_capped,
+ )
+ after_first = [dict(message) for message in messages]
+
+ relief = clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=1_000,
+ is_capped=_is_capped,
+ )
+
+ assert relief.changed == 0
+ assert messages == after_first
+
+ def test_a_zero_budget_disables_clearing(self):
+ messages = _turns(("scrape", 60_000), ("scrape", 100))
+
+ relief = clear_old_tool_results(
+ messages,
+ turn_start=len(messages) - 2,
+ budget_bytes=0,
+ is_capped=_is_capped,
+ )
+
+ assert relief.changed == 0
+
+
+class TestEarlierTurnsOverBudget:
+ def test_false_within_budget(self):
+ messages = _one_turn(1_000, user_chars=80_000)
+
+ assert (
+ earlier_turns_over_budget(
+ messages,
+ turn_start=2,
+ budget_bytes=1_000_000,
+ size=transcript_bytes(messages),
+ )
+ is False
+ )
+
+ def test_true_when_earlier_turns_hold_more_than_half(self):
+ messages = _one_turn(1_000, user_chars=80_000)
+
+ assert (
+ earlier_turns_over_budget(
+ messages,
+ turn_start=2,
+ budget_bytes=70_000,
+ size=transcript_bytes(messages),
+ )
+ is True
+ )
+
+ def test_false_when_the_latest_turn_is_the_excess(self):
+ messages = _one_turn(80_000)
+
+ assert (
+ earlier_turns_over_budget(
+ messages,
+ turn_start=2,
+ budget_bytes=70_000,
+ size=transcript_bytes(messages),
+ )
+ is False
+ )
+
+
+class TestClipLatestTurn:
+ def test_under_budget_nothing_changes(self):
+ messages = _one_turn(1_000, 1_000)
+ before = [dict(message) for message in messages]
+
+ relief = clip_latest_turn(
+ messages,
+ turn_start=2,
+ budget_bytes=1_000_000,
+ is_capped=_is_capped,
+ )
+
+ assert relief.changed == 0
+ assert messages == before
+
+ def test_several_large_results_are_cut_to_one_length_that_fits(self):
+ messages = _one_turn(100_000, 100_000, 100_000, 100_000)
+
+ relief = clip_latest_turn(
+ messages,
+ turn_start=2,
+ budget_bytes=393_216,
+ is_capped=_is_capped,
+ )
+
+ assert relief.changed == 4
+ assert relief.bytes_after <= 393_216
+ assert relief.bytes_after == transcript_bytes(messages)
+ assert len({len(_kept(message)) for message in messages[3:]}) == 1
+ assert all(
+ "of 100,000 characters" in message["content"]
+ for message in messages[3:]
+ )
+
+ def test_short_results_stay_whole_and_free_their_share(self):
+ messages = _one_turn(1_000, 200_000, 200_000)
+
+ clip_latest_turn(
+ messages,
+ turn_start=2,
+ budget_bytes=393_216,
+ is_capped=_is_capped,
+ )
+
+ assert messages[3]["content"] == "r" * 1_000
+ assert "Tool result truncated" in messages[4]["content"]
+ assert len(_kept(messages[4])) > 90_000
+
+ def test_internal_results_are_never_cut(self):
+ messages = _one_turn(300_000, 300_000, tool="load_skill")
+
+ relief = clip_latest_turn(
+ messages,
+ turn_start=2,
+ budget_bytes=393_216,
+ is_capped=_is_capped,
+ )
+
+ assert relief.changed == 0
+ assert all(
+ message["content"] == "r" * 300_000 for message in messages[3:]
+ )
+
+ def test_earlier_turns_are_left_to_clearing(self):
+ messages = _turns(("scrape", 100_000), ("scrape", 100_000))
+
+ clip_latest_turn(
+ messages,
+ turn_start=4,
+ budget_bytes=250_000,
+ is_capped=_is_capped,
+ )
+
+ assert messages[3]["content"] == "r" * 100_000
+ assert "Tool result truncated" in messages[5]["content"]
+
+ def test_never_cut_below_the_minimum_length(self):
+ # The earlier turns alone overflow the budget, so nothing this turn
+ # does can fit; each result still keeps the minimum.
+ messages = _one_turn(50_000, 50_000, user_chars=400_000)
+
+ relief = clip_latest_turn(
+ messages,
+ turn_start=2,
+ budget_bytes=310_000,
+ is_capped=_is_capped,
+ )
+
+ assert relief.bytes_after > 310_000
+ assert all(
+ len(_kept(message)) == MIN_CLIPPED_RESULT_CHARS
+ for message in messages[3:]
+ )
+
+
+class TestTokenArithmetic:
+ def test_request_tokens_is_the_step_total(self):
+ usage = {
+ "input_tokens": 1_000,
+ "output_tokens": 200,
+ "cache_read_tokens": 50_000,
+ "total_tokens": 51_200,
+ }
+
+ assert request_tokens(usage) == 51_200
+
+ def test_cache_counters_are_never_added_on_top_of_input(self):
+ """OpenAI and Gemini already count cached tokens inside input."""
+ usage = {
+ "input_tokens": 60_000,
+ "output_tokens": 500,
+ "cache_read_tokens": 50_000,
+ "total_tokens": 60_500,
+ }
+
+ assert request_tokens(usage) == 60_500
+
+ def test_request_tokens_falls_back_to_input_plus_output(self):
+ assert request_tokens({"input_tokens": 7, "output_tokens": 3}) == 10
+ assert request_tokens(None) == 0
+ assert request_tokens({"total_tokens": True}) == 0
+
+ def test_projection_adds_the_turn_and_subtracts_what_was_cleared(self):
+ usage = {"total_tokens": 1_000}
+
+ assert projected_request_tokens(usage, 4_000) == 1_000 + 4_000 // CHARS_PER_TOKEN
+ assert projected_request_tokens(usage, -2_000) == 1_000 - 2_000 // CHARS_PER_TOKEN
+ assert projected_request_tokens({}, -10_000) == 0
+
+ def test_turn_tool_chars_counts_only_the_latest_turn(self):
+ messages = _turns(("scrape", 5_000), ("scrape", 700))
+
+ assert turn_tool_chars(messages, len(messages) - 2) == 700
+
+
+class TestSummarization:
+ def test_a_run_before_its_first_turn_has_nothing_to_summarize(self):
+ messages = _turns(("scrape", 100))
+
+ assert has_summarizable_history(messages, 2) is False
+
+ def test_an_earlier_turn_can_be_summarized(self):
+ messages = _turns(("scrape", 100), ("scrape", 100))
+
+ assert has_summarizable_history(messages, 4) is True
+
+ def test_a_previous_summary_alone_is_not_summarized_again(self):
+ messages = [
+ _wire(role="system", content="You are useful."),
+ _wire(role="user", content="## Compacted conversation summary\n..."),
+ _assistant("call-9"),
+ _result("call-9", "scrape", 100),
+ ]
+
+ assert has_summarizable_history(messages, 2) is False
+
+ def test_summarizer_view_keeps_only_what_the_activity_renders(self):
+ messages = _turns(("scrape", 100))
+ messages[2]["provider_state"] = {"provider": "gemini", "payload": {}}
+
+ view = summarizer_view(messages)
+
+ for original, trimmed in zip(messages, view):
+ assert "blocks" not in trimmed
+ assert "provider_state" not in trimmed
+ decoded = message_from_wire(trimmed)
+ assert decoded.role == original["role"]
+ assert decoded.content == original["content"]
+ assert message_from_wire(view[2]).tool_calls[0].name == "scrape"
+ assert message_from_wire(view[3]).tool_call_id == "call-1"
diff --git a/server/tests/temporal/test_agent_workflow.py b/server/tests/temporal/test_agent_workflow.py
index 7f9813a9..cf4eed68 100644
--- a/server/tests/temporal/test_agent_workflow.py
+++ b/server/tests/temporal/test_agent_workflow.py
@@ -1309,3 +1309,45 @@ class TestAgentContinueAsNew:
guard = "delegation_handles or task_manager_delegation_tasks"
assert guard in source
assert source.index(guard) < source.index("workflow.continue_as_new(")
+
+
+class TestTranscriptPressureReplaySafety:
+ """The recorded payload, not a code edit, selects the pressure rules.
+
+ Whether ``agent.compact_context`` is scheduled depends on these rules, so
+ a history recorded before ``context_pressure_version`` existed must replay
+ through the original cumulative gate. Behavior is locked in
+ ``test_agent_workflow_pressure.py``; these guard the selection itself.
+ """
+
+ @staticmethod
+ def _source() -> str:
+ import inspect
+
+ from services.temporal.agent_workflow import AgentWorkflow
+
+ return inspect.getsource(AgentWorkflow.run)
+
+ def test_the_rules_are_selected_by_the_recorded_payload(self):
+ source = self._source()
+
+ assert 'payload.get("context_pressure_version")' in source
+ assert 'payload.get("tool_result_max_chars")' in source
+ assert 'payload.get("transcript_budget_bytes")' in source
+ assert source.count("if pressure_version >= 1:") == 2
+
+ def test_the_original_cumulative_gate_is_kept_for_old_histories(self):
+ source = self._source()
+ section = source[source.index("# ---- Transcript pressure and compaction") :]
+
+ assert 'context_usage_total.get("total_tokens")' in section
+ assert "compact_source = messages" in section
+
+ def test_only_external_results_outside_delegation_are_cut(self):
+ source = self._source()
+ start = source.index("tool_content = _serialise_tool_result(tool_result)")
+ cap = source[start : start + 600]
+
+ assert "not is_delegation" in cap
+ assert 'tool_output_is_capped(tool_info["node_type"])' in cap
+ assert "bound_tool_output(" in cap
diff --git a/server/tests/temporal/test_agent_workflow_pressure.py b/server/tests/temporal/test_agent_workflow_pressure.py
new file mode 100644
index 00000000..102702c6
--- /dev/null
+++ b/server/tests/temporal/test_agent_workflow_pressure.py
@@ -0,0 +1,406 @@
+"""``AgentWorkflow`` under transcript pressure (``context_pressure_version`` 1).
+
+Drives ``AgentWorkflow.run`` in-process with ``workflow.*`` patched, the style
+of ``test_agent_llm_contract.py``. Every test records the messages each LLM
+step was sent: that is what the model saw, and what the conversation store
+saved for the next firing.
+
+The incident these lock (docs-internal/errors.md, entry 28): uncapped tool
+results grew the transcript past Temporal's payload warning, the token gate
+never fired because it summed every request, and the saved conversation
+outgrew the 1 MB seed cap.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any, Dict, List
+from unittest.mock import MagicMock
+
+import pytest
+
+from services.llm.protocol import Message, ToolCall, message_to_wire
+from services.temporal.agent_context_pressure import (
+ CLEARED_TOOL_RESULT,
+ CONTEXT_PRESSURE_VERSION,
+ transcript_bytes,
+)
+
+SCRAPE_ACTIVITY = "node.tikhubAction.v1"
+TRUNCATED = "[Tool result truncated"
+
+
+def _tool(name: str, node_type: str, node_id: str) -> dict:
+ return {
+ "name": name,
+ "definition": {
+ "name": name,
+ "description": f"Run {name}",
+ "parameters": {"type": "object", "properties": {}},
+ },
+ "node_type": node_type,
+ "version": 1,
+ "task_queue": "default",
+ "tool_node_id": node_id,
+ "parameters": {},
+ "tool_info": {"node_id": node_id, "node_type": node_type},
+ }
+
+
+def _payload(**overrides) -> dict:
+ payload = {
+ "node_id": "agent-1",
+ "node_type": "aiAgent",
+ "workflow_id": "graph-1",
+ "session_id": "session-1",
+ "provider": "openai",
+ "model": "test-model",
+ "max_tokens": 100,
+ "temperature": 0,
+ "system_message": "Be useful",
+ "user_prompt": "research the account",
+ "tools": [
+ _tool("scrape", "tikhubAction", "scraper-1"),
+ _tool("Skill", "_builtin_skill", "agent-1_skill_runtime"),
+ ],
+ "memory_node_id": "",
+ "memory_content": "",
+ "memory_window_size": 10,
+ "max_iterations": 10,
+ "thinking_config": None,
+ "compaction_threshold": None,
+ "tool_result_max_chars": 100_000,
+ "transcript_budget_bytes": 393_216,
+ "context_pressure_version": CONTEXT_PRESSURE_VERSION,
+ }
+ payload.update(overrides)
+ return payload
+
+
+def _legacy(payload: dict) -> dict:
+ """The same payload as recorded before the pressure keys existed."""
+ for key in (
+ "tool_result_max_chars",
+ "transcript_budget_bytes",
+ "context_pressure_version",
+ ):
+ payload.pop(key)
+ return payload
+
+
+def _usage(total: int = 110) -> dict:
+ return {"input_tokens": total - 10, "output_tokens": 10, "total_tokens": total}
+
+
+def _tool_turn(*calls, total: int = 110) -> dict:
+ """An LLM step that calls each ``(call_id, tool_name)`` pair."""
+ tool_calls = [ToolCall(id=call_id, name=name, args={}) for call_id, name in calls]
+ return {
+ "kind": "tool_calls",
+ "assistant_message": message_to_wire(
+ Message(role="assistant", tool_calls=tool_calls)
+ ),
+ "calls": [{"id": call_id, "name": name, "args": {}} for call_id, name in calls],
+ "usage": _usage(total),
+ }
+
+
+def _final() -> dict:
+ return {
+ "kind": "final",
+ "content": "done",
+ "thinking": None,
+ "assistant_message": message_to_wire(
+ Message(role="assistant", content="done")
+ ),
+ "usage": _usage(),
+ }
+
+
+def _scraped(chars: int) -> dict:
+ """A tool activity's envelope around a result of about ``chars``."""
+ return {"success": True, "result": {"data": "x" * chars}}
+
+
+class _Run:
+ """Scripted activities for one ``AgentWorkflow.run``."""
+
+ def __init__(self, payload: dict, turns: List[dict], tools: Dict[str, Any]):
+ self.payload = payload
+ self.turns = list(turns)
+ self.tools = tools
+ self.sent: List[List[dict]] = []
+ self.compactions: List[dict] = []
+
+ async def execute_activity(self, name, *, args, **_kwargs):
+ if name == "agent.prepare_payload":
+ return self.payload
+ if name == "agent.broadcast_progress":
+ return {"emitted": True}
+ if name == "agent.execute_llm_step":
+ self.sent.append([dict(message) for message in args[0]["messages"]])
+ return self.turns.pop(0)
+ if name == "agent.compact_context":
+ self.compactions.append(args[0])
+ return {
+ "success": True,
+ "summary": "The account was researched across several calls.",
+ "usage": _usage(40),
+ }
+ if name in self.tools:
+ return self.tools[name]
+ if name in ("agent.store_output", "agent.skill.clear"):
+ return {"ok": True}
+ raise AssertionError(f"Unexpected activity {name}")
+
+
+def patched_workflow(monkeypatch):
+ import services.temporal.agent_workflow as workflow_module
+
+ temporal_workflow = workflow_module.workflow
+ monkeypatch.setattr(temporal_workflow, "logger", MagicMock())
+ monkeypatch.setattr(temporal_workflow, "patched", lambda _patch_id: True)
+ monkeypatch.setattr(
+ temporal_workflow,
+ "info",
+ lambda: SimpleNamespace(workflow_id="agent-run-1", run_id="run-id-12345678"),
+ )
+ monkeypatch.setattr(
+ workflow_module,
+ "get_node_class",
+ lambda _node_type: SimpleNamespace(needs_canvas=False),
+ )
+ return temporal_workflow
+
+
+async def _run(monkeypatch, patched_workflow, run: _Run) -> dict:
+ from services.temporal.agent_workflow import AgentWorkflow
+
+ monkeypatch.setattr(patched_workflow, "execute_activity", run.execute_activity)
+ result = await AgentWorkflow().run({"node_id": "agent-1", "execution_id": "root-1"})
+ assert result["success"] is True, result
+ return result
+
+
+def _tool_messages(messages: List[dict]) -> List[dict]:
+ return [message for message in messages if message.get("role") == "tool"]
+
+
+class TestToolResultCap:
+ @pytest.mark.asyncio
+ async def test_an_external_result_is_cut_before_the_model_reads_it(
+ self, monkeypatch, patched_workflow
+ ):
+ run = _Run(
+ _payload(tool_result_max_chars=1_000),
+ [_tool_turn(("c1", "scrape")), _final()],
+ {SCRAPE_ACTIVITY: _scraped(5_000)},
+ )
+
+ await _run(monkeypatch, patched_workflow, run)
+
+ (result,) = _tool_messages(run.sent[1])
+ assert result["content"].startswith('{"data": "xxx')
+ assert "showing the first 1,000 of 5,012 characters" in result["content"]
+ assert len(result["content"]) < 1_200
+ # The repeated tool_result block carries the cut text, not the whole.
+ assert result["blocks"][0]["text"] == result["content"]
+
+ @pytest.mark.asyncio
+ async def test_skill_loads_are_never_cut(self, monkeypatch, patched_workflow):
+ instructions = {"status": "loaded", "instructions": "i" * 5_000}
+ run = _Run(
+ _payload(tool_result_max_chars=1_000),
+ [_tool_turn(("c1", "Skill")), _final()],
+ {"agent.skill.invoke": instructions},
+ )
+
+ await _run(monkeypatch, patched_workflow, run)
+
+ (result,) = _tool_messages(run.sent[1])
+ assert TRUNCATED not in result["content"]
+ assert "i" * 5_000 in result["content"]
+
+ @pytest.mark.asyncio
+ async def test_a_history_recorded_before_the_cap_keeps_whole_results(
+ self, monkeypatch, patched_workflow
+ ):
+ run = _Run(
+ _legacy(_payload()),
+ [_tool_turn(("c1", "scrape")), _final()],
+ {SCRAPE_ACTIVITY: _scraped(150_000)},
+ )
+
+ await _run(monkeypatch, patched_workflow, run)
+
+ (result,) = _tool_messages(run.sent[1])
+ assert TRUNCATED not in result["content"]
+ assert len(result["content"]) > 150_000
+
+
+class TestClearing:
+ @pytest.mark.asyncio
+ async def test_old_results_are_cleared_and_the_latest_turn_is_kept(
+ self, monkeypatch, patched_workflow
+ ):
+ run = _Run(
+ _payload(transcript_budget_bytes=60_000),
+ [
+ _tool_turn(("c1", "scrape")),
+ _tool_turn(("c2", "scrape")),
+ _tool_turn(("c3", "scrape")),
+ _final(),
+ ],
+ {SCRAPE_ACTIVITY: _scraped(20_000)},
+ )
+
+ await _run(monkeypatch, patched_workflow, run)
+
+ third, fourth = run.sent[2], run.sent[3]
+ assert [m["content"] == CLEARED_TOOL_RESULT for m in _tool_messages(third)] == [
+ True,
+ False,
+ ]
+ assert [m["content"] == CLEARED_TOOL_RESULT for m in _tool_messages(fourth)] == [
+ True,
+ True,
+ False,
+ ]
+ # Every call still has its answer, in order.
+ assert [m["tool_call_id"] for m in _tool_messages(fourth)] == ["c1", "c2", "c3"]
+ assert all(transcript_bytes(sent) <= 60_000 for sent in run.sent)
+ # Clearing is not compaction: no summarizer call was needed.
+ assert run.compactions == []
+
+ @pytest.mark.asyncio
+ async def test_one_turn_over_the_budget_is_cut_to_fit(
+ self, monkeypatch, patched_workflow
+ ):
+ run = _Run(
+ _payload(transcript_budget_bytes=100_000),
+ [
+ _tool_turn(("c1", "scrape"), ("c2", "scrape"), ("c3", "scrape")),
+ _final(),
+ ],
+ {SCRAPE_ACTIVITY: _scraped(40_000)},
+ )
+
+ await _run(monkeypatch, patched_workflow, run)
+
+ results = _tool_messages(run.sent[1])
+ assert len(results) == 3
+ assert all(TRUNCATED in result["content"] for result in results)
+ assert transcript_bytes(run.sent[1]) <= 100_000
+
+
+class TestTokenGate:
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize(
+ ("versioned", "expected_compactions"),
+ [(True, 0), (False, 1)],
+ ids=["next-request", "legacy-running-sum"],
+ )
+ async def test_the_gate_measures_the_next_request_not_a_running_sum(
+ self, monkeypatch, patched_workflow, versioned, expected_compactions
+ ):
+ # Every request is 400 tokens, well under the 1,000 threshold. Only
+ # a running sum of them (the original gate) crosses it, on turn 3.
+ payload = _payload(compaction_threshold=1_000)
+ if not versioned:
+ payload = _legacy(payload)
+ run = _Run(
+ payload,
+ [
+ _tool_turn(("c1", "scrape"), total=400),
+ _tool_turn(("c2", "scrape"), total=400),
+ _tool_turn(("c3", "scrape"), total=400),
+ _final(),
+ ],
+ {SCRAPE_ACTIVITY: _scraped(10)},
+ )
+
+ await _run(monkeypatch, patched_workflow, run)
+
+ assert len(run.compactions) == expected_compactions
+
+
+class TestSummarization:
+ @pytest.mark.asyncio
+ async def test_a_summary_keeps_the_turn_the_model_has_not_read(
+ self, monkeypatch, patched_workflow
+ ):
+ run = _Run(
+ _payload(compaction_threshold=500),
+ [
+ # Over the threshold already, but there is nothing older
+ # than this first turn to summarize: skipped, not failed.
+ _tool_turn(("c1", "scrape"), total=600),
+ _tool_turn(("c2", "scrape"), total=600),
+ _final(),
+ ],
+ {SCRAPE_ACTIVITY: _scraped(10)},
+ )
+
+ await _run(monkeypatch, patched_workflow, run)
+
+ assert len(run.compactions) == 1
+ summarized = run.compactions[0]["messages"]
+ assert [m["role"] for m in summarized] == ["system", "user", "assistant", "tool"]
+ assert all("blocks" not in m and "provider_state" not in m for m in summarized)
+
+ after = run.sent[2]
+ assert [m["role"] for m in after] == ["system", "user", "assistant", "tool"]
+ assert after[0]["content"] == "Be useful"
+ assert after[1]["content"].startswith("## Compacted conversation summary")
+ assert after[1]["content"].endswith("## Current request\nresearch the account")
+ # The latest turn survives verbatim: its call and its unread result.
+ assert after[2]["tool_calls"][0]["id"] == "c2"
+ assert after[3]["tool_call_id"] == "c2"
+ assert "x" * 10 in after[3]["content"]
+
+ @pytest.mark.asyncio
+ async def test_a_text_heavy_history_is_summarized_when_it_overflows(
+ self, monkeypatch, patched_workflow
+ ):
+ # A stored conversation of long messages: no tool results to clear,
+ # so only a summary brings the transcript back under budget.
+ stored = [
+ message_to_wire(Message(role="user", content="q" * 30_000)),
+ message_to_wire(Message(role="assistant", content="a" * 30_000)),
+ ]
+ run = _Run(
+ _payload(
+ compaction_threshold=10**9,
+ transcript_budget_bytes=100_000,
+ conversation=stored,
+ ),
+ [_tool_turn(("c1", "scrape")), _final()],
+ {SCRAPE_ACTIVITY: _scraped(100)},
+ )
+
+ await _run(monkeypatch, patched_workflow, run)
+
+ assert len(run.compactions) == 1
+ assert [m["role"] for m in run.sent[1]] == ["system", "user", "assistant", "tool"]
+ assert transcript_bytes(run.sent[1]) <= 100_000
+
+ @pytest.mark.asyncio
+ async def test_compaction_off_never_summarizes(self, monkeypatch, patched_workflow):
+ stored = [
+ message_to_wire(Message(role="user", content="q" * 30_000)),
+ message_to_wire(Message(role="assistant", content="a" * 30_000)),
+ ]
+ run = _Run(
+ _payload(
+ compaction_threshold=None,
+ transcript_budget_bytes=100_000,
+ conversation=stored,
+ ),
+ [_tool_turn(("c1", "scrape")), _final()],
+ {SCRAPE_ACTIVITY: _scraped(100)},
+ )
+
+ await _run(monkeypatch, patched_workflow, run)
+
+ assert run.compactions == []
diff --git a/server/tests/temporal/test_prepare_payload_pressure.py b/server/tests/temporal/test_prepare_payload_pressure.py
new file mode 100644
index 00000000..9063c82e
--- /dev/null
+++ b/server/tests/temporal/test_prepare_payload_pressure.py
@@ -0,0 +1,215 @@
+"""``agent.prepare_payload`` and the conversation save: the pressure contract.
+
+Calls the activity bodies directly. Collaborators are patched by string path:
+subdirectory conftests can swap the stubbed ``core`` modules for the real
+ones in a whole-suite run, and a string path resolves whichever is loaded.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from temporalio.exceptions import ApplicationError
+
+from services.temporal.agent_activities import (
+ _SEED_TRANSCRIPT_MAX_BYTES,
+ _save_conversation,
+ prepare_agent_payload,
+)
+from services.temporal.agent_context_pressure import (
+ CONTEXT_PRESSURE_VERSION,
+ transcript_budget_bytes,
+)
+
+pytestmark = pytest.mark.unit
+
+_CONTEXT = {
+ "node_id": "agent-1",
+ "node_type": "aiAgent",
+ "workflow_id": "graph-1",
+ "session_id": "session-1",
+ "generation": 1,
+}
+
+_ENV_TOOL_LIMIT = 100_000
+
+
+def _conversation_of(size_bytes: int) -> list:
+ """A stored conversation whose serialized size is exactly ``size_bytes``."""
+ overhead = len(json.dumps([{"role": "user", "content": ""}]).encode("utf-8"))
+ return [{"role": "user", "content": "x" * (size_bytes - overhead)}]
+
+
+def prepare(monkeypatch):
+ """Patch prepare_agent_payload's collaborators; tests steer ``state``."""
+ state = SimpleNamespace(
+ user_settings=None,
+ conversation=[],
+ context_descriptor=None,
+ compaction_service=lambda: None,
+ )
+ database = SimpleNamespace(
+ get_node_parameters=AsyncMock(
+ return_value={
+ "provider": "openai",
+ "model": "test-model",
+ "api_key": "sk-test",
+ "prompt": "hello",
+ }
+ ),
+ get_user_settings=AsyncMock(side_effect=lambda *_a, **_k: state.user_settings),
+ )
+ monkeypatch.setattr(
+ "core.container.container",
+ SimpleNamespace(
+ database=lambda: database,
+ auth_service=lambda: SimpleNamespace(get_api_key=AsyncMock(return_value=None)),
+ ai_service=lambda: SimpleNamespace(),
+ workflow_service=lambda: SimpleNamespace(),
+ ),
+ )
+ monkeypatch.setattr(
+ "core.config.Settings",
+ lambda: SimpleNamespace(
+ max_concurrent_subagents=3,
+ max_delegation_depth=2,
+ agent_recursion_limit=200,
+ tool_result_max_chars=_ENV_TOOL_LIMIT,
+ ),
+ )
+ monkeypatch.setattr(
+ "services.llm.config.is_model_valid_for_provider", lambda *_a: True
+ )
+ monkeypatch.setattr("services.llm.config.resolve_max_tokens", lambda *_a: 1_000)
+ monkeypatch.setattr("services.llm.config.resolve_temperature", lambda *_a: 0.2)
+
+ async def connections(*_args, **_kwargs):
+ return state.context_descriptor, [], [], {}, None
+
+ async def load(*_args, **_kwargs):
+ return state.conversation
+
+ monkeypatch.setattr(
+ "services.plugin.edge_walker.collect_agent_connections", connections
+ )
+ monkeypatch.setattr(
+ "services.compaction.get_compaction_service",
+ lambda: state.compaction_service(),
+ )
+ monkeypatch.setattr("services.agent_context.load_conversation", load)
+ return state
+
+
+class TestPressureControls:
+ @pytest.mark.asyncio
+ async def test_the_run_records_its_pressure_controls(self, prepare):
+ payload = await prepare_agent_payload(dict(_CONTEXT))
+
+ assert payload["tool_result_max_chars"] == _ENV_TOOL_LIMIT
+ assert payload["transcript_budget_bytes"] == transcript_budget_bytes()
+ assert payload["context_pressure_version"] == CONTEXT_PRESSURE_VERSION
+
+ @pytest.mark.asyncio
+ async def test_the_users_tool_limit_beats_the_env_value(self, prepare):
+ prepare.user_settings = {"tool_result_max_chars": 25_000}
+
+ payload = await prepare_agent_payload(dict(_CONTEXT))
+
+ assert payload["tool_result_max_chars"] == 25_000
+
+ @pytest.mark.asyncio
+ async def test_an_unavailable_threshold_is_logged_not_silent(
+ self, prepare, caplog
+ ):
+ def broken():
+ raise RuntimeError("model registry unavailable")
+
+ prepare.compaction_service = broken
+
+ with caplog.at_level(logging.WARNING):
+ payload = await prepare_agent_payload(dict(_CONTEXT))
+
+ assert payload["compaction_threshold"] is None
+ assert "Compaction threshold unavailable" in caplog.text
+
+
+class TestSeedGuard:
+ @pytest.mark.asyncio
+ async def test_a_conversation_at_the_cap_still_loads(self, prepare):
+ prepare.context_descriptor = {"kind": "context"}
+ prepare.conversation = _conversation_of(_SEED_TRANSCRIPT_MAX_BYTES)
+
+ payload = await prepare_agent_payload(dict(_CONTEXT))
+
+ assert payload["conversation"] == prepare.conversation
+
+ @pytest.mark.asyncio
+ async def test_an_oversized_conversation_fails_loudly_with_a_way_out(
+ self, prepare
+ ):
+ prepare.context_descriptor = {"kind": "context"}
+ prepare.conversation = _conversation_of(_SEED_TRANSCRIPT_MAX_BYTES + 1)
+
+ with pytest.raises(ApplicationError) as raised:
+ await prepare_agent_payload(dict(_CONTEXT))
+
+ error = raised.value
+ assert error.type == "ConversationTooLarge"
+ assert error.non_retryable is True
+ assert "Context panel" in error.message
+ assert "Tool Result Limit" in error.message
+ # The Temporal path never reads a per-session compaction override.
+ assert "compaction threshold" not in error.message
+
+
+class TestSaveWarning:
+ @pytest.fixture
+ def saver(self, monkeypatch):
+ save = AsyncMock()
+ monkeypatch.setattr(
+ "core.container.container",
+ SimpleNamespace(database=lambda: SimpleNamespace()),
+ )
+ monkeypatch.setattr("services.agent_context.save_conversation", save)
+ return save
+
+ _PAYLOAD = {
+ "conversation_key": {
+ "workflow_id": "graph-1",
+ "generation": 1,
+ "agent_node_id": "agent-1",
+ }
+ }
+
+ @pytest.mark.asyncio
+ async def test_a_large_save_warns_before_the_next_firing_would_fail(
+ self, saver, caplog
+ ):
+ sent = _conversation_of(_SEED_TRANSCRIPT_MAX_BYTES // 2 + 1)
+
+ with caplog.at_level(logging.WARNING):
+ await _save_conversation(
+ self._PAYLOAD,
+ sent=sent,
+ assistant_wire={"role": "assistant", "content": "done"},
+ )
+
+ assert "over half" in caplog.text
+ saver.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_a_normal_save_is_quiet(self, saver, caplog):
+ with caplog.at_level(logging.WARNING):
+ await _save_conversation(
+ self._PAYLOAD,
+ sent=[{"role": "user", "content": "hi"}],
+ assistant_wire={"role": "assistant", "content": "done"},
+ )
+
+ assert "over half" not in caplog.text
+ saver.assert_awaited_once()