@buildanagent/harness 0.0.0-stage → 0.1.0-alpha.28

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 (364) hide show
  1. package/LICENSE +54 -0
  2. package/LICENSE-APACHE +202 -0
  3. package/LICENSE-MIT +21 -0
  4. package/README.md +716 -2
  5. package/dist/ablation.d.ts +2 -0
  6. package/dist/ablation.js +3 -0
  7. package/dist/ablation.js.map +1 -0
  8. package/dist/completion/check.d.ts +64 -0
  9. package/dist/completion/check.js +152 -0
  10. package/dist/completion/check.js.map +1 -0
  11. package/dist/completion/checks.d.ts +45 -0
  12. package/dist/completion/checks.js +173 -0
  13. package/dist/completion/checks.js.map +1 -0
  14. package/dist/completion/flags.d.ts +25 -0
  15. package/dist/completion/flags.js +87 -0
  16. package/dist/completion/flags.js.map +1 -0
  17. package/dist/completion/index.d.ts +8 -0
  18. package/dist/completion/index.js +9 -0
  19. package/dist/completion/index.js.map +1 -0
  20. package/dist/completion/snapshot.d.ts +33 -0
  21. package/dist/completion/snapshot.js +83 -0
  22. package/dist/completion/snapshot.js.map +1 -0
  23. package/dist/context/cap.d.ts +32 -0
  24. package/dist/context/cap.js +50 -0
  25. package/dist/context/cap.js.map +1 -0
  26. package/dist/context/estimate.d.ts +18 -0
  27. package/dist/context/estimate.js +20 -0
  28. package/dist/context/estimate.js.map +1 -0
  29. package/dist/context/file-spill.d.ts +5 -0
  30. package/dist/context/file-spill.js +25 -0
  31. package/dist/context/file-spill.js.map +1 -0
  32. package/dist/context/index.d.ts +10 -0
  33. package/dist/context/index.js +10 -0
  34. package/dist/context/index.js.map +1 -0
  35. package/dist/context/mask.d.ts +27 -0
  36. package/dist/context/mask.js +71 -0
  37. package/dist/context/mask.js.map +1 -0
  38. package/dist/context/mid-turn.d.ts +40 -0
  39. package/dist/context/mid-turn.js +82 -0
  40. package/dist/context/mid-turn.js.map +1 -0
  41. package/dist/context/policy.d.ts +9 -0
  42. package/dist/context/policy.js +140 -0
  43. package/dist/context/policy.js.map +1 -0
  44. package/dist/context/spill-ledger.d.ts +25 -0
  45. package/dist/context/spill-ledger.js +54 -0
  46. package/dist/context/spill-ledger.js.map +1 -0
  47. package/dist/context/spill.d.ts +6 -0
  48. package/dist/context/spill.js +14 -0
  49. package/dist/context/spill.js.map +1 -0
  50. package/dist/context/summarize.d.ts +53 -0
  51. package/dist/context/summarize.js +204 -0
  52. package/dist/context/summarize.js.map +1 -0
  53. package/dist/context/summary-template.d.ts +29 -0
  54. package/dist/context/summary-template.js +69 -0
  55. package/dist/context/summary-template.js.map +1 -0
  56. package/dist/context/types.d.ts +150 -0
  57. package/dist/context/types.js +2 -0
  58. package/dist/context/types.js.map +1 -0
  59. package/dist/context/write-cap.d.ts +19 -0
  60. package/dist/context/write-cap.js +41 -0
  61. package/dist/context/write-cap.js.map +1 -0
  62. package/dist/create-harness.d.ts +7 -0
  63. package/dist/create-harness.js +21 -0
  64. package/dist/create-harness.js.map +1 -0
  65. package/dist/credentials/addresses.d.ts +14 -0
  66. package/dist/credentials/addresses.js +144 -0
  67. package/dist/credentials/addresses.js.map +1 -0
  68. package/dist/credentials/allowlist.d.ts +34 -0
  69. package/dist/credentials/allowlist.js +77 -0
  70. package/dist/credentials/allowlist.js.map +1 -0
  71. package/dist/credentials/egress-proxy.d.ts +70 -0
  72. package/dist/credentials/egress-proxy.js +482 -0
  73. package/dist/credentials/egress-proxy.js.map +1 -0
  74. package/dist/credentials/index.d.ts +9 -0
  75. package/dist/credentials/index.js +10 -0
  76. package/dist/credentials/index.js.map +1 -0
  77. package/dist/credentials/scrub.d.ts +16 -0
  78. package/dist/credentials/scrub.js +93 -0
  79. package/dist/credentials/scrub.js.map +1 -0
  80. package/dist/errors.d.ts +56 -0
  81. package/dist/errors.js +63 -0
  82. package/dist/errors.js.map +1 -0
  83. package/dist/extensions/compose.d.ts +27 -0
  84. package/dist/extensions/compose.js +83 -0
  85. package/dist/extensions/compose.js.map +1 -0
  86. package/dist/extensions/context-files-node.d.ts +28 -0
  87. package/dist/extensions/context-files-node.js +74 -0
  88. package/dist/extensions/context-files-node.js.map +1 -0
  89. package/dist/extensions/context-files.d.ts +68 -0
  90. package/dist/extensions/context-files.js +214 -0
  91. package/dist/extensions/context-files.js.map +1 -0
  92. package/dist/extensions/digest.d.ts +6 -0
  93. package/dist/extensions/digest.js +68 -0
  94. package/dist/extensions/digest.js.map +1 -0
  95. package/dist/extensions/index.d.ts +10 -0
  96. package/dist/extensions/index.js +10 -0
  97. package/dist/extensions/index.js.map +1 -0
  98. package/dist/extensions/load.d.ts +42 -0
  99. package/dist/extensions/load.js +211 -0
  100. package/dist/extensions/load.js.map +1 -0
  101. package/dist/extensions/lock.d.ts +8 -0
  102. package/dist/extensions/lock.js +95 -0
  103. package/dist/extensions/lock.js.map +1 -0
  104. package/dist/extensions/node.d.ts +10 -0
  105. package/dist/extensions/node.js +11 -0
  106. package/dist/extensions/node.js.map +1 -0
  107. package/dist/extensions/project-dirs.d.ts +24 -0
  108. package/dist/extensions/project-dirs.js +97 -0
  109. package/dist/extensions/project-dirs.js.map +1 -0
  110. package/dist/extensions/skills-node.d.ts +34 -0
  111. package/dist/extensions/skills-node.js +123 -0
  112. package/dist/extensions/skills-node.js.map +1 -0
  113. package/dist/extensions/skills.d.ts +51 -0
  114. package/dist/extensions/skills.js +175 -0
  115. package/dist/extensions/skills.js.map +1 -0
  116. package/dist/extensions/trust-file.d.ts +3 -0
  117. package/dist/extensions/trust-file.js +62 -0
  118. package/dist/extensions/trust-file.js.map +1 -0
  119. package/dist/extensions/trust-store-node.d.ts +10 -0
  120. package/dist/extensions/trust-store-node.js +33 -0
  121. package/dist/extensions/trust-store-node.js.map +1 -0
  122. package/dist/extensions/types.d.ts +42 -0
  123. package/dist/extensions/types.js +2 -0
  124. package/dist/extensions/types.js.map +1 -0
  125. package/dist/harness.d.ts +156 -0
  126. package/dist/harness.js +2 -0
  127. package/dist/harness.js.map +1 -0
  128. package/dist/index.d.ts +4 -0
  129. package/dist/index.js +5 -0
  130. package/dist/index.js.map +1 -0
  131. package/dist/mcp/connection.d.ts +22 -0
  132. package/dist/mcp/connection.js +267 -0
  133. package/dist/mcp/connection.js.map +1 -0
  134. package/dist/mcp/content.d.ts +27 -0
  135. package/dist/mcp/content.js +177 -0
  136. package/dist/mcp/content.js.map +1 -0
  137. package/dist/mcp/errors.d.ts +19 -0
  138. package/dist/mcp/errors.js +21 -0
  139. package/dist/mcp/errors.js.map +1 -0
  140. package/dist/mcp/index.d.ts +10 -0
  141. package/dist/mcp/index.js +10 -0
  142. package/dist/mcp/index.js.map +1 -0
  143. package/dist/mcp/manager.d.ts +7 -0
  144. package/dist/mcp/manager.js +173 -0
  145. package/dist/mcp/manager.js.map +1 -0
  146. package/dist/mcp/record.d.ts +7 -0
  147. package/dist/mcp/record.js +20 -0
  148. package/dist/mcp/record.js.map +1 -0
  149. package/dist/mcp/stdio.d.ts +39 -0
  150. package/dist/mcp/stdio.js +382 -0
  151. package/dist/mcp/stdio.js.map +1 -0
  152. package/dist/mcp/types.d.ts +172 -0
  153. package/dist/mcp/types.js +2 -0
  154. package/dist/mcp/types.js.map +1 -0
  155. package/dist/memory/index.d.ts +2 -0
  156. package/dist/memory/index.js +3 -0
  157. package/dist/memory/index.js.map +1 -0
  158. package/dist/permissions/default-rules.d.ts +7 -0
  159. package/dist/permissions/default-rules.js +42 -0
  160. package/dist/permissions/default-rules.js.map +1 -0
  161. package/dist/permissions/errors.d.ts +11 -0
  162. package/dist/permissions/errors.js +14 -0
  163. package/dist/permissions/errors.js.map +1 -0
  164. package/dist/permissions/index.d.ts +9 -0
  165. package/dist/permissions/index.js +9 -0
  166. package/dist/permissions/index.js.map +1 -0
  167. package/dist/permissions/match.d.ts +33 -0
  168. package/dist/permissions/match.js +287 -0
  169. package/dist/permissions/match.js.map +1 -0
  170. package/dist/permissions/pipeline.d.ts +9 -0
  171. package/dist/permissions/pipeline.js +235 -0
  172. package/dist/permissions/pipeline.js.map +1 -0
  173. package/dist/permissions/rules.d.ts +22 -0
  174. package/dist/permissions/rules.js +74 -0
  175. package/dist/permissions/rules.js.map +1 -0
  176. package/dist/permissions/shadow.d.ts +5 -0
  177. package/dist/permissions/shadow.js +22 -0
  178. package/dist/permissions/shadow.js.map +1 -0
  179. package/dist/permissions/types.d.ts +104 -0
  180. package/dist/permissions/types.js +2 -0
  181. package/dist/permissions/types.js.map +1 -0
  182. package/dist/sandbox/base.d.ts +35 -0
  183. package/dist/sandbox/base.js +60 -0
  184. package/dist/sandbox/base.js.map +1 -0
  185. package/dist/sandbox/docker/index.d.ts +35 -0
  186. package/dist/sandbox/docker/index.js +448 -0
  187. package/dist/sandbox/docker/index.js.map +1 -0
  188. package/dist/sandbox/errors.d.ts +16 -0
  189. package/dist/sandbox/errors.js +22 -0
  190. package/dist/sandbox/errors.js.map +1 -0
  191. package/dist/sandbox/host-files.d.ts +63 -0
  192. package/dist/sandbox/host-files.js +248 -0
  193. package/dist/sandbox/host-files.js.map +1 -0
  194. package/dist/sandbox/index.d.ts +8 -0
  195. package/dist/sandbox/index.js +8 -0
  196. package/dist/sandbox/index.js.map +1 -0
  197. package/dist/sandbox/none.d.ts +17 -0
  198. package/dist/sandbox/none.js +108 -0
  199. package/dist/sandbox/none.js.map +1 -0
  200. package/dist/sandbox/process.d.ts +61 -0
  201. package/dist/sandbox/process.js +253 -0
  202. package/dist/sandbox/process.js.map +1 -0
  203. package/dist/sandbox/spawn-env.d.ts +20 -0
  204. package/dist/sandbox/spawn-env.js +128 -0
  205. package/dist/sandbox/spawn-env.js.map +1 -0
  206. package/dist/sandbox/srt/index.d.ts +35 -0
  207. package/dist/sandbox/srt/index.js +264 -0
  208. package/dist/sandbox/srt/index.js.map +1 -0
  209. package/dist/sandbox/srt/settings.d.ts +48 -0
  210. package/dist/sandbox/srt/settings.js +31 -0
  211. package/dist/sandbox/srt/settings.js.map +1 -0
  212. package/dist/sandbox/types.d.ts +88 -0
  213. package/dist/sandbox/types.js +6 -0
  214. package/dist/sandbox/types.js.map +1 -0
  215. package/dist/server/answers.d.ts +16 -0
  216. package/dist/server/answers.js +43 -0
  217. package/dist/server/answers.js.map +1 -0
  218. package/dist/server/connection.d.ts +99 -0
  219. package/dist/server/connection.js +309 -0
  220. package/dist/server/connection.js.map +1 -0
  221. package/dist/server/dispatcher.d.ts +86 -0
  222. package/dist/server/dispatcher.js +800 -0
  223. package/dist/server/dispatcher.js.map +1 -0
  224. package/dist/server/index.d.ts +13 -0
  225. package/dist/server/index.js +12 -0
  226. package/dist/server/index.js.map +1 -0
  227. package/dist/server/local-transport.d.ts +44 -0
  228. package/dist/server/local-transport.js +103 -0
  229. package/dist/server/local-transport.js.map +1 -0
  230. package/dist/server/outbox.d.ts +31 -0
  231. package/dist/server/outbox.js +130 -0
  232. package/dist/server/outbox.js.map +1 -0
  233. package/dist/server/params.d.ts +25 -0
  234. package/dist/server/params.js +112 -0
  235. package/dist/server/params.js.map +1 -0
  236. package/dist/server/protocol.schema.json +2448 -0
  237. package/dist/server/rpc-session.d.ts +43 -0
  238. package/dist/server/rpc-session.js +167 -0
  239. package/dist/server/rpc-session.js.map +1 -0
  240. package/dist/server/stdio-streams.d.ts +67 -0
  241. package/dist/server/stdio-streams.js +218 -0
  242. package/dist/server/stdio-streams.js.map +1 -0
  243. package/dist/server/stdio.d.ts +59 -0
  244. package/dist/server/stdio.js +189 -0
  245. package/dist/server/stdio.js.map +1 -0
  246. package/dist/server/websocket.d.ts +106 -0
  247. package/dist/server/websocket.js +327 -0
  248. package/dist/server/websocket.js.map +1 -0
  249. package/dist/session/approvals.d.ts +81 -0
  250. package/dist/session/approvals.js +217 -0
  251. package/dist/session/approvals.js.map +1 -0
  252. package/dist/session/code-call-log.d.ts +42 -0
  253. package/dist/session/code-call-log.js +63 -0
  254. package/dist/session/code-call-log.js.map +1 -0
  255. package/dist/session/code-call-result.d.ts +19 -0
  256. package/dist/session/code-call-result.js +95 -0
  257. package/dist/session/code-call-result.js.map +1 -0
  258. package/dist/session/code-call.d.ts +49 -0
  259. package/dist/session/code-call.js +345 -0
  260. package/dist/session/code-call.js.map +1 -0
  261. package/dist/session/effect-scope.d.ts +11 -0
  262. package/dist/session/effect-scope.js +10 -0
  263. package/dist/session/effect-scope.js.map +1 -0
  264. package/dist/session/errors.d.ts +19 -0
  265. package/dist/session/errors.js +27 -0
  266. package/dist/session/errors.js.map +1 -0
  267. package/dist/session/file-index.d.ts +8 -0
  268. package/dist/session/file-index.js +70 -0
  269. package/dist/session/file-index.js.map +1 -0
  270. package/dist/session/file-key-store.d.ts +16 -0
  271. package/dist/session/file-key-store.js +169 -0
  272. package/dist/session/file-key-store.js.map +1 -0
  273. package/dist/session/file-lock.d.ts +52 -0
  274. package/dist/session/file-lock.js +324 -0
  275. package/dist/session/file-lock.js.map +1 -0
  276. package/dist/session/index.d.ts +22 -0
  277. package/dist/session/index.js +20 -0
  278. package/dist/session/index.js.map +1 -0
  279. package/dist/session/jsonl-store.d.ts +37 -0
  280. package/dist/session/jsonl-store.js +386 -0
  281. package/dist/session/jsonl-store.js.map +1 -0
  282. package/dist/session/jsonl.d.ts +9 -0
  283. package/dist/session/jsonl.js +10 -0
  284. package/dist/session/jsonl.js.map +1 -0
  285. package/dist/session/lock.d.ts +19 -0
  286. package/dist/session/lock.js +2 -0
  287. package/dist/session/lock.js.map +1 -0
  288. package/dist/session/memory-store.d.ts +12 -0
  289. package/dist/session/memory-store.js +60 -0
  290. package/dist/session/memory-store.js.map +1 -0
  291. package/dist/session/migrate.d.ts +41 -0
  292. package/dist/session/migrate.js +86 -0
  293. package/dist/session/migrate.js.map +1 -0
  294. package/dist/session/pointer.d.ts +15 -0
  295. package/dist/session/pointer.js +22 -0
  296. package/dist/session/pointer.js.map +1 -0
  297. package/dist/session/rebuild.d.ts +53 -0
  298. package/dist/session/rebuild.js +230 -0
  299. package/dist/session/rebuild.js.map +1 -0
  300. package/dist/session/resume.d.ts +26 -0
  301. package/dist/session/resume.js +128 -0
  302. package/dist/session/resume.js.map +1 -0
  303. package/dist/session/retention.d.ts +97 -0
  304. package/dist/session/retention.js +702 -0
  305. package/dist/session/retention.js.map +1 -0
  306. package/dist/session/runner.d.ts +156 -0
  307. package/dist/session/runner.js +656 -0
  308. package/dist/session/runner.js.map +1 -0
  309. package/dist/session/scheduler.d.ts +47 -0
  310. package/dist/session/scheduler.js +85 -0
  311. package/dist/session/scheduler.js.map +1 -0
  312. package/dist/session/secret-key-store.d.ts +47 -0
  313. package/dist/session/secret-key-store.js +79 -0
  314. package/dist/session/secret-key-store.js.map +1 -0
  315. package/dist/session/session.d.ts +106 -0
  316. package/dist/session/session.js +353 -0
  317. package/dist/session/session.js.map +1 -0
  318. package/dist/session/sticky.d.ts +48 -0
  319. package/dist/session/sticky.js +232 -0
  320. package/dist/session/sticky.js.map +1 -0
  321. package/dist/session/store.d.ts +108 -0
  322. package/dist/session/store.js +163 -0
  323. package/dist/session/store.js.map +1 -0
  324. package/dist/telemetry/index.d.ts +2 -0
  325. package/dist/telemetry/index.js +3 -0
  326. package/dist/telemetry/index.js.map +1 -0
  327. package/dist/testing/fake-sandbox.d.ts +34 -0
  328. package/dist/testing/fake-sandbox.js +221 -0
  329. package/dist/testing/fake-sandbox.js.map +1 -0
  330. package/dist/testing/index.d.ts +10 -0
  331. package/dist/testing/index.js +11 -0
  332. package/dist/testing/index.js.map +1 -0
  333. package/dist/testing/key-store-conformance.d.ts +22 -0
  334. package/dist/testing/key-store-conformance.js +97 -0
  335. package/dist/testing/key-store-conformance.js.map +1 -0
  336. package/dist/testing/run-cases.d.ts +21 -0
  337. package/dist/testing/run-cases.js +20 -0
  338. package/dist/testing/run-cases.js.map +1 -0
  339. package/dist/testing/sandbox-conformance.d.ts +64 -0
  340. package/dist/testing/sandbox-conformance.js +361 -0
  341. package/dist/testing/sandbox-conformance.js.map +1 -0
  342. package/dist/testing/scheduler-conformance.d.ts +32 -0
  343. package/dist/testing/scheduler-conformance.js +72 -0
  344. package/dist/testing/scheduler-conformance.js.map +1 -0
  345. package/dist/testing/store-conformance.d.ts +21 -0
  346. package/dist/testing/store-conformance.js +320 -0
  347. package/dist/testing/store-conformance.js.map +1 -0
  348. package/dist/tools/errors.d.ts +13 -0
  349. package/dist/tools/errors.js +17 -0
  350. package/dist/tools/errors.js.map +1 -0
  351. package/dist/tools/index.d.ts +8 -0
  352. package/dist/tools/index.js +8 -0
  353. package/dist/tools/index.js.map +1 -0
  354. package/dist/tools/registry.d.ts +3 -0
  355. package/dist/tools/registry.js +234 -0
  356. package/dist/tools/registry.js.map +1 -0
  357. package/dist/tools/tool-search.d.ts +30 -0
  358. package/dist/tools/tool-search.js +118 -0
  359. package/dist/tools/tool-search.js.map +1 -0
  360. package/dist/tools/types.d.ts +106 -0
  361. package/dist/tools/types.js +2 -0
  362. package/dist/tools/types.js.map +1 -0
  363. package/llms.txt +435 -0
  364. package/package.json +118 -3
