tokencut-proxy 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. tokencut/__init__.py +0 -0
  2. tokencut/cli.py +127 -0
  3. tokencut/contracts.py +148 -0
  4. tokencut/gateway/__init__.py +0 -0
  5. tokencut/gateway/__main__.py +14 -0
  6. tokencut/gateway/adapters/__init__.py +1 -0
  7. tokencut/gateway/adapters/anthropic.py +119 -0
  8. tokencut/gateway/adapters/common.py +95 -0
  9. tokencut/gateway/adapters/gemini.py +107 -0
  10. tokencut/gateway/adapters/openai.py +82 -0
  11. tokencut/gateway/app.py +366 -0
  12. tokencut/gateway/brief.py +101 -0
  13. tokencut/gateway/ccr.py +83 -0
  14. tokencut/gateway/classify.py +41 -0
  15. tokencut/gateway/codeview.py +139 -0
  16. tokencut/gateway/history.py +433 -0
  17. tokencut/gateway/live.html +135 -0
  18. tokencut/gateway/media.py +825 -0
  19. tokencut/gateway/note.py +71 -0
  20. tokencut/gateway/prompt_router.py +214 -0
  21. tokencut/gateway/records.py +312 -0
  22. tokencut/gateway/routing.py +131 -0
  23. tokencut/gateway/session.py +76 -0
  24. tokencut/gateway/task_router.py +157 -0
  25. tokencut/gateway/textcut.py +91 -0
  26. tokencut/gateway/trimmer.py +256 -0
  27. tokencut/gateway/usage.py +120 -0
  28. tokencut/gateway/virtual.py +273 -0
  29. tokencut/graph/__init__.py +0 -0
  30. tokencut/graph/builder.py +307 -0
  31. tokencut/graph/modules.py +149 -0
  32. tokencut/graph/queries.py +106 -0
  33. tokencut/ingestion/__init__.py +0 -0
  34. tokencut/ingestion/base.py +18 -0
  35. tokencut/ingestion/parser.py +36 -0
  36. tokencut/ingestion/python_parser.py +275 -0
  37. tokencut/ingestion/walker.py +68 -0
  38. tokencut/launch.py +104 -0
  39. tokencut/litellm_proxy.py +134 -0
  40. tokencut/pdftool/__init__.py +9 -0
  41. tokencut/pdftool/__main__.py +115 -0
  42. tokencut/pdftool/reader.py +97 -0
  43. tokencut/repoindex/__init__.py +0 -0
  44. tokencut/repoindex/__main__.py +67 -0
  45. tokencut/repoindex/bm25.py +63 -0
  46. tokencut/repoindex/embed.py +93 -0
  47. tokencut/repoindex/index.py +455 -0
  48. tokencut/repoindex/mcp.py +145 -0
  49. tokencut/tokens.py +19 -0
  50. tokencut/trimming/__init__.py +0 -0
  51. tokencut/trimming/packing.py +317 -0
  52. tokencut/trimming/query.py +259 -0
  53. tokencut/trimming/render.py +65 -0
  54. tokencut/trimming/scoring.py +117 -0
  55. tokencut/trimming/variants.py +61 -0
  56. tokencut/userconfig.py +107 -0
  57. tokencut/wizard.py +94 -0
  58. tokencut_proxy-0.1.0.dist-info/METADATA +267 -0
  59. tokencut_proxy-0.1.0.dist-info/RECORD +62 -0
  60. tokencut_proxy-0.1.0.dist-info/WHEEL +5 -0
  61. tokencut_proxy-0.1.0.dist-info/entry_points.txt +2 -0
  62. tokencut_proxy-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,139 @@
