pantheon-opencode 1.6.0-beta.9 → 1.6.0

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 (131) hide show
  1. package/AGENTS.global.md +118 -0
  2. package/AGENTS.md +18 -168
  3. package/CHANGELOG.md +126 -376
  4. package/README.md +83 -610
  5. package/README.pt-BR.md +120 -345
  6. package/bin/pantheon-init.mjs +366 -132
  7. package/commands/pantheon-deepwork.md +14 -3
  8. package/commands/pantheon-vision.md +61 -12
  9. package/package.json +19 -11
  10. package/plugin.json +1 -1
  11. package/pyproject.toml +6 -2
  12. package/scripts/_pantheon_paths.py +24 -0
  13. package/scripts/build-agents-md.mjs +368 -69
  14. package/scripts/changelog-merge.mjs +161 -0
  15. package/scripts/check-plugin-v2-coverage.mjs +11 -8
  16. package/scripts/docs-check-changelog.mjs +204 -0
  17. package/scripts/docs-link-check.mjs +314 -0
  18. package/scripts/docs-media.mjs +157 -0
  19. package/scripts/doctor.mjs +828 -40
  20. package/scripts/install/agents-md.mjs +2 -2
  21. package/scripts/install/backup.mjs +648 -0
  22. package/scripts/install/cli-ui.mjs +303 -72
  23. package/scripts/install/component-selection.mjs +61 -0
  24. package/scripts/install/config-migration.mjs +583 -27
  25. package/scripts/install/exit-codes.mjs +26 -0
  26. package/scripts/install/file-inventory.mjs +555 -0
  27. package/scripts/install/health-check.mjs +31 -25
  28. package/scripts/install/interactive.mjs +78 -383
  29. package/scripts/install/migrate.mjs +49 -25
  30. package/scripts/install/model-picker.mjs +218 -250
  31. package/scripts/install/opencode-version.mjs +83 -21
  32. package/scripts/install/opencode.mjs +1413 -154
  33. package/scripts/install/plan-artifact.mjs +517 -0
  34. package/scripts/install/plan.mjs +475 -0
  35. package/scripts/install/plugin.mjs +214 -27
  36. package/scripts/install/prompt-result.mjs +2 -0
  37. package/scripts/install/shared.mjs +256 -99
  38. package/scripts/install/state.mjs +63 -8
  39. package/scripts/install/strings.mjs +60 -4
  40. package/scripts/install/venv.mjs +90 -47
  41. package/scripts/install/verify.mjs +128 -0
  42. package/scripts/install/vision-prompt.mjs +173 -0
  43. package/scripts/install-mcp.mjs +2 -2
  44. package/scripts/manifest-inventory.mjs +49 -3
  45. package/scripts/mcp_persistence.py +1535 -1050
  46. package/scripts/memory_mcp.py +12 -843
  47. package/scripts/node-engine-policy.mjs +85 -0
  48. package/scripts/package-evidence.mjs +10 -2
  49. package/scripts/postinstall.mjs +26 -26
  50. package/scripts/probe-pantheon-cost.mjs +118 -19
  51. package/scripts/prune.mjs +9 -3
  52. package/scripts/reconcile.mjs +325 -0
  53. package/scripts/release-gates.mjs +682 -0
  54. package/scripts/restore.mjs +222 -0
  55. package/scripts/run-node-tests.mjs +24 -8
  56. package/scripts/sync-artifacts.mjs +19 -7
  57. package/scripts/sync-tui.mjs +5 -1
  58. package/scripts/test-opencode-v2-sandbox.sh +36 -123
  59. package/scripts/uninstall.mjs +369 -34
  60. package/scripts/update.mjs +164 -0
  61. package/scripts/validate-node-engine-policy.mjs +13 -0
  62. package/scripts/version-check.mjs +34 -1
  63. package/scripts/versioning.mjs +23 -3
  64. package/scripts/vision-status.mjs +682 -0
  65. package/skills-lock.json +8 -8
  66. package/src/agents/aphrodite.md +13 -10
  67. package/src/agents/apollo.md +4 -5
  68. package/src/agents/athena.md +74 -46
  69. package/src/agents/demeter.md +10 -7
  70. package/src/agents/gaia.md +0 -1
  71. package/src/agents/hephaestus.md +4 -3
  72. package/src/agents/hermes.md +10 -9
  73. package/src/agents/iris.md +6 -1
  74. package/src/agents/mnemosyne.md +10 -4
  75. package/src/agents/nyx.md +4 -4
  76. package/src/agents/prometheus.md +12 -11
  77. package/src/agents/talos.md +6 -0
  78. package/src/agents/zeus.md +84 -56
  79. package/src/instructions/agent-return-format.instructions.md +12 -41
  80. package/src/instructions/memory-protocol.instructions.md +5 -11
  81. package/src/instructions/test-economy.instructions.md +12 -0
  82. package/src/instructions/yagni.instructions.md +6 -15
  83. package/src/instructions/zeus-anti-stall.instructions.md +6 -6
  84. package/src/instructions/zeus-communication-rules.instructions.md +6 -6
  85. package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
  86. package/src/instructions/zeus-memory-operations.instructions.md +13 -7
  87. package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
  88. package/src/mcp/_pantheon_paths.py +24 -0
  89. package/src/mcp/mcp_codemap_module.py +86 -18
  90. package/src/mcp/mcp_persistence.py +1535 -1050
  91. package/src/mcp/memory_mcp.py +444 -94
  92. package/src/mcp/pantheon_vision.py +285 -41
  93. package/src/mcp/requirements-mcp.txt +5 -0
  94. package/src/pantheon/context-pruner.ts +541 -0
  95. package/src/pantheon/cost-command.ts +814 -60
  96. package/src/pantheon/goal-loop.ts +11 -8
  97. package/src/pantheon/memory-context.ts +1017 -0
  98. package/src/pantheon/model-agents.ts +19 -0
  99. package/src/pantheon/model-command.ts +218 -56
  100. package/src/pantheon/model-pricing.ts +536 -0
  101. package/src/pantheon/presets.mjs +2 -0
  102. package/src/pantheon/task-result-guard.ts +50 -14
  103. package/src/pantheon/v2-bounded-read.ts +640 -0
  104. package/src/pantheon/v2-delegation-enforce.ts +133 -6
  105. package/src/pantheon/v2-execute-after.ts +135 -24
  106. package/src/pantheon/v2-model-overrides.ts +275 -0
  107. package/src/pantheon/v2-tools.ts +89 -35
  108. package/src/pantheon/v2-unsupported.mjs +2 -3
  109. package/src/pantheon/v2-vision.ts +622 -0
  110. package/src/pantheon/vision-local.ts +531 -0
  111. package/src/pantheon/vision.ts +1160 -115
  112. package/src/plugin-v2.ts +654 -162
  113. package/src/plugin.ts +15 -11
  114. package/src/plugins/tui/dist/tui-v2.d.ts +1029 -2
  115. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  116. package/src/plugins/tui/dist/tui-v2.js +3742 -85
  117. package/src/plugins/tui/dist/tui.js +1 -1
  118. package/src/plugins/tui/package-lock.json +6 -6
  119. package/src/plugins/tui/package.json +5 -4
  120. package/src/plugins/tui/src/index-v2.tsx +4314 -50
  121. package/src/plugins/tui/tsconfig.typecheck.json +5 -0
  122. package/src/routing.yml +50 -5
  123. package/src/skills/agent-coordination/SKILL.md +7 -2
  124. package/src/skills/artifact-management/SKILL.md +5 -1
  125. package/src/skills/auto-continue/SKILL.md +14 -6
  126. package/src/skills/codemap/SKILL.md +1 -1
  127. package/src/skills/memory-bank/SKILL.md +21 -13
  128. package/src/skills/session-goal/SKILL.md +12 -22
  129. package/src/skills/spec-driven-development/SKILL.md +3 -1
  130. package/src/skills/worktrees/SKILL.md +30 -11
  131. package/scripts/probe-context-rehydrate.mjs +0 -263