@@ -0,0 +1,82 @@
1
+ import { contextWithStarts, summaryMessage } from "../session/rebuild.js";
2
+ import { estimate } from "./estimate.js";
3
+ import { withoutSignedReasoning } from "./mask.js";
4
+ /** The view after a compaction: the summary, then the kept tail, without signed reasoning the compaction made stale. */
5
+ function viewAfter(applied, messages) {
6
+ const tail = messages.slice(applied.keptFrom).flatMap((message, i) => {
7
+ // Blocks the run wrote after the compaction were made under this view and stay; the older ones go.
8
+ if (message.role !== "assistant" || applied.keptFrom + i >= applied.length)
9
+ return [message];
10
+ const trimmed = withoutSignedReasoning(message);
11
+ return trimmed === undefined ? [] : [trimmed];
12
+ });
13
+ return [summaryMessage(applied.summary), ...tail];
14
+ }
15
+ /** One turn's mid-turn compaction. It compacts at most once, and only when `enabled`. */
16
+ export class MidTurn {
17
+ #session;
18
+ #enabled;
19
+ #limitTokens;
20
+ #compact;
21
+ #log;
22
+ #bindings;
23
+ #applied;
24
+ #tried = false;
25
+ #appliedAtStep = 0;
26
+ constructor(options) {
27
+ this.#session = options.session;
28
+ this.#enabled = options.enabled;
29
+ this.#limitTokens = options.limitTokens;
30
+ this.#compact = options.compact;
31
+ this.#log = options.log;
32
+ }
33
+ attach(bindings) {
34
+ this.#bindings = bindings;
35
+ }
36
+ /** Whether this turn has compacted, so the caller drops the last response's usage from its estimates. */
37
+ get applied() {
38
+ return this.#applied !== undefined;
39
+ }
40
+ /**
41
+ * The last response's usage when it still describes this view. A compaction in this turn makes the usage of the calls
42
+ * before it describe the old context, so it counts again only from the first response made under the new view.
43
+ */
44
+ usageFor(event) {
45
+ return this.#applied !== undefined && event.stepIndex <= this.#appliedAtStep ? undefined : event.lastUsage;
46
+ }
47
+ /** The messages the next model call starts from: the run's own, or the compacted view of them. */
48
+ async view(event) {
49
+ if (this.#applied === undefined && !(await this.#compactNow(event)))
50
+ return event.messages;
51
+ return viewAfter(this.#applied, event.messages);
52
+ }
53
+ async #compactNow(event) {
54
+ const bindings = this.#bindings;
55
+ if (!this.#enabled || this.#tried || bindings === undefined)
56
+ return false;
57
+ if (estimate(event.system, event.messages, event.lastUsage) <= this.#limitTokens)
58
+ return false;
59
+ this.#tried = true;
60
+ await bindings.settle();
61
+ const path = await this.#session.path();
62
+ const { context, starts } = contextWithStarts(path);
63
+ if (context.messages.length !== event.messages.length) {
64
+ this.#log?.({ layer: "mid_turn", event: "skipped", detail: "the log and the run's transcript do not line up" });
65
+ return false;
66
+ }
67
+ const done = await this.#compact({
68
+ path,
69
+ append: bindings.append,
70
+ signal: event.signal,
71
+ layer: "mid_turn",
72
+ force: true,
73
+ view: { system: event.system, messages: event.messages, starts, lastUsage: event.lastUsage },
74
+ });
75
+ if (done === undefined)
76
+ return false;
77
+ this.#applied = { ...done, length: event.messages.length };
78
+ this.#appliedAtStep = event.stepIndex;
79
+ return true;
80
+ }
81
+ }
82
+ //# sourceMappingURL=mid-turn.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mid-turn.js","sourceRoot":"","sources":["../../src/context/mid-turn.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Layer 4: compact inside a turn. The SDK's loop keeps the run's whole transcript, so a compaction in the middle of a\n * run cannot shorten it; it changes the view every later model call of the run reads. The first call that would push the\n * context past a share of the window summarises the span before a verbatim tail, writes a `compaction` entry, and from\n * then on the view is the summary, the tail and what the run adds. Later turns rebuild the same view from the log.\n */\nimport type { Message } from \"@buildanagent/gateway\";\nimport type { SessionEntry } from \"@buildanagent/protocol\";\nimport type { ContextEvent } from \"@buildanagent/sdk\";\nimport { contextWithStarts, summaryMessage } from \"../session/rebuild.js\";\nimport type { Session } from \"../session/session.js\";\nimport { estimate } from \"./estimate.js\";\nimport { withoutSignedReasoning } from \"./mask.js\";\nimport type { Compacted, CompactInput } from \"./summarize.js\";\nimport type { AppendEntry, CompactionLog } from \"./types.js\";\n\n/** What a turn lends the layer once its writer exists: a way to write entries and to wait for the ones queued. */\nexport interface MidTurnBindings {\n readonly append: AppendEntry;\n /** Resolves once every entry the run has produced so far is in the log. */\n readonly settle: () => Promise<void>;\n}\n\n/** Runs one compaction with the policy's settings filled in. */\nexport type RunCompaction = (\n input: Pick<CompactInput, \"path\" | \"append\" | \"signal\" | \"layer\" | \"force\" | \"view\">,\n) => Promise<Compacted | undefined>;\n\n/** What the layer did to the run's transcript: the summary, where the kept tail starts, and how long the transcript was. */\ninterface Applied extends Compacted {\n readonly length: number;\n}\n\n/** The view after a compaction: the summary, then the kept tail, without signed reasoning the compaction made stale. */\nfunction viewAfter(applied: Applied, messages: readonly Message[]): readonly Message[] {\n const tail = messages.slice(applied.keptFrom).flatMap((message, i) => {\n // Blocks the run wrote after the compaction were made under this view and stay; the older ones go.\n if (message.role !== \"assistant\" || applied.keptFrom + i >= applied.length) return [message];\n const trimmed = withoutSignedReasoning(message);\n return trimmed === undefined ? [] : [trimmed];\n });\n return [summaryMessage(applied.summary), ...tail];\n}\n\n/** One turn's mid-turn compaction. It compacts at most once, and only when `enabled`. */\nexport class MidTurn {\n readonly #session: Session;\n readonly #enabled: boolean;\n readonly #limitTokens: number;\n readonly #compact: RunCompaction;\n readonly #log: CompactionLog | undefined;\n #bindings: MidTurnBindings | undefined;\n #applied: Applied | undefined;\n #tried = false;\n #appliedAtStep = 0;\n\n constructor(options: {\n session: Session;\n enabled: boolean;\n limitTokens: number;\n compact: RunCompaction;\n log: CompactionLog | undefined;\n }) {\n this.#session = options.session;\n this.#enabled = options.enabled;\n this.#limitTokens = options.limitTokens;\n this.#compact = options.compact;\n this.#log = options.log;\n }\n\n attach(bindings: MidTurnBindings): void {\n this.#bindings = bindings;\n }\n\n /** Whether this turn has compacted, so the caller drops the last response's usage from its estimates. */\n get applied(): boolean {\n return this.#applied !== undefined;\n }\n\n /**\n * The last response's usage when it still describes this view. A compaction in this turn makes the usage of the calls\n * before it describe the old context, so it counts again only from the first response made under the new view.\n */\n usageFor(event: ContextEvent): ContextEvent[\"lastUsage\"] {\n return this.#applied !== undefined && event.stepIndex <= this.#appliedAtStep ? undefined : event.lastUsage;\n }\n\n /** The messages the next model call starts from: the run's own, or the compacted view of them. */\n async view(event: ContextEvent): Promise<readonly Message[]> {\n if (this.#applied === undefined && !(await this.#compactNow(event))) return event.messages;\n return viewAfter(this.#applied as Applied, event.messages);\n }\n\n async #compactNow(event: ContextEvent): Promise<boolean> {\n const bindings = this.#bindings;\n if (!this.#enabled || this.#tried || bindings === undefined) return false;\n if (estimate(event.system, event.messages, event.lastUsage) <= this.#limitTokens) return false;\n this.#tried = true;\n await bindings.settle();\n const path: readonly SessionEntry[] = await this.#session.path();\n const { context, starts } = contextWithStarts(path);\n if (context.messages.length !== event.messages.length) {\n this.#log?.({ layer: \"mid_turn\", event: \"skipped\", detail: \"the log and the run's transcript do not line up\" });\n return false;\n }\n const done = await this.#compact({\n path,\n append: bindings.append,\n signal: event.signal,\n layer: \"mid_turn\",\n force: true,\n view: { system: event.system, messages: event.messages, starts, lastUsage: event.lastUsage },\n });\n if (done === undefined) return false;\n this.#applied = { ...done, length: event.messages.length };\n this.#appliedAtStep = event.stepIndex;\n return true;\n }\n}\n"]}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * `createContextPolicy()`: the cheap context layers, built once for a harness. Layer 1 caps each tool result at write
3
+ * time and spills the full text to a file the model can name; layer 2 masks older tool results in the request view.
4
+ * Neither changes a stored entry: the cap changes what the model reads, which is what the log stores, and the mask
5
+ * changes only the view.
6
+ */
7
+ import type { ContextPolicy, ContextPolicyOptions } from "./types.js";
8
+ /** Creates a context policy. A layer left out of `layers` is on, except mid-turn compaction, which is on below a 128K window. */
9
+ export declare function createContextPolicy(options?: ContextPolicyOptions): ContextPolicy;
@@ -0,0 +1,140 @@
1
+ /**
2
+ * `createContextPolicy()`: the cheap context layers, built once for a harness. Layer 1 caps each tool result at write
3
+ * time and spills the full text to a file the model can name; layer 2 masks older tool results in the request view.
4
+ * Neither changes a stored entry: the cap changes what the model reads, which is what the log stores, and the mask
5
+ * changes only the view.
6
+ */
7
+ import { HarnessError } from "../errors.js";
8
+ import { capResult } from "./cap.js";
9
+ import { estimate } from "./estimate.js";
10
+ import { maskMessages } from "./mask.js";
11
+ import { MidTurn } from "./mid-turn.js";
12
+ import { NO_SPILL, SpillLedger } from "./spill-ledger.js";
13
+ import { compact } from "./summarize.js";
14
+ const DEFAULT_CAP_BYTES = 64 * 1024;
15
+ const DEFAULT_MASK = { keepChars: 500, stepMessages: 8 };
16
+ const DEFAULT_TAIL_TOKENS = 20_000;
17
+ const DEFAULT_TOOL_OUTPUT_CHARS = 2_000;
18
+ const DEFAULT_SUMMARY_OUTPUT_TOKENS = 4_096;
19
+ const RESERVE_TOKENS = 16_384;
20
+ const MAX_BUDGET_TOKENS = 200_000;
21
+ function checkRatio(ratio) {
22
+ if (ratio !== undefined && !(Number.isFinite(ratio) && ratio > 0 && ratio < 1)) {
23
+ throw new HarnessError("invalid_context_options", "midTurnRatio must be a number above 0 and below 1");
24
+ }
25
+ }
26
+ function checked(options) {
27
+ const cap = options.writeCapBytes ?? DEFAULT_CAP_BYTES;
28
+ const mask = options.mask ?? DEFAULT_MASK;
29
+ const bad = (why) => new HarnessError("invalid_context_options", why);
30
+ if (!Number.isInteger(cap) || cap < 1)
31
+ throw bad("writeCapBytes must be a positive whole number of bytes");
32
+ if (!Number.isInteger(mask.keepChars) || mask.keepChars < 0)
33
+ throw bad("mask.keepChars must be a whole number, 0 or more");
34
+ if (!Number.isInteger(mask.stepMessages) || mask.stepMessages < 1)
35
+ throw bad("mask.stepMessages must be a whole number, 1 or more");
36
+ if (options.budgetTokens !== undefined && (!Number.isInteger(options.budgetTokens) || options.budgetTokens < 1)) {
37
+ throw bad("budgetTokens must be a positive whole number");
38
+ }
39
+ checkRatio(options.midTurnRatio);
40
+ const writeCap = options.layers?.write_cap !== false;
41
+ if (writeCap && options.spill === undefined) {
42
+ throw bad("the write_cap layer needs a spill store; pass `spill`, or turn the layer off with layers.write_cap: false");
43
+ }
44
+ return { cap, mask, writeCap, masking: options.layers?.mask !== false };
45
+ }
46
+ /** The summary layer's settings with their defaults. */
47
+ function summarySettings(options) {
48
+ const settings = {
49
+ tailTokens: DEFAULT_TAIL_TOKENS,
50
+ toolOutputChars: DEFAULT_TOOL_OUTPUT_CHARS,
51
+ maxOutputTokens: DEFAULT_SUMMARY_OUTPUT_TOKENS,
52
+ ...options.summarize,
53
+ };
54
+ const whole = (name, value, least) => {
55
+ if (!Number.isInteger(value) || value < least) {
56
+ throw new HarnessError("invalid_context_options", `summarize.${name} must be a whole number, ${least} or more`);
57
+ }
58
+ };
59
+ whole("tailTokens", settings.tailTokens, 1);
60
+ whole("toolOutputChars", settings.toolOutputChars, 0);
61
+ whole("maxOutputTokens", settings.maxOutputTokens, 1);
62
+ if (settings.capUsd !== undefined && !(Number.isFinite(settings.capUsd) && settings.capUsd >= 0)) {
63
+ throw new HarnessError("invalid_context_options", "summarize.capUsd must be a number, 0 or more");
64
+ }
65
+ return settings;
66
+ }
67
+ const MID_TURN_RATIO = 0.9;
68
+ /** Mid-turn compaction is on by default only below this window, where the context fills in the middle of a turn. */
69
+ const MID_TURN_WINDOW = 128_000;
70
+ /** Layer 1 as an `afterToolCall` hook: caps the result and records where its full text went. */
71
+ function writeCapHook(options, session, ledger, cap) {
72
+ let spilled = 0;
73
+ return async (event) => {
74
+ // Read the earlier turns' spills first, so this result takes its place after them in the list.
75
+ await ledger.learn();
76
+ const capped = cap === undefined
77
+ ? undefined
78
+ : await capResult({
79
+ content: event.result.content,
80
+ details: event.result.details,
81
+ cap,
82
+ // A call id can repeat across turns and within a run, so the file is named by the run and a count too.
83
+ name: `${event.runId}.${spilled++}.${event.callId}`,
84
+ write: (name, text) => options.spill.write(session.key, name, text),
85
+ });
86
+ ledger.remember(event.callId, capped?.spill ?? NO_SPILL);
87
+ return capped?.patch;
88
+ };
89
+ }
90
+ /** Creates a context policy. A layer left out of `layers` is on, except mid-turn compaction, which is on below a 128K window. */
91
+ export function createContextPolicy(options = {}) {
92
+ const { cap, mask, writeCap, masking } = checked(options);
93
+ const settings = summarySettings(options);
94
+ const summarizing = options.layers?.summarize !== false;
95
+ const overflowRetry = options.layers?.overflow_retry !== false;
96
+ return {
97
+ forTurn({ session, model, onFill, ownHistory, midTurn: midTurnAllowed }) {
98
+ const ledger = new SpillLedger(session);
99
+ const window = model.caps.contextWindow;
100
+ const budget = options.budgetTokens ?? Math.max(1, Math.min(window - RESERVE_TOKENS, MAX_BUDGET_TOKENS));
101
+ let fill = { tokens: 0, budget, window };
102
+ const runCompaction = (input) => compact({ ...input, model, settings, budgetTokens: budget, hooks: options.hooks ?? {}, log: options.log });
103
+ const midTurn = new MidTurn({
104
+ session,
105
+ // A caller-supplied history is not what the log rebuilds, so a summary of it could not be written as an entry.
106
+ enabled: ownHistory !== true && midTurnAllowed !== false && (options.layers?.mid_turn ?? window < MID_TURN_WINDOW),
107
+ limitTokens: Math.floor((options.midTurnRatio ?? MID_TURN_RATIO) * window),
108
+ compact: runCompaction,
109
+ log: options.log,
110
+ });
111
+ const transformContext = async (event) => {
112
+ await ledger.learn();
113
+ const compactedBefore = midTurn.applied;
114
+ const base = await midTurn.view(event);
115
+ // A mid-turn compaction changes which results the view holds, so the spills are counted again from the log. The
116
+ // step's tool calls have all finished by now, so no result is being remembered while the ledger reloads.
117
+ if (!compactedBefore && midTurn.applied)
118
+ await ledger.reload();
119
+ const view = masking ? maskMessages(base, mask, (id, nth) => ledger.where(id, nth)) : base;
120
+ // After a compaction the last response's usage describes the context before it, so it no longer counts.
121
+ fill = { tokens: estimate(event.system, view, midTurn.usageFor(event)), budget, window };
122
+ onFill?.(fill);
123
+ return [...view];
124
+ };
125
+ return {
126
+ interceptors: {
127
+ afterToolCall: writeCapHook(options, session, ledger, writeCap ? cap : undefined),
128
+ transformContext,
129
+ },
130
+ attach: (bindings) => midTurn.attach(bindings),
131
+ compact: async ({ path, append, signal }) => summarizing && (await runCompaction({ path, append, signal, layer: "summarize" })) !== undefined,
132
+ onOverflow: async ({ path, append, signal }) => overflowRetry &&
133
+ (await runCompaction({ path, append, signal, layer: "overflow_retry", force: true })) !== undefined,
134
+ spillOf: (callId) => ledger.latest(callId),
135
+ fill: () => fill,
136
+ };
137
+ },
138
+ };
139
+ }
140
+ //# sourceMappingURL=policy.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/context/policy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `createContextPolicy()`: the cheap context layers, built once for a harness. Layer 1 caps each tool result at write\n * time and spills the full text to a file the model can name; layer 2 masks older tool results in the request view.\n * Neither changes a stored entry: the cap changes what the model reads, which is what the log stores, and the mask\n * changes only the view.\n */\n\nimport { HarnessError } from \"../errors.js\";\nimport { capResult } from \"./cap.js\";\nimport { estimate } from \"./estimate.js\";\nimport { maskMessages } from \"./mask.js\";\nimport { MidTurn, type RunCompaction } from \"./mid-turn.js\";\nimport { NO_SPILL, SpillLedger } from \"./spill-ledger.js\";\nimport { compact } from \"./summarize.js\";\nimport type { ContextFill, ContextPolicy, ContextPolicyOptions, TurnContext, TurnContextOptions } from \"./types.js\";\n\nconst DEFAULT_CAP_BYTES = 64 * 1024;\nconst DEFAULT_MASK = { keepChars: 500, stepMessages: 8 };\nconst DEFAULT_TAIL_TOKENS = 20_000;\nconst DEFAULT_TOOL_OUTPUT_CHARS = 2_000;\nconst DEFAULT_SUMMARY_OUTPUT_TOKENS = 4_096;\nconst RESERVE_TOKENS = 16_384;\nconst MAX_BUDGET_TOKENS = 200_000;\n\nfunction checkRatio(ratio: number | undefined): void {\n if (ratio !== undefined && !(Number.isFinite(ratio) && ratio > 0 && ratio < 1)) {\n throw new HarnessError(\"invalid_context_options\", \"midTurnRatio must be a number above 0 and below 1\");\n }\n}\n\nfunction checked(options: ContextPolicyOptions) {\n const cap = options.writeCapBytes ?? DEFAULT_CAP_BYTES;\n const mask = options.mask ?? DEFAULT_MASK;\n const bad = (why: string) => new HarnessError(\"invalid_context_options\", why);\n if (!Number.isInteger(cap) || cap < 1) throw bad(\"writeCapBytes must be a positive whole number of bytes\");\n if (!Number.isInteger(mask.keepChars) || mask.keepChars < 0)\n throw bad(\"mask.keepChars must be a whole number, 0 or more\");\n if (!Number.isInteger(mask.stepMessages) || mask.stepMessages < 1)\n throw bad(\"mask.stepMessages must be a whole number, 1 or more\");\n if (options.budgetTokens !== undefined && (!Number.isInteger(options.budgetTokens) || options.budgetTokens < 1)) {\n throw bad(\"budgetTokens must be a positive whole number\");\n }\n checkRatio(options.midTurnRatio);\n const writeCap = options.layers?.write_cap !== false;\n if (writeCap && options.spill === undefined) {\n throw bad(\n \"the write_cap layer needs a spill store; pass `spill`, or turn the layer off with layers.write_cap: false\",\n );\n }\n return { cap, mask, writeCap, masking: options.layers?.mask !== false };\n}\n\n/** The summary layer's settings with their defaults. */\nfunction summarySettings(options: ContextPolicyOptions) {\n const settings = {\n tailTokens: DEFAULT_TAIL_TOKENS,\n toolOutputChars: DEFAULT_TOOL_OUTPUT_CHARS,\n maxOutputTokens: DEFAULT_SUMMARY_OUTPUT_TOKENS,\n ...options.summarize,\n };\n const whole = (name: string, value: number, least: number) => {\n if (!Number.isInteger(value) || value < least) {\n throw new HarnessError(\"invalid_context_options\", `summarize.${name} must be a whole number, ${least} or more`);\n }\n };\n whole(\"tailTokens\", settings.tailTokens, 1);\n whole(\"toolOutputChars\", settings.toolOutputChars, 0);\n whole(\"maxOutputTokens\", settings.maxOutputTokens, 1);\n if (settings.capUsd !== undefined && !(Number.isFinite(settings.capUsd) && settings.capUsd >= 0)) {\n throw new HarnessError(\"invalid_context_options\", \"summarize.capUsd must be a number, 0 or more\");\n }\n return settings;\n}\n\nconst MID_TURN_RATIO = 0.9;\n/** Mid-turn compaction is on by default only below this window, where the context fills in the middle of a turn. */\nconst MID_TURN_WINDOW = 128_000;\n\ntype AfterToolCall = NonNullable<TurnContext[\"interceptors\"][\"afterToolCall\"]>;\n\n/** Layer 1 as an `afterToolCall` hook: caps the result and records where its full text went. */\nfunction writeCapHook(\n options: ContextPolicyOptions,\n session: TurnContextOptions[\"session\"],\n ledger: SpillLedger,\n cap: number | undefined,\n): AfterToolCall {\n let spilled = 0;\n return async (event) => {\n // Read the earlier turns' spills first, so this result takes its place after them in the list.\n await ledger.learn();\n const capped =\n cap === undefined\n ? undefined\n : await capResult({\n content: event.result.content,\n details: event.result.details,\n cap,\n // A call id can repeat across turns and within a run, so the file is named by the run and a count too.\n name: `${event.runId}.${spilled++}.${event.callId}`,\n write: (name, text) => (options.spill as NonNullable<typeof options.spill>).write(session.key, name, text),\n });\n ledger.remember(event.callId, capped?.spill ?? NO_SPILL);\n return capped?.patch;\n };\n}\n\n/** Creates a context policy. A layer left out of `layers` is on, except mid-turn compaction, which is on below a 128K window. */\nexport function createContextPolicy(options: ContextPolicyOptions = {}): ContextPolicy {\n const { cap, mask, writeCap, masking } = checked(options);\n const settings = summarySettings(options);\n const summarizing = options.layers?.summarize !== false;\n const overflowRetry = options.layers?.overflow_retry !== false;\n return {\n forTurn({ session, model, onFill, ownHistory, midTurn: midTurnAllowed }: TurnContextOptions): TurnContext {\n const ledger = new SpillLedger(session);\n const window = model.caps.contextWindow;\n const budget = options.budgetTokens ?? Math.max(1, Math.min(window - RESERVE_TOKENS, MAX_BUDGET_TOKENS));\n let fill: ContextFill = { tokens: 0, budget, window };\n const runCompaction: RunCompaction = (input) =>\n compact({ ...input, model, settings, budgetTokens: budget, hooks: options.hooks ?? {}, log: options.log });\n const midTurn = new MidTurn({\n session,\n // A caller-supplied history is not what the log rebuilds, so a summary of it could not be written as an entry.\n enabled:\n ownHistory !== true && midTurnAllowed !== false && (options.layers?.mid_turn ?? window < MID_TURN_WINDOW),\n limitTokens: Math.floor((options.midTurnRatio ?? MID_TURN_RATIO) * window),\n compact: runCompaction,\n log: options.log,\n });\n\n const transformContext: NonNullable<TurnContext[\"interceptors\"][\"transformContext\"]> = async (event) => {\n await ledger.learn();\n const compactedBefore = midTurn.applied;\n const base = await midTurn.view(event);\n // A mid-turn compaction changes which results the view holds, so the spills are counted again from the log. The\n // step's tool calls have all finished by now, so no result is being remembered while the ledger reloads.\n if (!compactedBefore && midTurn.applied) await ledger.reload();\n const view = masking ? maskMessages(base, mask, (id, nth) => ledger.where(id, nth)) : base;\n // After a compaction the last response's usage describes the context before it, so it no longer counts.\n fill = { tokens: estimate(event.system, view, midTurn.usageFor(event)), budget, window };\n onFill?.(fill);\n return [...view];\n };\n\n return {\n interceptors: {\n afterToolCall: writeCapHook(options, session, ledger, writeCap ? cap : undefined),\n transformContext,\n },\n attach: (bindings) => midTurn.attach(bindings),\n compact: async ({ path, append, signal }) =>\n summarizing && (await runCompaction({ path, append, signal, layer: \"summarize\" })) !== undefined,\n onOverflow: async ({ path, append, signal }) =>\n overflowRetry &&\n (await runCompaction({ path, append, signal, layer: \"overflow_retry\", force: true })) !== undefined,\n spillOf: (callId) => ledger.latest(callId),\n fill: () => fill,\n };\n },\n };\n}\n"]}
@@ -0,0 +1,25 @@
1
+ import type { Session } from "../session/session.js";
2
+ /** Where a capped result's full text went. An empty path means the result was never spilled. */
3
+ export type Spill = {
4
+ readonly path: string;
5
+ readonly bytes: number;
6
+ };
7
+ /** A result that was not capped still takes its place in the list, so the nth result of a call id finds its own spill. */
8
+ export declare const NO_SPILL: Spill;
9
+ export declare class SpillLedger {
10
+ #private;
11
+ constructor(session: Session);
12
+ /** Records the spill of the next result with this call id. */
13
+ remember(callId: string, spill: Spill): void;
14
+ /**
15
+ * Reads the earlier turns' spills from the log once. One shared promise makes parallel callers all wait for the read,
16
+ * and a failed read is tried again by the next caller.
17
+ */
18
+ learn(): Promise<void>;
19
+ /** Reads the log again, after a compaction changed which results the context holds. */
20
+ reload(): Promise<void>;
21
+ /** The latest spill of a call id, or `undefined` when its latest result was not capped. */
22
+ latest(callId: string): Spill | undefined;
23
+ /** The words a masked result's pointer line uses for the `occurrence`th result of a call id. */
24
+ where(callId: string, occurrence: number): string;
25
+ }
@@ -0,0 +1,54 @@
1
+ /** The spills of one session, in log order: which file holds the full text of each capped tool result. */
2
+ import { entriesAfterCompaction } from "../session/rebuild.js";
3
+ /** A result that was not capped still takes its place in the list, so the nth result of a call id finds its own spill. */
4
+ export const NO_SPILL = { path: "", bytes: 0 };
5
+ export class SpillLedger {
6
+ // Every spill of a call id, in log order: a provider may reuse an id, so a masked result is told apart by its place.
7
+ #spills = new Map();
8
+ #session;
9
+ #loading;
10
+ constructor(session) {
11
+ this.#session = session;
12
+ }
13
+ /** Records the spill of the next result with this call id. */
14
+ remember(callId, spill) {
15
+ this.#spills.set(callId, [...(this.#spills.get(callId) ?? []), spill]);
16
+ }
17
+ async #read() {
18
+ // Only the results the compacted context still holds, so a result's place here is its place in the view.
19
+ for (const entry of entriesAfterCompaction(await this.#session.path()).entries) {
20
+ if (entry.type === "tool_result")
21
+ this.remember(entry.callId, entry.spill ?? NO_SPILL);
22
+ }
23
+ }
24
+ /**
25
+ * Reads the earlier turns' spills from the log once. One shared promise makes parallel callers all wait for the read,
26
+ * and a failed read is tried again by the next caller.
27
+ */
28
+ learn() {
29
+ this.#loading ??= this.#read().catch((error) => {
30
+ this.#loading = undefined;
31
+ throw error;
32
+ });
33
+ return this.#loading;
34
+ }
35
+ /** Reads the log again, after a compaction changed which results the context holds. */
36
+ reload() {
37
+ this.#spills.clear();
38
+ this.#loading = undefined;
39
+ return this.learn();
40
+ }
41
+ /** The latest spill of a call id, or `undefined` when its latest result was not capped. */
42
+ latest(callId) {
43
+ const spill = this.#spills.get(callId)?.at(-1);
44
+ return spill === undefined || spill.path === "" ? undefined : spill;
45
+ }
46
+ /** The words a masked result's pointer line uses for the `occurrence`th result of a call id. */
47
+ where(callId, occurrence) {
48
+ const spill = this.#spills.get(callId)?.[occurrence];
49
+ return spill === undefined || spill.path === ""
50
+ ? `the full text is in the session log, call ${callId}`
51
+ : `the full text is in ${spill.path}`;
52
+ }
53
+ }
54
+ //# sourceMappingURL=spill-ledger.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"spill-ledger.js","sourceRoot":"","sources":["../../src/context/spill-ledger.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAK/D,0HAA0H;AAC1H,MAAM,CAAC,MAAM,QAAQ,GAAU,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAEtD,MAAM,OAAO,WAAW;IACtB,qHAAqH;IAC5G,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IACrC,QAAQ,CAAU;IAC3B,QAAQ,CAA4B;IAEpC,YAAY,OAAgB;QAC1B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,8DAA8D;IAC9D,QAAQ,CAAC,MAAc,EAAE,KAAY;QACnC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,KAAK;QACT,yGAAyG;QACzG,KAAK,MAAM,KAAK,IAAI,sBAAsB,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YAC/E,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa;gBAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,IAAI,QAAQ,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACtD,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;YAC1B,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,uFAAuF;IACvF,MAAM;QACJ,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC1B,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,2FAA2F;IAC3F,MAAM,CAAC,MAAc;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;IACtE,CAAC;IAED,gGAAgG;IAChG,KAAK,CAAC,MAAc,EAAE,UAAkB;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;QACrD,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,EAAE;YAC7C,CAAC,CAAC,6CAA6C,MAAM,EAAE;YACvD,CAAC,CAAC,uBAAuB,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;CACF","sourcesContent":["/** The spills of one session, in log order: which file holds the full text of each capped tool result. */\nimport { entriesAfterCompaction } from \"../session/rebuild.js\";\nimport type { Session } from \"../session/session.js\";\n\n/** Where a capped result's full text went. An empty path means the result was never spilled. */\nexport type Spill = { readonly path: string; readonly bytes: number };\n/** A result that was not capped still takes its place in the list, so the nth result of a call id finds its own spill. */\nexport const NO_SPILL: Spill = { path: \"\", bytes: 0 };\n\nexport class SpillLedger {\n // Every spill of a call id, in log order: a provider may reuse an id, so a masked result is told apart by its place.\n readonly #spills = new Map<string, Spill[]>();\n readonly #session: Session;\n #loading: Promise<void> | undefined;\n\n constructor(session: Session) {\n this.#session = session;\n }\n\n /** Records the spill of the next result with this call id. */\n remember(callId: string, spill: Spill): void {\n this.#spills.set(callId, [...(this.#spills.get(callId) ?? []), spill]);\n }\n\n async #read(): Promise<void> {\n // Only the results the compacted context still holds, so a result's place here is its place in the view.\n for (const entry of entriesAfterCompaction(await this.#session.path()).entries) {\n if (entry.type === \"tool_result\") this.remember(entry.callId, entry.spill ?? NO_SPILL);\n }\n }\n\n /**\n * Reads the earlier turns' spills from the log once. One shared promise makes parallel callers all wait for the read,\n * and a failed read is tried again by the next caller.\n */\n learn(): Promise<void> {\n this.#loading ??= this.#read().catch((error: unknown) => {\n this.#loading = undefined;\n throw error;\n });\n return this.#loading;\n }\n\n /** Reads the log again, after a compaction changed which results the context holds. */\n reload(): Promise<void> {\n this.#spills.clear();\n this.#loading = undefined;\n return this.learn();\n }\n\n /** The latest spill of a call id, or `undefined` when its latest result was not capped. */\n latest(callId: string): Spill | undefined {\n const spill = this.#spills.get(callId)?.at(-1);\n return spill === undefined || spill.path === \"\" ? undefined : spill;\n }\n\n /** The words a masked result's pointer line uses for the `occurrence`th result of a call id. */\n where(callId: string, occurrence: number): string {\n const spill = this.#spills.get(callId)?.[occurrence];\n return spill === undefined || spill.path === \"\"\n ? `the full text is in the session log, call ${callId}`\n : `the full text is in ${spill.path}`;\n }\n}\n"]}
@@ -0,0 +1,6 @@
1
+ import type { SpillStore } from "./types.js";
2
+ /** A spill store in memory, for tests and for a process that keeps its sessions in `memoryStore()`. */
3
+ export declare function memorySpillStore(): SpillStore & {
4
+ /** The full text spilled to `path`, or `undefined` when nothing was. */
5
+ read(path: string): string | undefined;
6
+ };
@@ -0,0 +1,14 @@
1
+ import { encodeName } from "../session/store.js";
2
+ /** A spill store in memory, for tests and for a process that keeps its sessions in `memoryStore()`. */
3
+ export function memorySpillStore() {
4
+ const files = new Map();
5
+ return {
6
+ async write(key, callId, text) {
7
+ const path = `spill/${encodeName(key.userId)}/${encodeName(key.sessionId)}/${encodeName(callId)}.txt`;
8
+ files.set(path, text);
9
+ return path;
10
+ },
11
+ read: (path) => files.get(path),
12
+ };
13
+ }
14
+ //# sourceMappingURL=spill.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"spill.js","sourceRoot":"","sources":["../../src/context/spill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAmB,MAAM,qBAAqB,CAAC;AAGlE,uGAAuG;AACvG,MAAM,UAAU,gBAAgB;IAI9B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,GAAe,EAAE,MAAc,EAAE,IAAY;YACvD,MAAM,IAAI,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC;YACtG,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;KAChC,CAAC;AACJ,CAAC","sourcesContent":["import { encodeName, type SessionKey } from \"../session/store.js\";\nimport type { SpillStore } from \"./types.js\";\n\n/** A spill store in memory, for tests and for a process that keeps its sessions in `memoryStore()`. */\nexport function memorySpillStore(): SpillStore & {\n /** The full text spilled to `path`, or `undefined` when nothing was. */\n read(path: string): string | undefined;\n} {\n const files = new Map<string, string>();\n return {\n async write(key: SessionKey, callId: string, text: string): Promise<string> {\n const path = `spill/${encodeName(key.userId)}/${encodeName(key.sessionId)}/${encodeName(callId)}.txt`;\n files.set(path, text);\n return path;\n },\n read: (path) => files.get(path),\n };\n}\n"]}
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Layer 3: summarise the span a long session has outgrown, between turns. The harness keeps a verbatim tail, asks a
3
+ * model for a recall-first summary of everything before it, and writes the result as a `compaction` entry beside a
4
+ * `usage` entry that holds the call's cost. No entry is changed or removed: the log still holds every original, and
5
+ * only the context a later turn rebuilds starts from the summary.
6
+ */
7
+ import { type Message, type Model } from "@buildanagent/gateway";
8
+ import type { CompactionEntry, SessionEntry } from "@buildanagent/protocol";
9
+ import { type LastUsage } from "./estimate.js";
10
+ import type { AppendEntry, CompactionLog, ContextHooks, SummarizeSettings } from "./types.js";
11
+ /** What `compact()` needs for one turn. */
12
+ export interface CompactInput {
13
+ readonly path: readonly SessionEntry[];
14
+ readonly append: AppendEntry;
15
+ readonly model: Model;
16
+ readonly settings: Required<Pick<SummarizeSettings, "tailTokens" | "toolOutputChars" | "maxOutputTokens">> & Pick<SummarizeSettings, "model" | "focus" | "capUsd">;
17
+ readonly budgetTokens: number;
18
+ readonly hooks: ContextHooks;
19
+ readonly log: CompactionLog | undefined;
20
+ /** Stops the summary call when the turn is aborted. */
21
+ readonly signal?: AbortSignal | undefined;
22
+ /** Which layer is compacting; written on the entry and in each log record. */
23
+ readonly layer: CompactionEntry["layer"];
24
+ /** Compact whatever the size: a provider has already said the context is too big. */
25
+ readonly force?: boolean;
26
+ /**
27
+ * The context to compact, when it is not the one the log rebuilds: a run's own transcript in the middle of a turn.
28
+ * `starts` names the entry each message begins at, and must line up with `messages`.
29
+ */
30
+ readonly view?: {
31
+ readonly system: string;
32
+ readonly messages: readonly Message[];
33
+ readonly starts: readonly (string | null)[];
34
+ readonly lastUsage?: LastUsage | undefined;
35
+ };
36
+ }
37
+ /** What a compaction replaced: the summary, and the index of the first message kept. */
38
+ export interface Compacted {
39
+ readonly summary: string;
40
+ readonly keptFrom: number;
41
+ }
42
+ /**
43
+ * The index of the first message of the tail: the newest messages that together reach `tailTokens`, moved earlier until
44
+ * the tail starts with an assistant message, so a call is never split from its result and the summary is never followed
45
+ * by another user message. 0 means nothing can be dropped.
46
+ */
47
+ export declare function tailStart(messages: readonly Message[], tailTokens: number): number;
48
+ /**
49
+ * Compacts the session when its context is over the budget, or at once when `force` is set. Returns what the new
50
+ * `compaction` entry replaced, or `undefined` when it wrote none. A skipped or failed summary writes nothing but, when
51
+ * the call was made, its `usage` entry, and says why through `log`.
52
+ */
53
+ export declare function compact(input: CompactInput): Promise<Compacted | undefined>;