1
+ """Trim a Python file that arrived inside a tool result (file read, `cat` output).
2
+
3
+ Uses the Iteration 1 engine (chunker + graph + scorer + tier packer) to decide which
4
+ functions / classes matter for the query, then keeps those **original lines exactly**
5
+ (including the tool's line-number prefixes, e.g. Claude Code's " 12→"). Every gap
6
+ becomes one marker line naming the omitted line range, so the model can read it again.
7
+ Kept lines are never rewritten, so an edit tool's exact-match `old_string` still works.
8
+ """
9
+
10
+ import re
11
+ from dataclasses import dataclass
12
+
13
+ from tokencut.contracts import Chunk, ChunkKind, Tier
14
+ from tokencut.graph.builder import build_graph
15
+ from tokencut.ingestion.python_parser import PythonParser
16
+ from tokencut.tokens import count_tokens
17
+ from tokencut.trimming.query import SYMBOL_WEIGHT, analyse_query
18
+ from tokencut.trimming.variants import generate_variants
19
+
20
+ # " 12→code", "12\tcode", " 12 | code" (prefix kept verbatim, code is what follows)
21
+ _NUMBERED = re.compile(r"^(\s*\d+(?:→|\t| \| |│))(.*)$")
22
+ _NUMBERED_SHARE = 0.8
23
+ MIN_GAP_TOKENS = 60 # a smaller gap is kept as-is: a marker (~25 tokens) would save too little
24
+
25
+
26
+ @dataclass
27
+ class FileView:
28
+ prefixes: list[str] # per line: the tool's line-number prefix ("" if none)
29
+ code: list[str] # per line: the source text
30
+ first_line: int # source line number of code[0] (a read with an offset starts later)
31
+
32
+
33
+ def parse_listing(text: str) -> FileView:
34
+ """Split tool output into line-number prefixes and source lines."""
35
+ lines = text.split("\n")
36
+ while lines and lines[-1] == "":
37
+ lines.pop()
38
+ matches = [_NUMBERED.match(line) for line in lines]
39
+ numbered = sum(1 for m in matches if m)
40
+ if lines and numbered / len(lines) >= _NUMBERED_SHARE:
41
+ prefixes = [m.group(1) if m else "" for m in matches]
42
+ code = [m.group(2) if m else line for m, line in zip(matches, lines)]
43
+ first = next((m for m in matches if m), None)
44
+ first_line = int(re.sub(r"\D", "", first.group(1))) if first else 1
45
+ return FileView(prefixes, code, first_line)
46
+ return FileView([""] * len(lines), lines, 1)
47
+
48
+
49
+ def _own_lines(chunk: Chunk, chunks: list[Chunk], n_lines: int) -> set[int]:
50
+ """1-based line numbers (within the listing) that belong to this chunk alone."""
51
+ if chunk.kind == ChunkKind.MODULE:
52
+ covered = set()
53
+ for c in chunks:
54
+ if c.kind in (ChunkKind.FUNCTION, ChunkKind.CLASS):
55
+ covered.update(range(c.start_line, c.end_line + 1))
56
+ return set(range(1, n_lines + 1)) - covered
57
+ lines = set(range(chunk.start_line, chunk.end_line + 1))
58
+ if chunk.kind == ChunkKind.CLASS:
59
+ for c in chunks:
60
+ if c.parent_id == chunk.id:
61
+ lines -= set(range(c.start_line, c.end_line + 1))
62
+ return lines
63
+
64
+
65
+ def select_lines(code: str, path: str, query: str, tier: Tier) -> set[int] | None:
66
+ """Line numbers (1-based within `code`) to keep for this tier; None = keep everything."""
67
+ chunks = PythonParser().parse_file(path or "file.py", code.encode("utf-8"))
68
+ if len([c for c in chunks if c.kind != ChunkKind.MODULE]) < 2:
69
+ return None # nothing to choose between
70
+ variants = generate_variants(chunks, build_graph(chunks), query)
71
+ variant = next(v for v in variants if v.tier == tier)
72
+ by_id = {c.id: c for c in chunks}
73
+ n_lines = len(code.split("\n"))
74
+ keep: set[int] = set()
75
+ for cid in variant.kept_chunk_ids:
76
+ keep |= _own_lines(by_id[cid], chunks, n_lines)
77
+ for cid in variant.skeleton_chunk_ids: # signature lines only; the body becomes a marker
78
+ keep |= _signature_lines(by_id[cid])
79
+ # Code the query names (or a traceback points into) is always kept whole, like a file the
80
+ # user named: the packer may drop it for being bigger than the tier budget or for losing
81
+ # the budget to higher-ranked neighbours (step D, DECISIONS change log).
82
+ for cid in named_chunk_ids(chunks, query):
83
+ keep |= _own_lines(by_id[cid], chunks, n_lines)
84
+ parent = by_id.get(by_id[cid].parent_id or "")
85
+ if parent is not None:
86
+ keep |= _signature_lines(parent)
87
+ return keep
88
+
89
+
90
+ def named_chunk_ids(chunks: list[Chunk], query: str) -> list[str]:
91
+ """Functions / classes / methods the query names by symbol or a traceback points into."""
92
+ mentions = analyse_query(query, chunks)
93
+ kinds = {c.id: c.kind for c in chunks}
94
+ return [
95
+ cid
96
+ for cid, weight in mentions.weights.items()
97
+ if weight >= SYMBOL_WEIGHT and kinds.get(cid) != ChunkKind.MODULE
98
+ ]
99
+
100
+
101
+ def _signature_lines(chunk: Chunk) -> set[int]:
102
+ return set(range(chunk.start_line, chunk.start_line + chunk.signature.count("\n") + 1))
103
+
104
+
105
+ def render(view: FileView, keep: set[int], path: str) -> str:
106
+ """Kept lines verbatim; each run of dropped lines -> one marker (blank-only runs kept)."""
107
+ out: list[str] = []
108
+ name = path or "this file"
109
+ i, n = 0, len(view.code)
110
+ while i < n:
111
+ if (i + 1) in keep:
112
+ out.append(view.prefixes[i] + view.code[i])
113
+ i += 1
114
+ continue
115
+ j = i
116
+ while j < n and (j + 1) not in keep:
117
+ j += 1
118
+ gap = view.code[i:j]
119
+ if all(not line.strip() for line in gap) or count_tokens("\n".join(gap)) < MIN_GAP_TOKENS:
120
+ out.extend(view.prefixes[k] + view.code[k] for k in range(i, j))
121
+ else:
122
+ first, last = view.first_line + i, view.first_line + j - 1
123
+ indent = re.match(r"\s*", next(line for line in gap if line.strip())).group(0)
124
+ out.append(
125
+ f"{indent}[TokenCut: lines {first}-{last} of {name} omitted "
126
+ f"({count_tokens(chr(10).join(gap))} tokens); read them again if needed]"
127
+ )
128
+ i = j
129
+ return "\n".join(out)
130
+
131
+
132
+ def trim_file_listing(text: str, path: str, query: str, tier: Tier) -> str | None:
133
+ """Trimmed listing, or None if trimming would not help (not Python, too small, no gain)."""
134
+ view = parse_listing(text)
135
+ keep = select_lines("\n".join(view.code), path, query, tier)
136
+ if keep is None:
137
+ return None
138
+ result = render(view, keep, path)
139
+ return result if count_tokens(result) < count_tokens(text) else None
@@ -0,0 +1,433 @@
1
+ """Cache-event trimming: re-trim the whole history when the prompt cache is lost anyway.
2
+
3
+ Normal turns: only newly arrived tool results are trimmed (trimmer.trim_request), and
4
+ every earlier decision is re-applied unchanged, so the cached prefix stays identical.
5
+
6
+ Cache events (model switch, cache expired, context nearly full): the provider re-reads
7
+ the whole prompt at full price anyway, so TokenCut also shrinks old history:
8
+ * old command / test / search output -> one-line note + its error lines
9
+ * an old file read -> a note (newer read later / file edited since / read again)
10
+ * optional: tool definitions -> only tools used so far + core tools
11
+ The most recent turns are never touched. Decisions are remembered (session.py) and sent
12
+ identically until the next event. A file the agent re-reads after we removed an old read
13
+ of it is protected from then on.
14
+
15
+ Task masking (R10, opt-in): when the user starts a new task, the previous tasks' large tool
16
+ outputs become the same kind of note. The agent saw them whole while it worked on them.
17
+ Unlike an event this breaks the cache from the first changed output on, so it is done only
18
+ when the cache reads saved on later requests outweigh that one-time rewrite.
19
+ """
20
+
21
+ import copy
22
+ import json
23
+ import re
24
+ import time
25
+ from dataclasses import dataclass
26
+
27
+ from tokencut.contracts import Segment, SegmentKind, Tier, ToolResultKind
28
+ from tokencut.gateway.adapters.common import lookup, set_text
29
+ from tokencut.gateway.ccr import with_ref
30
+ from tokencut.gateway.session import ConversationState, SessionStore, conversation_key, fingerprint
31
+ from tokencut.gateway.textcut import _ERROR
32
+ from tokencut.gateway.trimmer import (
33
+ _REMINDER,
34
+ TrimConfig,
35
+ TrimReport,
36
+ _call_path,
37
+ _is_edit_call,
38
+ _same_file,
39
+ trim_request,
40
+ )
41
+ from tokencut.tokens import count_tokens
42
+
43
+ # Recent turns (assistant messages, counted from the end) kept exactly as they are.
44
+ KEEP_RECENT_TURNS = {Tier.AGGRESSIVE: 2, Tier.MODERATE: 4, Tier.CONSERVATIVE: 8, Tier.FULL: 10**9}
45
+ MAX_KEY_LINES = 10 # error lines kept in a note about removed output
46
+ # Claude Code / Gemini CLI / common agent tools always offered when pruning tool definitions.
47
+ DEFAULT_CORE_TOOLS = (
48
+ "Read", "Edit", "MultiEdit", "Write", "Bash", "Grep", "Glob", "LS", "TodoWrite", "Task",
49
+ "read_file", "write_file", "replace", "run_shell_command", "search_file_content", "glob",
50
+ "list_directory", "apply_patch", "str_replace_editor", "str_replace_based_edit_tool",
51
+ "mcp__tokencut__repo_map", "mcp__tokencut__find_code", "mcp__tokencut__symbol",
52
+ )
53
+ _ONE_HOUR_TTL = re.compile(r'"ttl"\s*:\s*"1h"')
54
+ # Provider prices relative to uncached input (Anthropic): a cache read ~0.1x, a write ~1.25x.
55
+ CACHE_READ_PRICE = 0.1
56
+ CACHE_WRITE_PRICE = 1.25
57
+
58
+
59
+ @dataclass
60
+ class CacheEventConfig:
61
+ cache_ttl_seconds: int = 300 # provider default; requests marked ttl "1h" use 3600
62
+ compact_at_tokens: int = 110_000 # proxy tokens (~165k Claude tokens): context nearly full
63
+ compact_growth_tokens: int = 20_000 # re-trigger "nearly full" only after this much growth
64
+ history_min_tokens: int = 200 # older results smaller than this are left alone
65
+ prune_tools: bool = False # opt-in: fewer tool definitions at events
66
+ core_tools: tuple[str, ...] = DEFAULT_CORE_TOOLS
67
+ task_masking: bool = True # R10 (on by default since P1): mask finished tasks' outputs at a new task
68
+ task_mask_min_tokens: int = 300 # (tunable) smaller outputs are left alone
69
+ task_min_expected_requests: int = 20 # (tunable) assume at least this many requests follow
70
+
71
+
72
+ # ---------- event detection ----------
73
+
74
+
75
+ def detect_event(state: ConversationState | None, model: str, now: float, total_tokens: int,
76
+ body: dict, config: CacheEventConfig) -> str | None:
77
+ if state is None:
78
+ return None # first time we see this conversation: its cache may still be valid
79
+ ttl = 3600 if _ONE_HOUR_TTL.search(json.dumps(body.get("system", ""))) else config.cache_ttl_seconds
80
+ if model and state.model and model != state.model:
81
+ # Each model has its own cache: only a model not used here within the TTL starts cold.
82
+ seen = dict(state.model_seen)
83
+ seen.setdefault(state.model, state.last_seen)
84
+ if model not in seen or now - seen[model] > ttl:
85
+ return "model_switch"
86
+ if now - state.last_seen > ttl:
87
+ return "cache_expired"
88
+ if total_tokens >= config.compact_at_tokens and (
89
+ state.last_event_tokens is None
90
+ or total_tokens - state.last_event_tokens >= config.compact_growth_tokens
91
+ ):
92
+ return "context_full"
93
+ return None
94
+
95
+
96
+ # ---------- what each tool result is ----------
97
+
98
+
99
+ @dataclass
100
+ class _ResultInfo:
101
+ seg: Segment
102
+ position: int # index in the segment list
103
+ path: str # file the producing call was about ("" if none)
104
+ call_input: str
105
+ call_name: str
106
+
107
+
108
+ def _scan(segments: list[Segment]) -> tuple[list[_ResultInfo], list[tuple[int, str]]]:
109
+ """Tool results with their producing call, and (position, path) of every edit call."""
110
+ calls: dict[str, tuple[str, str]] = {}
111
+ last_by_name: dict[str, str] = {}
112
+ results: list[_ResultInfo] = []
113
+ edits: list[tuple[int, str]] = []
114
+ for pos, seg in enumerate(segments):
115
+ if seg.kind == SegmentKind.TOOL_CALL:
116
+ calls[seg.tool_call_id] = (seg.tool_name, seg.text)
117
+ last_by_name[seg.tool_name] = seg.tool_call_id
118
+ if _is_edit_call(seg.tool_name, seg.text):
119
+ path = _call_path(seg.text)
120
+ if path:
121
+ edits.append((pos, path))
122
+ elif seg.kind == SegmentKind.TOOL_RESULT:
123
+ call_id = seg.tool_call_id or last_by_name.get(seg.tool_name, "")
124
+ name, call_input = calls.get(call_id, (seg.tool_name, ""))
125
+ # An edit call's result ("file updated") is not a read of the file.
126
+ path = "" if _is_edit_call(name, call_input) else _call_path(call_input)
127
+ results.append(_ResultInfo(seg, pos, path, call_input, name))
128
+ return results, edits
129
+
130
+
131
+ def _recent_from(segments: list[Segment], keep_turns: int) -> int:
132
+ """Message index from which messages count as recent (never re-trimmed)."""
133
+ assistant_messages = sorted({s.message_index for s in segments
134
+ if s.role in ("assistant", "model") and s.message_index >= 0})
135
+ if len(assistant_messages) <= keep_turns:
136
+ return 0
137
+ return assistant_messages[-keep_turns]
138
+
139
+
140
+ def _command_label(call_input: str) -> str:
141
+ try:
142
+ data = json.loads(call_input)
143
+ except ValueError:
144
+ return ""
145
+ if isinstance(data, dict):
146
+ for key in ("command", "cmd", "pattern", "query", "path"):
147
+ value = data.get(key)
148
+ if isinstance(value, list):
149
+ value = " ".join(map(str, value))
150
+ if isinstance(value, str) and value:
151
+ return value if len(value) <= 80 else value[:77] + "..."
152
+ return ""
153
+
154
+
155
+ def _output_note(info: _ResultInfo) -> str:
156
+ what = {ToolResultKind.SEARCH: "search results", ToolResultKind.FILE_READ: "file content"}.get(
157
+ info.seg.result_kind, "output")
158
+ label = _command_label(info.call_input)
159
+ head = f"[TokenCut: earlier {what}"
160
+ head += f" of `{label}`" if label else (f" of {info.call_name}" if info.call_name else "")
161
+ head += f" removed ({info.seg.token_count} tokens)"
162
+ lines = [line for line in info.seg.text.split("\n") if line.strip()]
163
+ key = [line for line in lines if _ERROR.search(line)][:MAX_KEY_LINES]
164
+ if lines and lines[-1] not in key:
165
+ key.append(lines[-1]) # usually the summary ("3 failed, 40 passed")
166
+ if not key:
167
+ return head + "]"
168
+ return head + ". Key lines:]\n" + "\n".join(line[:300] for line in key)
169
+
170
+
171
+ def _note(info: _ResultInfo, later: list[_ResultInfo], edits: list[tuple[int, str]]) -> tuple[str, str]:
172
+ """(note, how) replacing an old tool result. `later` = results after it in the request."""
173
+ seg, path = info.seg, info.path
174
+ if not path:
175
+ return _output_note(info), "history_old_output"
176
+ removed = f"[TokenCut: earlier read of {path} removed ({seg.token_count} tokens); "
177
+ if any(r.path and _same_file(r.path, path) for r in later):
178
+ return removed + "a newer read of this file appears later in the conversation]", \
179
+ "history_duplicate_read"
180
+ if any(pos > info.position and _same_file(p, path) for pos, p in edits):
181
+ return removed + "the file was edited afterwards, read it again for the current version]", \
182
+ "history_stale_read"
183
+ if seg.result_kind == ToolResultKind.FILE_READ:
184
+ return removed + "read it again if needed]", "history_old_read"
185
+ return _output_note(info), "history_old_output"
186
+
187
+
188
+ def _history_replacements(segments: list[Segment], state: ConversationState,
189
+ config: CacheEventConfig, keep_turns: int,
190
+ ccr: bool = False) -> dict[str, tuple[str, str]]:
191
+ """fingerprint -> (replacement text, how) for old tool results, decided at an event."""
192
+ results, edits = _scan(segments)
193
+ recent_from = _recent_from(segments, keep_turns)
194
+ decided: dict[str, tuple[str, str]] = {}
195
+ for i, info in enumerate(results):
196
+ seg = info.seg
197
+ if seg.message_index >= recent_from or seg.token_count < config.history_min_tokens:
198
+ continue
199
+ fp = fingerprint(seg)
200
+ if fp in state.pinned:
201
+ continue # already decided at an earlier event: keep it identical
202
+ if info.path and any(_same_file(info.path, p) for p in state.protected_paths):
203
+ continue
204
+ note, how = _note(info, results[i + 1:], edits)
205
+ if ccr:
206
+ note = with_ref(note, seg.text)
207
+ if info.path:
208
+ state.masked_paths.add(info.path)
209
+ if count_tokens(note) < seg.token_count:
210
+ decided[fp] = (note, how)
211
+ return decided
212
+
213
+
214
+ # ---------- R10: a new task masks the finished tasks' outputs ----------
215
+
216
+
217
+ def _real_user_positions(segments: list[Segment]) -> list[int]:
218
+ """Position of the first user text of each task (not tool results, not reminders).
219
+
220
+ A task starts only where the agent had finished its turn: the user text comes before any
221
+ assistant message, or after an assistant message without tool calls. Text that arrives
222
+ after a tool call is context the agent injects between steps (Claude Code 2.1 adds e.g.
223
+ "The following skills are available ..." without a <system-reminder> wrapper)."""
224
+ positions: list[int] = []
225
+ turn_open = True # may a new task start here?
226
+ last_assistant = None
227
+ for pos, s in enumerate(segments):
228
+ if s.role in ("assistant", "model") and s.message_index >= 0:
229
+ if s.message_index != last_assistant:
230
+ last_assistant = s.message_index
231
+ turn_open = True
232
+ if s.kind == SegmentKind.TOOL_CALL:
233
+ turn_open = False
234
+ elif (s.kind == SegmentKind.USER_TEXT and turn_open
235
+ and _REMINDER.sub("", s.text).strip()):
236
+ positions.append(pos)
237
+ turn_open = False # one task start per finished turn
238
+ return positions
239
+
240
+
241
+ def _task_replacements(segments: list[Segment], state: ConversationState,
242
+ config: CacheEventConfig, task_start: int,
243
+ ccr: bool = False) -> dict[str, tuple[str, str]]:
244
+ """fingerprint -> (note, "task_masked") for large tool results before `task_start`.
245
+
246
+ Masking changes cached history, so the request is re-cached from the first masked
247
+ result to the new task (once, at the write price). It saves that many tokens of cache
248
+ reads on every later request. Mask only if the expected saving is the larger one.
249
+ """
250
+ results, edits = _scan(segments)
251
+ candidates: dict[str, tuple[str, _ResultInfo]] = {}
252
+ for i, info in enumerate(results):
253
+ seg = info.seg
254
+ if info.position >= task_start or seg.token_count < config.task_mask_min_tokens:
255
+ continue
256
+ fp = fingerprint(seg)
257
+ if fp in state.pinned:
258
+ continue # decided earlier: stays identical
259
+ if info.path and any(_same_file(info.path, p) for p in state.protected_paths):
260
+ continue
261
+ note, _ = _note(info, results[i + 1:], edits)
262
+ if ccr:
263
+ note = with_ref(note, seg.text)
264
+ if count_tokens(note) < seg.token_count:
265
+ candidates[fp] = (note, info)
266
+ if not candidates:
267
+ return {}
268
+
269
+ removed = sum(info.seg.token_count - count_tokens(note) for note, info in candidates.values())
270
+ first = min(info.position for _, info in candidates.values())
271
+ rewrite = 0 # tokens re-cached once: from the first masked result up to the new task
272
+ for seg in segments[first:task_start]:
273
+ fp = fingerprint(seg)
274
+ if fp in candidates:
275
+ rewrite += count_tokens(candidates[fp][0])
276
+ elif fp in state.pinned:
277
+ rewrite += count_tokens(state.pinned[fp])
278
+ else:
279
+ rewrite += seg.token_count
280
+ # A masked result is not re-sent for the rest of the session. Its length is unknown, so a
281
+ # session that already lasted N requests is assumed to last about N more (with a floor).
282
+ expected = max(config.task_min_expected_requests, state.requests)
283
+ if CACHE_READ_PRICE * removed * expected < (CACHE_WRITE_PRICE - CACHE_READ_PRICE) * rewrite:
284
+ return {} # the one-time cache rewrite would cost more than it saves
285
+ for _, info in candidates.values():
286
+ if info.path:
287
+ state.masked_paths.add(info.path)
288
+ return {fp: (note, "task_masked") for fp, (note, _) in candidates.items()}
289
+
290
+
291
+ # ---------- tool definitions ----------
292
+
293
+
294
+ def _tool_lists(body: dict) -> list[tuple[list, str]]:
295
+ """(list of tool definitions, how to read a name) for each provider format."""
296
+ tools = body.get("tools")
297
+ if isinstance(tools, list) and tools and all(isinstance(t, dict) for t in tools):
298
+ if any("functionDeclarations" in t or "function_declarations" in t for t in tools):
299
+ out = []
300
+ for t in tools:
301
+ decls = t.get("functionDeclarations", t.get("function_declarations"))
302
+ if isinstance(decls, list):
303
+ out.append((decls, "name"))
304
+ return out
305
+ if any("function" in t for t in tools):
306
+ return [(tools, "function.name")]
307
+ return [(tools, "name")]
308
+ if isinstance(body.get("functions"), list):
309
+ return [(body["functions"], "name")]
310
+ return []
311
+
312
+
313
+ def _tool_name(tool: dict, how: str) -> str:
314
+ if how == "function.name":
315
+ return str((tool.get("function") or {}).get("name", ""))
316
+ return str(tool.get("name", ""))
317
+
318
+
319
+ def _forced_tool(body: dict) -> str:
320
+ choice = body.get("tool_choice")
321
+ if isinstance(choice, dict):
322
+ return str(choice.get("name") or (choice.get("function") or {}).get("name", ""))
323
+ return ""
324
+
325
+
326
+ def _prune_tools(body: dict, keep: set[str]) -> int:
327
+ """Remove tool definitions not in `keep` (in place). Returns tokens removed."""
328
+ removed = 0
329
+ for tool_list, how in _tool_lists(body):
330
+ kept = []
331
+ for tool in tool_list:
332
+ name = _tool_name(tool, how)
333
+ if not name or name in keep:
334
+ kept.append(tool)
335
+ else:
336
+ removed += count_tokens(json.dumps(tool, ensure_ascii=False, sort_keys=True))
337
+ tool_list[:] = kept
338
+ return removed
339
+
340
+
341
+ # ---------- the whole request ----------
342
+
343
+
344
+ def trim_with_cache_events(provider: str, model: str, body: dict, segments: list[Segment],
345
+ config: TrimConfig, events_config: CacheEventConfig,
346
+ store: SessionStore, now: float | None = None,
347
+ total_tokens: int | None = None) -> tuple[dict | None, TrimReport, str | None]:
348
+ """Returns (new body or None, report, cache event or None)."""
349
+ now = time.time() if now is None else now
350
+ total = total_tokens if total_tokens is not None else sum(s.token_count for s in segments)
351
+ new_body, report = trim_request(body, segments, config) # on-arrival trims (cache-safe)
352
+ key = conversation_key(provider, segments)
353
+ if key is None:
354
+ return new_body, report, None
355
+
356
+ with store.lock:
357
+ state = store.get(key)
358
+ event = detect_event(state, model, now, total, body, events_config)
359
+ first_sight = state is None
360
+ if state is None:
361
+ state = ConversationState(model=model, last_seen=now)
362
+ user_positions = _real_user_positions(segments)
363
+
364
+ # A new read of a file we removed earlier: the agent needs it, protect it from now on.
365
+ results, _ = _scan(segments)
366
+ for info in results:
367
+ if info.path and fingerprint(info.seg) not in state.pinned and any(
368
+ _same_file(info.path, p) for p in state.masked_paths
369
+ ):
370
+ state.protected_paths.add(info.path)
371
+
372
+ if event is not None:
373
+ decided = _history_replacements(segments, state, events_config,
374
+ KEEP_RECENT_TURNS[config.tier], config.ccr)
375
+ for fp, (text, _) in decided.items():
376
+ state.pinned[fp] = text
377
+ if events_config.prune_tools:
378
+ used = {s.tool_name for s in segments if s.kind == SegmentKind.TOOL_CALL}
379
+ state.kept_tools = sorted(set(events_config.core_tools) | used)
380
+ state.events += 1
381
+ state.last_event_tokens = total
382
+ elif (events_config.task_masking and not first_sight and user_positions
383
+ and len(user_positions) > state.user_turns):
384
+ # R10: the user started a new task; its own outputs are still to come.
385
+ decided = _task_replacements(segments, state, events_config, user_positions[-1],
386
+ config.ccr)
387
+ for fp, (text, _) in decided.items():
388
+ state.pinned[fp] = text
389
+ else:
390
+ decided = {}
391
+
392
+ # Re-apply every remembered decision (identical text every turn = cache stays valid).
393
+ on_arrival = {d["segment"]: d for d in report.trimmed}
394
+ for seg in segments:
395
+ fp = fingerprint(seg)
396
+ if fp not in state.pinned or not isinstance(lookup(body, seg.path), str):
397
+ continue
398
+ text = state.pinned[fp]
399
+ if new_body is None:
400
+ new_body = copy.deepcopy(body)
401
+ set_text(new_body, seg.path, text)
402
+ after = count_tokens(text)
403
+ how = decided[fp][1] if fp in decided else "history_pinned"
404
+ earlier = on_arrival.pop(seg.id, None)
405
+ if earlier is not None: # the history decision replaces the on-arrival trim
406
+ report.trimmed.remove(earlier)
407
+ report.tokens_before -= earlier["before"]
408
+ report.tokens_after -= earlier["after"]
409
+ report.tokens_before += seg.token_count
410
+ report.tokens_after += after
411
+ report.trimmed.append({"segment": seg.id, "how": how, "tool": seg.tool_name,
412
+ "before": seg.token_count, "after": after})
413
+
414
+ if state.kept_tools is not None:
415
+ keep = set(state.kept_tools) | {_forced_tool(body)}
416
+ if new_body is None:
417
+ new_body = copy.deepcopy(body)
418
+ removed = _prune_tools(new_body, keep)
419
+ if removed:
420
+ report.tokens_before += removed
421
+ report.trimmed.append({"segment": "tools", "how": "tools_pruned",
422
+ "tool": "", "before": removed, "after": 0})
423
+ elif new_body == body:
424
+ new_body = None
425
+
426
+ state.model = model or state.model
427
+ state.last_seen = now
428
+ if model:
429
+ state.model_seen[model] = now
430
+ state.user_turns = len(user_positions)
431
+ state.requests += 1
432
+ store.put(key, state)
433
+ return new_body, report, event