@@ -0,0 +1,541 @@
1
+ /**
2
+ * Dynamic Context Pruning (DCP) for the OpenCode V2 runtime.
3
+ *
4
+ * The V2 host hands an in-place mutable `messages` array to
5
+ * `session.hook('compaction', …)` right before it is sent to the summarization
6
+ * model. Pruning that array is safe: it changes only what feeds the summary,
7
+ * never the persisted session. The same engine is exposed behind an explicit
8
+ * opt-in on the per-request `context` hook, where it also invalidates the
9
+ * provider prompt cache — hence `context_pruner.enabled` defaults to `false`.
10
+ *
11
+ * Message shape measured on `opencode v2.1.2` (see CHANGELOG):
12
+ *
13
+ * user/assistant text { id?, role, content: [{ type: 'text', text }], metadata? }
14
+ * assistant tool call { id?, role: 'assistant',
15
+ * content: [{ type: 'tool-call', id, name, input, providerExecuted }] }
16
+ * tool result { role: 'tool',
17
+ * content: [{ type: 'tool-result', id, name,
18
+ * result: { type: 'text'|'error', value },
19
+ * providerExecuted }] }
20
+ *
21
+ * There is no `parts` field and tool messages carry no `id`/`metadata`. This
22
+ * module never deletes a message, never reorders, never changes a role, and
23
+ * never touches `system`. Every rule only rewrites a part's `result` or
24
+ * `input`, which is why the provider serializer keeps working.
25
+ *
26
+ * Rules (v1, deliberately small):
27
+ * 1. dedup — identical (tool name, normalized input) invocations keep the
28
+ * MOST RECENT result verbatim; earlier result bodies become a
29
+ * short marker placeholder;
30
+ * 2. purge — arguments of tool calls that failed are blanked after N turns,
31
+ * leaving the error message itself visible;
32
+ * 3. window — the last K turns are never touched (default 4);
33
+ * 4. guard — configured tool names (default: delegation + skill loads) are
34
+ * never touched;
35
+ * 5. idem — placeholders carry `[pantheon-prune:v1 …]`; a second pass over
36
+ * an already-pruned array finds nothing to do;
37
+ * 6. floor — below ~200 estimated tokens saved, nothing is mutated, so a
38
+ * provider prompt cache is not invalidated for nothing.
39
+ *
40
+ * Pure: no host imports, no I/O, no LLM, no tokenizer. Characters/4 is the
41
+ * estimate. Never throws — every unexpected shape fails open (no mutation).
42
+ *
43
+ * @module context-pruner
44
+ */
45
+
46
+ /** Stable prefix carried by every placeholder this module writes. */
47
+ export const PRUNE_MARKER = '[pantheon-prune:v1'
48
+
49
+ /** Which hook asked for the prune — echoed in the one-line log entry. */
50
+ export type PruneSite = 'compaction' | 'context'
51
+
52
+ /** Why a pass made no change (`null` when it did prune). */
53
+ export type PruneSkipReason = 'not-array' | 'malformed' | 'below-threshold' | 'no-candidates'
54
+
55
+ export interface ContextPrunerConfig {
56
+ /**
57
+ * Per-request (`context` hook) opt-in. The compaction site always applies
58
+ * the rules; this flag only gates the cache-invalidating per-request site.
59
+ */
60
+ enabled: boolean
61
+ /** Number of trailing turns left untouched. */
62
+ keepTurns: number
63
+ /** Minimum turns between a failed call and its argument purge. */
64
+ purgeAfterTurns: number
65
+ /** Tool names no rule may touch. */
66
+ protectedTools: string[]
67
+ /** Estimated-token floor below which nothing is mutated. */
68
+ minSavingsTokens: number
69
+ /** Characters-per-token heuristic divisor. */
70
+ charsPerToken: number
71
+ }
72
+
73
+ export interface PruneStats {
74
+ site: PruneSite
75
+ changed: boolean
76
+ /** Distinct messages whose parts were rewritten. */
77
+ messagesTouched: number
78
+ /** Parts rewritten (a message may contain several). */
79
+ partsPruned: number
80
+ estimatedCharsSaved: number
81
+ /** `ceil(charsSaved / charsPerToken)`. */
82
+ estimatedTokensSaved: number
83
+ skipReason: PruneSkipReason | null
84
+ }
85
+
86
+ /** Defaults. `enabled:false` is the documented cache-safety decision. */
87
+ export const DEFAULT_CONTEXT_PRUNER_CONFIG: ContextPrunerConfig = {
88
+ enabled: false,
89
+ keepTurns: 4,
90
+ purgeAfterTurns: 2,
91
+ protectedTools: ['subagent', 'task', 'skill'],
92
+ minSavingsTokens: 200,
93
+ charsPerToken: 4,
94
+ }
95
+
96
+ /**
97
+ * Read `options.context_pruner` (the V2 config copy, mirroring how
98
+ * `context_sandbox` is read). Malformed input yields the defaults — config
99
+ * parsing must never take the hook down.
100
+ */
101
+ export function resolveContextPrunerConfig(options: unknown): ContextPrunerConfig {
102
+ try {
103
+ const raw = (options as { context_pruner?: unknown } | null | undefined)?.context_pruner
104
+ if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) {
105
+ return {
106
+ ...DEFAULT_CONTEXT_PRUNER_CONFIG,
107
+ protectedTools: [...DEFAULT_CONTEXT_PRUNER_CONFIG.protectedTools],
108
+ }
109
+ }
110
+ const obj = raw as Record<string, unknown>
111
+ const num = (value: unknown, fallback: number, min: number): number => {
112
+ if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
113
+ return Math.max(min, Math.floor(value))
114
+ }
115
+ let protectedTools = [...DEFAULT_CONTEXT_PRUNER_CONFIG.protectedTools]
116
+ if (Array.isArray(obj.protectedTools)) {
117
+ const names = obj.protectedTools
118
+ .filter((entry): entry is string => typeof entry === 'string')
119
+ .map((entry) => entry.trim())
120
+ .filter((entry) => entry !== '')
121
+ protectedTools = [...new Set(names)]
122
+ }
123
+ return {
124
+ enabled: typeof obj.enabled === 'boolean' ? obj.enabled : false,
125
+ keepTurns: num(obj.keepTurns, DEFAULT_CONTEXT_PRUNER_CONFIG.keepTurns, 0),
126
+ purgeAfterTurns: num(obj.purgeAfterTurns, DEFAULT_CONTEXT_PRUNER_CONFIG.purgeAfterTurns, 0),
127
+ protectedTools,
128
+ minSavingsTokens: num(
129
+ obj.minSavingsTokens,
130
+ DEFAULT_CONTEXT_PRUNER_CONFIG.minSavingsTokens,
131
+ 0,
132
+ ),
133
+ charsPerToken: num(obj.charsPerToken, DEFAULT_CONTEXT_PRUNER_CONFIG.charsPerToken, 1),
134
+ }
135
+ } catch {
136
+ return {
137
+ ...DEFAULT_CONTEXT_PRUNER_CONFIG,
138
+ protectedTools: [...DEFAULT_CONTEXT_PRUNER_CONFIG.protectedTools],
139
+ }
140
+ }
141
+ }
142
+
143
+ /** The keys `resolveContextPrunerConfig` understands, in documented order. */
144
+ export const CONTEXT_PRUNER_CONFIG_KEYS = [
145
+ 'enabled',
146
+ 'keepTurns',
147
+ 'purgeAfterTurns',
148
+ 'protectedTools',
149
+ 'minSavingsTokens',
150
+ 'charsPerToken',
151
+ ] as const
152
+
153
+ /**
154
+ * Describe why a `context_pruner` block would be partially ignored, without
155
+ * changing the fail-open resolution. An empty array means "absent or fully
156
+ * valid". Unknown keys are reported because a silent typo (`keepTurn` instead
157
+ * of `keepTurns`) is otherwise invisible: the engine keeps its default and the
158
+ * operator believes the setting took effect.
159
+ */
160
+ export function describeContextPrunerConfigIssues(options: unknown): string[] {
161
+ try {
162
+ const raw = (options as { context_pruner?: unknown } | null | undefined)?.context_pruner
163
+ if (raw === undefined || raw === null) return []
164
+ if (typeof raw !== 'object' || Array.isArray(raw)) return ['context_pruner is not an object']
165
+ const obj = raw as Record<string, unknown>
166
+ const issues: string[] = []
167
+ const accepted = CONTEXT_PRUNER_CONFIG_KEYS as readonly string[]
168
+ for (const key of Object.keys(obj)) {
169
+ if (!accepted.includes(key)) issues.push(`unknown key "${key}"`)
170
+ }
171
+ const numberField = (key: string, min: number): void => {
172
+ if (!(key in obj)) return
173
+ const value = obj[key]
174
+ if (typeof value !== 'number' || !Number.isFinite(value)) {
175
+ issues.push(`"${key}" must be a number`)
176
+ return
177
+ }
178
+ if (value < min) issues.push(`"${key}" must be >= ${min}`)
179
+ }
180
+ if ('enabled' in obj && typeof obj.enabled !== 'boolean') {
181
+ issues.push('"enabled" must be a boolean')
182
+ }
183
+ numberField('keepTurns', 0)
184
+ numberField('purgeAfterTurns', 0)
185
+ numberField('minSavingsTokens', 0)
186
+ numberField('charsPerToken', 1)
187
+ if ('protectedTools' in obj) {
188
+ const tools = obj.protectedTools
189
+ if (!Array.isArray(tools) || tools.some((entry) => typeof entry !== 'string')) {
190
+ issues.push('"protectedTools" must be an array of strings')
191
+ }
192
+ }
193
+ return issues
194
+ } catch {
195
+ return ['context_pruner could not be inspected']
196
+ }
197
+ }
198
+
199
+ // ─── Internal shapes ────────────────────────────────────────────────────
200
+ type JsonObject = Record<string, unknown>
201
+
202
+ interface ToolCallRef {
203
+ messageIndex: number
204
+ part: JsonObject
205
+ id: string
206
+ name: string
207
+ }
208
+
209
+ interface PlannedEdit {
210
+ messageIndex: number
211
+ partIndex: number
212
+ part: JsonObject
213
+ field: 'input' | 'result'
214
+ next: unknown
215
+ charsSaved: number
216
+ }
217
+
218
+ function isObject(value: unknown): value is JsonObject {
219
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
220
+ }
221
+
222
+ /** JSON length used only for the savings estimate; 0 when unserializable. */
223
+ function jsonLength(value: unknown): number {
224
+ try {
225
+ const text = JSON.stringify(value)
226
+ return typeof text === 'string' ? text.length : 0
227
+ } catch {
228
+ return 0
229
+ }
230
+ }
231
+
232
+ /** Deterministic key for an input object: sorted keys, arrays in order. */
233
+ function stableKey(value: unknown): string {
234
+ if (Array.isArray(value)) return `[${value.map((entry) => stableKey(entry)).join(',')}]`
235
+ if (isObject(value)) {
236
+ const keys = Object.keys(value).sort()
237
+ return `{${keys.map((key) => `${JSON.stringify(key)}:${stableKey(value[key])}`).join(',')}}`
238
+ }
239
+ return JSON.stringify(value ?? null) ?? 'undefined'
240
+ }
241
+
242
+ function markersMatch(value: unknown): boolean {
243
+ return typeof value === 'string' && value.startsWith(PRUNE_MARKER)
244
+ }
245
+
246
+ function isPrunedResult(part: JsonObject): boolean {
247
+ const result = part.result
248
+ return isObject(result) && markersMatch(result.value)
249
+ }
250
+
251
+ /** A failed tool result — never a redundant copy, never a valid survivor body. */
252
+ function isErrorResult(part: JsonObject): boolean {
253
+ return isObject(part.result) && part.result.type === 'error'
254
+ }
255
+
256
+ function isPurgedInput(input: unknown): boolean {
257
+ return isObject(input) && typeof input[PRUNE_MARKER] === 'string'
258
+ }
259
+
260
+ function supersededText(name: string): string {
261
+ return `${PRUNE_MARKER} superseded tool=${name}] Earlier invocation with identical arguments was superseded by a later call; its output was removed.`
262
+ }
263
+
264
+ function purgedInput(name: string, id: string): JsonObject {
265
+ return { [PRUNE_MARKER]: 'args-purged', tool: name, call: id }
266
+ }
267
+
268
+ /**
269
+ * Assign a turn index to every message.
270
+ *
271
+ * A turn is one user input or one assistant step, whichever comes first; tool
272
+ * results belong to the step that requested them. The trailing `keepTurns`
273
+ * turns are protected. `system` messages (preamble) get `-1` and are never
274
+ * candidates because no rule touches them. When the array opens with tool or
275
+ * assistant messages, turn 0 covers that prefix.
276
+ */
277
+ function assignTurns(roles: string[]): { turnOf: number[]; totalTurns: number } {
278
+ const turnOf = new Array<number>(roles.length).fill(0)
279
+ let turn = -1
280
+ let previousWasUser = false
281
+ for (let i = 0; i < roles.length; i++) {
282
+ const role = roles[i]
283
+ if (role === 'system') {
284
+ turnOf[i] = -1
285
+ continue
286
+ }
287
+ if (role === 'user') {
288
+ if (!previousWasUser) turn += 1
289
+ previousWasUser = true
290
+ } else if (role === 'assistant') {
291
+ turn += 1
292
+ previousWasUser = false
293
+ } else {
294
+ previousWasUser = false
295
+ if (turn < 0) turn = 0
296
+ }
297
+ turnOf[i] = turn
298
+ }
299
+ return { turnOf, totalTurns: turn + 1 }
300
+ }
301
+
302
+ /** Every `tool-call` part that may participate in dedup. */
303
+ function collectCalls(
304
+ messages: unknown[],
305
+ roles: string[],
306
+ protectedTools: Set<string>,
307
+ ): ToolCallRef[] {
308
+ const calls: ToolCallRef[] = []
309
+ for (let i = 0; i < messages.length; i++) {
310
+ if (roles[i] !== 'assistant') continue
311
+ const content = (messages[i] as JsonObject).content
312
+ if (!Array.isArray(content)) continue
313
+ for (const raw of content) {
314
+ if (!isObject(raw) || raw.type !== 'tool-call') continue
315
+ const id = raw.id
316
+ const name = raw.name
317
+ if (typeof id !== 'string' || id === '' || typeof name !== 'string' || name === '') continue
318
+ if (protectedTools.has(name)) continue
319
+ if (!isObject(raw.input) || isPurgedInput(raw.input)) continue
320
+ calls.push({ messageIndex: i, part: raw, id, name })
321
+ }
322
+ }
323
+ return calls
324
+ }
325
+
326
+ /** First `tool-result` part carrying the given call id, scanning forward. */
327
+ function findResult(
328
+ messages: unknown[],
329
+ fromIndex: number,
330
+ id: string,
331
+ ): { messageIndex: number; partIndex: number; part: JsonObject } | null {
332
+ for (let i = Math.max(0, fromIndex); i < messages.length; i++) {
333
+ const message = messages[i]
334
+ if (!isObject(message) || message.role !== 'tool' || !Array.isArray(message.content)) continue
335
+ for (let p = 0; p < message.content.length; p++) {
336
+ const raw = message.content[p]
337
+ if (!isObject(raw) || raw.type !== 'tool-result') continue
338
+ if (raw.id !== id) continue
339
+ return { messageIndex: i, partIndex: p, part: raw }
340
+ }
341
+ }
342
+ return null
343
+ }
344
+
345
+ /** Locate the `tool-call` part for a result id (used by the purge rule). */
346
+ function findCallById(
347
+ messages: unknown[],
348
+ id: string,
349
+ ): { messageIndex: number; partIndex: number; part: JsonObject } | null {
350
+ for (let i = 0; i < messages.length; i++) {
351
+ const message = messages[i]
352
+ if (!isObject(message) || !Array.isArray(message.content)) continue
353
+ for (let p = 0; p < message.content.length; p++) {
354
+ const raw = message.content[p]
355
+ if (!isObject(raw) || raw.type !== 'tool-call') continue
356
+ if (raw.id !== id) continue
357
+ return { messageIndex: i, partIndex: p, part: raw }
358
+ }
359
+ }
360
+ return null
361
+ }
362
+
363
+ function emptyStats(site: PruneSite, skipReason: PruneSkipReason | null): PruneStats {
364
+ return {
365
+ site,
366
+ changed: false,
367
+ messagesTouched: 0,
368
+ partsPruned: 0,
369
+ estimatedCharsSaved: 0,
370
+ estimatedTokensSaved: 0,
371
+ skipReason,
372
+ }
373
+ }
374
+
375
+ // ─── Engine ─────────────────────────────────────────────────────────────
376
+
377
+ /**
378
+ * Apply the v1 pruning rules to an in-place mutable provider-bound array.
379
+ *
380
+ * Returns statistics; the array is mutated only when the estimated savings
381
+ * reach `minSavingsTokens`. Any unexpected shape returns `changed:false` with
382
+ * the array untouched — this function NEVER throws and never partially
383
+ * applies a pass.
384
+ */
385
+ export function pruneMessages(
386
+ messages: unknown,
387
+ config: ContextPrunerConfig,
388
+ site: PruneSite,
389
+ ): PruneStats {
390
+ try {
391
+ if (!Array.isArray(messages)) return emptyStats(site, 'not-array')
392
+ if (messages.length === 0) return emptyStats(site, 'no-candidates')
393
+
394
+ const roles: string[] = []
395
+ for (const message of messages) {
396
+ if (!isObject(message) || !Array.isArray(message.content)) {
397
+ return emptyStats(site, 'malformed')
398
+ }
399
+ roles.push(typeof message.role === 'string' ? message.role : '')
400
+ }
401
+
402
+ const { turnOf, totalTurns } = assignTurns(roles)
403
+ const protectedTools = new Set(config.protectedTools)
404
+ const isProtectedTurn = (index: number): boolean =>
405
+ turnOf[index] === -1 || (turnOf[index] as number) >= totalTurns - config.keepTurns
406
+
407
+ const edits: PlannedEdit[] = []
408
+ const seen = new Set<string>()
409
+ const plan = (edit: PlannedEdit): void => {
410
+ const key = `${edit.messageIndex}:${edit.partIndex}:${edit.field}`
411
+ if (seen.has(key)) return
412
+ seen.add(key)
413
+ edits.push(edit)
414
+ }
415
+
416
+ // Rule 1 — dedup identical invocations, keep the most recent result.
417
+ const groups = new Map<string, ToolCallRef[]>()
418
+ for (const call of collectCalls(messages, roles, protectedTools)) {
419
+ let key: string
420
+ try {
421
+ key = `${call.name}\u0000${stableKey(call.part.input)}`
422
+ } catch {
423
+ continue
424
+ }
425
+ const group = groups.get(key)
426
+ if (group === undefined) groups.set(key, [call])
427
+ else group.push(call)
428
+ }
429
+ for (const group of groups.values()) {
430
+ if (group.length < 2) continue
431
+ // The survivor is the MOST RECENT invocation, and it must carry a real
432
+ // SUCCESSFUL result before any older copy is discarded. An interrupted or
433
+ // aborted call (`call c2` with no `tool-result` yet) or a later failure
434
+ // (`read X` succeeded, the identical retry errored) would otherwise
435
+ // destroy the only body in the group while both sides claim to be
436
+ // "superseded". A placeholder survivor is likewise not a survivor: the
437
+ // real body is already gone, so pruning again only loses more.
438
+ const survivor = group[group.length - 1]
439
+ if (survivor === undefined) continue
440
+ const survivorResult = findResult(messages, survivor.messageIndex + 1, survivor.id)
441
+ if (survivorResult === null) continue
442
+ if (isPrunedResult(survivorResult.part)) continue
443
+ if (isErrorResult(survivorResult.part)) continue
444
+
445
+ for (let i = 0; i < group.length - 1; i++) {
446
+ const call = group[i]
447
+ if (call === undefined) continue
448
+ const result = findResult(messages, call.messageIndex + 1, call.id)
449
+ if (result === null) continue
450
+ if (isProtectedTurn(result.messageIndex)) continue
451
+ if (isPrunedResult(result.part)) continue
452
+ // An error is never a redundant copy: its text is the diagnostic the
453
+ // caller needs. Only successful output bodies are deduped; the
454
+ // errored-arguments rule below still blanks the call arguments.
455
+ if (isErrorResult(result.part)) continue
456
+ const next = { type: 'text', value: supersededText(call.name) }
457
+ const saved = jsonLength(result.part.result) - jsonLength(next)
458
+ if (saved <= 0) continue
459
+ plan({
460
+ messageIndex: result.messageIndex,
461
+ partIndex: result.partIndex,
462
+ part: result.part,
463
+ field: 'result',
464
+ next,
465
+ charsSaved: saved,
466
+ })
467
+ }
468
+ }
469
+
470
+ // Rule 2 — blank the arguments of failed calls after N turns.
471
+ for (let i = 0; i < messages.length; i++) {
472
+ if (roles[i] !== 'tool') continue
473
+ const content = (messages[i] as JsonObject).content
474
+ if (!Array.isArray(content)) continue
475
+ for (const raw of content) {
476
+ if (!isObject(raw) || raw.type !== 'tool-result') continue
477
+ if (!isObject(raw.result) || raw.result.type !== 'error') continue
478
+ const id = raw.id
479
+ if (typeof id !== 'string' || id === '') continue
480
+ const call = findCallById(messages, id)
481
+ if (call === null) continue
482
+ const name = typeof call.part.name === 'string' ? call.part.name : ''
483
+ if (protectedTools.has(name)) continue
484
+ if (isProtectedTurn(call.messageIndex)) continue
485
+ const turnsAfter = totalTurns - 1 - (turnOf[call.messageIndex] as number)
486
+ if (turnsAfter < config.purgeAfterTurns) continue
487
+ if (!isObject(call.part.input) || isPurgedInput(call.part.input)) continue
488
+ const next = purgedInput(name, id)
489
+ const saved = jsonLength(call.part.input) - jsonLength(next)
490
+ if (saved <= 0) continue
491
+ plan({
492
+ messageIndex: call.messageIndex,
493
+ partIndex: call.partIndex,
494
+ part: call.part,
495
+ field: 'input',
496
+ next,
497
+ charsSaved: saved,
498
+ })
499
+ }
500
+ }
501
+
502
+ if (edits.length === 0) return emptyStats(site, 'no-candidates')
503
+
504
+ const charsSaved = edits.reduce((sum, edit) => sum + edit.charsSaved, 0)
505
+ const tokensSaved = Math.ceil(charsSaved / config.charsPerToken)
506
+ if (tokensSaved < config.minSavingsTokens) return emptyStats(site, 'below-threshold')
507
+
508
+ const touched = new Set<number>()
509
+ const applied: { part: JsonObject; field: 'input' | 'result'; previous: unknown }[] = []
510
+ try {
511
+ for (const edit of edits) {
512
+ applied.push({ part: edit.part, field: edit.field, previous: edit.part[edit.field] })
513
+ edit.part[edit.field] = edit.next
514
+ touched.add(edit.messageIndex)
515
+ }
516
+ } catch {
517
+ // A frozen/exotic part is an unexpected shape: roll back every write so
518
+ // the pass stays atomic and the host never sees a half-pruned array.
519
+ for (const write of applied.reverse()) {
520
+ try {
521
+ write.part[write.field] = write.previous
522
+ } catch {
523
+ // Nothing else can be done; the fields are not writable at all.
524
+ }
525
+ }
526
+ return emptyStats(site, 'malformed')
527
+ }
528
+
529
+ return {
530
+ site,
531
+ changed: true,
532
+ messagesTouched: touched.size,
533
+ partsPruned: edits.length,
534
+ estimatedCharsSaved: charsSaved,
535
+ estimatedTokensSaved: tokensSaved,
536
+ skipReason: null,
537
+ }
538
+ } catch {
539
+ return emptyStats(site, 'malformed')
540
+ }
541
+ }