@exla/rudder 4.0.0-alpha.7 → 4.0.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 (239) hide show
  1. package/README.md +33 -69
  2. package/dist/agent-efficiency/backend-observer.d.ts +13 -0
  3. package/dist/agent-efficiency/backend-observer.js +77 -0
  4. package/dist/agent-efficiency/backend-observer.js.map +1 -0
  5. package/dist/agent-efficiency/handoff.d.ts +9 -0
  6. package/dist/agent-efficiency/handoff.js +42 -0
  7. package/dist/agent-efficiency/handoff.js.map +1 -0
  8. package/dist/agent-efficiency/index.d.ts +11 -0
  9. package/dist/agent-efficiency/index.js +7 -0
  10. package/dist/agent-efficiency/index.js.map +1 -0
  11. package/dist/agent-efficiency/lessons.d.ts +55 -0
  12. package/dist/agent-efficiency/lessons.js +107 -0
  13. package/dist/agent-efficiency/lessons.js.map +1 -0
  14. package/dist/agent-efficiency/privacy.d.ts +6 -0
  15. package/dist/agent-efficiency/privacy.js +28 -0
  16. package/dist/agent-efficiency/privacy.js.map +1 -0
  17. package/dist/agent-efficiency/production.d.ts +16 -0
  18. package/dist/agent-efficiency/production.js +120 -0
  19. package/dist/agent-efficiency/production.js.map +1 -0
  20. package/dist/agent-efficiency/storage.d.ts +3 -0
  21. package/dist/agent-efficiency/storage.js +28 -0
  22. package/dist/agent-efficiency/storage.js.map +1 -0
  23. package/dist/agent-efficiency/telemetry.d.ts +59 -0
  24. package/dist/agent-efficiency/telemetry.js +143 -0
  25. package/dist/agent-efficiency/telemetry.js.map +1 -0
  26. package/dist/agent-efficiency/trace-lessons.d.ts +21 -0
  27. package/dist/agent-efficiency/trace-lessons.js +36 -0
  28. package/dist/agent-efficiency/trace-lessons.js.map +1 -0
  29. package/dist/agent-efficiency/waits.d.ts +52 -0
  30. package/dist/agent-efficiency/waits.js +131 -0
  31. package/dist/agent-efficiency/waits.js.map +1 -0
  32. package/dist/backends.js +14 -8
  33. package/dist/backends.js.map +1 -1
  34. package/dist/board/authority.d.ts +48 -0
  35. package/dist/board/authority.js +125 -0
  36. package/dist/board/authority.js.map +1 -0
  37. package/dist/board/board.js +6 -2
  38. package/dist/board/daemon.d.ts +3 -6
  39. package/dist/board/daemon.js +242 -222
  40. package/dist/board/daemon.js.map +1 -1
  41. package/dist/board/host-access.d.ts +8 -0
  42. package/dist/board/host-access.js +222 -0
  43. package/dist/board/host-access.js.map +1 -0
  44. package/dist/board/project-files.d.ts +12 -0
  45. package/dist/board/project-files.js +78 -0
  46. package/dist/board/project-files.js.map +1 -0
  47. package/dist/brain.d.ts +2 -1
  48. package/dist/brain.js +15 -21
  49. package/dist/brain.js.map +1 -1
  50. package/dist/claude-sdk-protocol.js +10 -7
  51. package/dist/claude-sdk-protocol.js.map +1 -1
  52. package/dist/cloud-build-profile.d.ts +22 -0
  53. package/dist/cloud-build-profile.js +160 -0
  54. package/dist/cloud-build-profile.js.map +1 -0
  55. package/dist/cloud.js +23 -470
  56. package/dist/cloud.js.map +1 -1
  57. package/dist/codex-binary.d.ts +1 -0
  58. package/dist/codex-binary.js +8 -1
  59. package/dist/codex-binary.js.map +1 -1
  60. package/dist/daemon.d.ts +2 -0
  61. package/dist/daemon.js +14 -2
  62. package/dist/daemon.js.map +1 -1
  63. package/dist/effort.d.ts +8 -0
  64. package/dist/effort.js +15 -2
  65. package/dist/effort.js.map +1 -1
  66. package/dist/engine-authority.js +16 -0
  67. package/dist/engine-authority.js.map +1 -1
  68. package/dist/engine.d.ts +1 -1
  69. package/dist/engine.js +11 -2
  70. package/dist/engine.js.map +1 -1
  71. package/dist/fabric-fetch.d.ts +25 -0
  72. package/dist/fabric-fetch.js +402 -0
  73. package/dist/fabric-fetch.js.map +1 -0
  74. package/dist/fabric-local.d.ts +5 -2
  75. package/dist/fabric-local.js +36 -1
  76. package/dist/fabric-local.js.map +1 -1
  77. package/dist/fabric-remote.d.ts +76 -1
  78. package/dist/fabric-remote.js +333 -61
  79. package/dist/fabric-remote.js.map +1 -1
  80. package/dist/git.js +23 -0
  81. package/dist/git.js.map +1 -1
  82. package/dist/graph.js +9 -1
  83. package/dist/graph.js.map +1 -1
  84. package/dist/jj.d.ts +3 -1
  85. package/dist/jj.js +34 -2
  86. package/dist/jj.js.map +1 -1
  87. package/dist/main.js +102 -310
  88. package/dist/main.js.map +1 -1
  89. package/dist/migration.d.ts +2 -0
  90. package/dist/migration.js +3 -0
  91. package/dist/migration.js.map +1 -1
  92. package/dist/models.js +11 -6
  93. package/dist/models.js.map +1 -1
  94. package/dist/native/darwin-arm64/native-manifest.json +19 -0
  95. package/dist/native/darwin-arm64/rudder-jj +0 -0
  96. package/dist/native/darwin-arm64/rudder-native +0 -0
  97. package/dist/native/darwin-x64/native-manifest.json +19 -0
  98. package/dist/native/darwin-x64/rudder-jj +0 -0
  99. package/dist/native/darwin-x64/rudder-native +0 -0
  100. package/dist/native/linux-x64/native-manifest.json +19 -0
  101. package/dist/native/linux-x64/rudder-jj +0 -0
  102. package/dist/native/linux-x64/rudder-native +0 -0
  103. package/dist/native-agents.js +3 -7
  104. package/dist/native-agents.js.map +1 -1
  105. package/dist/native-binary.js +11 -1
  106. package/dist/native-binary.js.map +1 -1
  107. package/dist/operations/cli.d.ts +23 -0
  108. package/dist/operations/cli.js +110 -0
  109. package/dist/operations/cli.js.map +1 -0
  110. package/dist/operations/registry.d.ts +1076 -0
  111. package/dist/operations/registry.js +69 -0
  112. package/dist/operations/registry.js.map +1 -0
  113. package/dist/operations/registry.json +124 -0
  114. package/dist/operations/requests.d.ts +167 -0
  115. package/dist/operations/requests.js +223 -0
  116. package/dist/operations/requests.js.map +1 -0
  117. package/dist/planning-ownership/index.d.ts +134 -0
  118. package/dist/planning-ownership/index.js +291 -0
  119. package/dist/planning-ownership/index.js.map +1 -0
  120. package/dist/planning-ownership/ingress.d.ts +30 -0
  121. package/dist/planning-ownership/ingress.js +41 -0
  122. package/dist/planning-ownership/ingress.js.map +1 -0
  123. package/dist/planning-ownership/store.d.ts +19 -0
  124. package/dist/planning-ownership/store.js +30 -0
  125. package/dist/planning-ownership/store.js.map +1 -0
  126. package/dist/private-access/cli.d.ts +22 -0
  127. package/dist/private-access/cli.js +76 -0
  128. package/dist/private-access/cli.js.map +1 -0
  129. package/dist/private-access/engine.d.ts +20 -0
  130. package/dist/private-access/engine.js +47 -0
  131. package/dist/private-access/engine.js.map +1 -0
  132. package/dist/private-access/home.d.ts +21 -0
  133. package/dist/private-access/home.js +80 -0
  134. package/dist/private-access/home.js.map +1 -0
  135. package/dist/private-access/previews.d.ts +101 -0
  136. package/dist/private-access/previews.js +447 -0
  137. package/dist/private-access/previews.js.map +1 -0
  138. package/dist/project-files/cli.d.ts +7 -0
  139. package/dist/project-files/cli.js +22 -0
  140. package/dist/project-files/cli.js.map +1 -0
  141. package/dist/project-files/engine.d.ts +14 -0
  142. package/dist/project-files/engine.js +52 -0
  143. package/dist/project-files/engine.js.map +1 -0
  144. package/dist/project-files/home.d.ts +13 -0
  145. package/dist/project-files/home.js +46 -0
  146. package/dist/project-files/home.js.map +1 -0
  147. package/dist/project-files/http.d.ts +9 -0
  148. package/dist/project-files/http.js +54 -0
  149. package/dist/project-files/http.js.map +1 -0
  150. package/dist/project-files/open.d.ts +10 -0
  151. package/dist/project-files/open.js +37 -0
  152. package/dist/project-files/open.js.map +1 -0
  153. package/dist/project-files/references.d.ts +9 -0
  154. package/dist/project-files/references.js +29 -0
  155. package/dist/project-files/references.js.map +1 -0
  156. package/dist/project-files/service.d.ts +32 -0
  157. package/dist/project-files/service.js +236 -0
  158. package/dist/project-files/service.js.map +1 -0
  159. package/dist/project-files/types.d.ts +40 -0
  160. package/dist/project-files/types.js +2 -0
  161. package/dist/project-files/types.js.map +1 -0
  162. package/dist/run-manager.d.ts +2 -0
  163. package/dist/run-manager.js +183 -13
  164. package/dist/run-manager.js.map +1 -1
  165. package/dist/run-timeline.d.ts +29 -0
  166. package/dist/run-timeline.js +112 -0
  167. package/dist/run-timeline.js.map +1 -0
  168. package/dist/scheduler.js +72 -13
  169. package/dist/scheduler.js.map +1 -1
  170. package/dist/surfaces.js +3 -8
  171. package/dist/surfaces.js.map +1 -1
  172. package/dist/tailscale-preview.d.ts +6 -2
  173. package/dist/tailscale-preview.js +58 -13
  174. package/dist/tailscale-preview.js.map +1 -1
  175. package/dist/task-routing.d.ts +2 -0
  176. package/dist/task-routing.js +42 -25
  177. package/dist/task-routing.js.map +1 -1
  178. package/dist/terminal-screen.d.ts +6 -0
  179. package/dist/terminal-screen.js +23 -0
  180. package/dist/terminal-screen.js.map +1 -0
  181. package/dist/tool-cache.d.ts +23 -0
  182. package/dist/tool-cache.js +144 -0
  183. package/dist/tool-cache.js.map +1 -0
  184. package/dist/types.d.ts +0 -17
  185. package/dist/types.js.map +1 -1
  186. package/dist/util.d.ts +8 -0
  187. package/dist/util.js +38 -2
  188. package/dist/util.js.map +1 -1
  189. package/dist/v4-migration/capture.d.ts +53 -0
  190. package/dist/v4-migration/capture.js +197 -0
  191. package/dist/v4-migration/capture.js.map +1 -0
  192. package/dist/v4-migration/cli.d.ts +4 -0
  193. package/dist/v4-migration/cli.js +38 -0
  194. package/dist/v4-migration/cli.js.map +1 -0
  195. package/dist/v4-migration/recovery.d.ts +43 -0
  196. package/dist/v4-migration/recovery.js +180 -0
  197. package/dist/v4-migration/recovery.js.map +1 -0
  198. package/dist/version-check.d.ts +2 -0
  199. package/dist/version-check.js +23 -0
  200. package/dist/version-check.js.map +1 -1
  201. package/dist/warm-snapshot.d.ts +55 -0
  202. package/dist/warm-snapshot.js +381 -0
  203. package/dist/warm-snapshot.js.map +1 -0
  204. package/package.json +4 -3
  205. package/scripts/copy-native.mjs +35 -48
  206. package/scripts/native-artifacts.mjs +248 -0
  207. package/dist/improve/advisor.d.ts +0 -10
  208. package/dist/improve/advisor.js +0 -115
  209. package/dist/improve/advisor.js.map +0 -1
  210. package/dist/improve/collect.d.ts +0 -49
  211. package/dist/improve/collect.js +0 -274
  212. package/dist/improve/collect.js.map +0 -1
  213. package/dist/improve/gate.d.ts +0 -17
  214. package/dist/improve/gate.js +0 -60
  215. package/dist/improve/gate.js.map +0 -1
  216. package/dist/improve/index.d.ts +0 -9
  217. package/dist/improve/index.js +0 -376
  218. package/dist/improve/index.js.map +0 -1
  219. package/dist/improve/judge.d.ts +0 -32
  220. package/dist/improve/judge.js +0 -114
  221. package/dist/improve/judge.js.map +0 -1
  222. package/dist/improve/mine.d.ts +0 -31
  223. package/dist/improve/mine.js +0 -192
  224. package/dist/improve/mine.js.map +0 -1
  225. package/dist/improve/propose.d.ts +0 -51
  226. package/dist/improve/propose.js +0 -150
  227. package/dist/improve/propose.js.map +0 -1
  228. package/dist/improve/rank.d.ts +0 -16
  229. package/dist/improve/rank.js +0 -49
  230. package/dist/improve/rank.js.map +0 -1
  231. package/dist/improve/schedule.d.ts +0 -1
  232. package/dist/improve/schedule.js +0 -95
  233. package/dist/improve/schedule.js.map +0 -1
  234. package/dist/improve/ship.d.ts +0 -25
  235. package/dist/improve/ship.js +0 -82
  236. package/dist/improve/ship.js.map +0 -1
  237. package/dist/improve/state.d.ts +0 -157
  238. package/dist/improve/state.js +0 -264
  239. package/dist/improve/state.js.map +0 -1
package/README.md CHANGED
@@ -108,14 +108,35 @@ You can also start a task directly from the shell:
108
108
 
109
109
  ```bash
110
110
  rudder "fix the failing tests"
111
- rudder claude "fix the auth redirect bug"
112
- rudder codex --model gpt-6.1-sol "refactor the parser"
111
+ rudder "fix the auth redirect bug" --backend claude
112
+ rudder "refactor the parser" --backend codex --model gpt-6.1-sol
113
+ rudder "run the migration" --cloud
113
114
  ```
114
115
 
116
+ The whole CLI:
117
+
118
+ ```
119
+ rudder open the dashboard
120
+ rudder "task" start an agent (--cloud, --backend X, --continue)
121
+ rudder ls list agents
122
+ rudder attach <agent> watch or type into one agent
123
+ rudder logs <agent> saved output
124
+ rudder stop <agent> [--delete] stop an agent; --delete also removes it
125
+ rudder login | logout Rudder Cloud account
126
+ rudder cloud [move] Cloud home status; move this project there
127
+ rudder doctor setup and diagnostics
128
+ rudder update | --version
129
+ ```
130
+
131
+ Merge, sync, cleanup and gc are automatic; undo is a dashboard action. Older
132
+ spellings (`run`, `claude`, `codex`, `sail`, `watch`, `status`, `runs`,
133
+ `handoff`, `onboard`, `mouse-test`) print the new form and still work for one
134
+ release.
135
+
115
136
  ## Onboarding and auth
116
137
 
117
138
  ```bash
118
- rudder onboard
139
+ rudder doctor setup
119
140
  ```
120
141
 
121
142
  Onboarding uses the auth you already have, so you usually do not need API keys:
@@ -442,7 +463,7 @@ Two directions, same result:
442
463
  showing what each was about, which model it was running, how long ago, and its
443
464
  session id. Pick one, optionally type the next step after it, and press Enter. It
444
465
  opens as an isolated worker that merges with `m` like any other.
445
- - **From inside the chat:** run `rudder handoff "<next step>"`. That queues the
466
+ - **From inside the chat:** run `rudder --continue "<next step>"`. That queues the
446
467
  conversation you are in; the dashboard picks it up within a second (start it with
447
468
  `rudder` if it is not open). `--here` continues in the main checkout instead of an
448
469
  isolated workspace, `--list` shows the conversations Rudder can see, and
@@ -493,13 +514,7 @@ Choose the merge behavior in `~/.rudder/config.json`:
493
514
  - `"merge"` (default): `git merge --no-ff`.
494
515
  - `"rebase"`: rebase the workspace onto the latest base, then `git merge --ff-only`.
495
516
 
496
- Command-line equivalents:
497
-
498
- ```bash
499
- rudder merge <runId>
500
- rudder sync <runId>
501
- rudder cleanup
502
- ```
517
+ Merging, syncing and cleanup happen automatically or from the dashboard.
503
518
 
504
519
  `rudder stop` records a durable cancellation request and terminates the native PTY process
505
520
  group. Cancellation is terminal: a resulting signal exit cannot be relabeled as a failure.
@@ -544,7 +559,7 @@ rudder cloud list # list cloud workers
544
559
  rudder cloud logs <id> # worker status
545
560
  rudder cloud onload [runId] # hand one agent off to the cloud (or upload the workspace)
546
561
  rudder cloud workspace attach # migrate all live isolated agents into one cloud workspace
547
- rudder sail <name> # short alias for starting a cloud worker
562
+ rudder "task" --cloud # start an agent on your Cloud home
548
563
  ```
549
564
 
550
565
  **Your home machine.** `rudder cloud` in a repo with a GitHub origin opens it on
@@ -645,15 +660,6 @@ diff. The explicit fleet-migration snapshot includes all inherited environment v
645
660
  agent auth/config, shell and cloud CLI configuration, and project `.env*` files (including
646
661
  nested package dotenv files) in each restored worker workspace.
647
662
 
648
- Cloud workers use Fly Machines by default. To use your own server over SSH (Docker over
649
- SSH; bring-your-own-compute can be stopped but not paused/resumed):
650
-
651
- ```bash
652
- rudder cloud byoc <ssh-host> # an entry from ~/.ssh/config, key auth + Docker
653
- rudder cloud vm "task" # run on that host
654
- rudder cloud runtime [fly|byoc]
655
- ```
656
-
657
663
  The CLI points at the hosted control plane `https://rudder-cloud-control.fly.dev`.
658
664
  Set `RUDDER_CLOUD_URL` to use your own deployment. Rudder Cloud login is separate
659
665
  from Claude Code and Codex login; provider auth stays in the official CLIs.
@@ -661,15 +667,11 @@ from Claude Code and Codex login; provider auth stays in the official CLIs.
661
667
  ## Run management
662
668
 
663
669
  ```bash
664
- rudder status
665
- rudder runs
666
- rudder watch <runId>
667
- rudder logs <runId> --follow
668
- rudder stop <runId>
669
- rudder delete <runId>
670
- rudder merge <runId>
671
- rudder sync <runId>
672
- rudder cleanup
670
+ rudder ls
671
+ rudder attach <agent>
672
+ rudder logs <agent> --follow
673
+ rudder stop <agent>
674
+ rudder stop <agent> --delete
673
675
  ```
674
676
 
675
677
  ## Troubleshooting
@@ -681,47 +683,9 @@ rudder cleanup
681
683
  avoid reparsing unchanged planner JSON, throttle background PTY drains, and redraw
682
684
  only dirty frames. Upgrade and restart any dashboard launched by 2.12.8 or older.
683
685
  - Trackpad scrolling: confirm your terminal sends scroll events with
684
- `rudder mouse-test parsed`. Set `RUDDER_WHEEL_SCROLL_ROWS=<n>` to change the
686
+ `rudder doctor mouse parsed`. Set `RUDDER_WHEEL_SCROLL_ROWS=<n>` to change the
685
687
  scroll step, or `RUDDER_MOUSE_DEBUG=1` to inspect routing.
686
688
 
687
- ## Continual improvement loop
688
-
689
- Rudder improves itself from its own telemetry. Every run already leaves a
690
- record on disk (`.rudder/runs/`, event logs, verifier results, steer history,
691
- token usage). The improvement loop, `rudder improve`, is a scheduled local
692
- batch job (launchd on macOS, not a resident daemon) that:
693
-
694
- 1. **Collects** recent session telemetry across your registered projects,
695
- redacting secrets at the source.
696
- 2. **Mines** it into ranked friction findings (failed runs, user redirects,
697
- merge conflicts, verifier misses) using the advisor pattern: a Sonnet
698
- executor consults a Fable 5 advisor mid-generation, so most tokens bill at
699
- the executor rate.
700
- 3. **Proposes** fixes with headless agents in isolated git worktrees of the
701
- rudder repo, each briefed with a rich context pack (finding, evidence,
702
- surface map, prior failed attempts, repo conventions).
703
- 4. **Judges** each candidate with the repo's full test gates plus a
704
- three-lens adversarial LLM panel that fails closed.
705
- 5. **Prepares** survivors as pushed review branches by default. If you
706
- explicitly opt into `ship` autonomy, Rudder instead rebases onto
707
- `origin/main`, runs `npm version patch`, and pushes main + tag for the normal
708
- tag-driven npm release. Later cycles verify whether the targeted metric
709
- improved and record regressions for review.
710
-
711
- ```bash
712
- rudder improve run --dry-run # see what it would do, propose nothing
713
- rudder improve schedule install # nightly cycle at 03:30 via launchd
714
- rudder improve status # shipped versions, metrics trend, ledger
715
- ```
716
-
717
- Everything stays on your machine. Estimated model/agent spend is bounded per
718
- cycle (`improve.budgetUsd`, default $5), and autonomy is configurable:
719
- `observe` only reports, `propose` (the default) pushes a review branch, and
720
- `ship` is an explicit opt-in to unattended releases. `RUDDER_IMPROVE=0`
721
- disables the loop. The full harness spec is in
722
- [`docs/continual-improvement.md`](./docs/continual-improvement.md);
723
- implementation details live in [`AGENTS.md`](./AGENTS.md) section 15.
724
-
725
689
  ## What Rudder derives rather than remembers
726
690
 
727
691
  A status that can be checked is checked, on a slow tick, against whatever actually
@@ -0,0 +1,13 @@
1
+ import type { RunRecord } from "../types.js";
2
+ /** Observe supported provider usage on the existing stream. This private local
3
+ * evidence cannot admit work or change completion/integration state.
4
+ */
5
+ export declare class BackendTelemetryObserver {
6
+ #private;
7
+ private readonly run;
8
+ constructor(run: RunRecord);
9
+ observe(event: unknown): Promise<void>;
10
+ /** Finish bounded local evidence before the integration path can learn it.
11
+ * A slow store cannot keep backend completion waiting indefinitely. */
12
+ flush(timeoutMs?: number): Promise<void>;
13
+ }
@@ -0,0 +1,77 @@
1
+ import path from "node:path";
2
+ import { randomUUID } from "node:crypto";
3
+ import { runDir } from "../state.js";
4
+ import { supportedUsage, TelemetryRecorder } from "./telemetry.js";
5
+ import { BackendReadTrace } from "./production.js";
6
+ /** Observe supported provider usage on the existing stream. This private local
7
+ * evidence cannot admit work or change completion/integration state.
8
+ */
9
+ export class BackendTelemetryObserver {
10
+ run;
11
+ #recorder;
12
+ #attempt = randomUUID();
13
+ #sequence = 0;
14
+ #pending = 0;
15
+ #reads;
16
+ #inflight = new Set();
17
+ constructor(run) {
18
+ this.run = run;
19
+ this.#recorder = new TelemetryRecorder(path.join(runDir(run.repoRoot, run.id), "efficiency.json"));
20
+ this.#reads = new BackendReadTrace(run);
21
+ }
22
+ observe(event) {
23
+ if (this.#inflight.size >= 16)
24
+ return Promise.resolve();
25
+ const work = this.#observe(event);
26
+ this.#inflight.add(work);
27
+ return work.finally(() => this.#inflight.delete(work));
28
+ }
29
+ /** Finish bounded local evidence before the integration path can learn it.
30
+ * A slow store cannot keep backend completion waiting indefinitely. */
31
+ async flush(timeoutMs = 1000) {
32
+ let timer;
33
+ try {
34
+ await Promise.race([
35
+ Promise.allSettled([...this.#inflight]),
36
+ new Promise(resolve => { timer = setTimeout(resolve, Math.min(2000, Math.max(0, timeoutMs))); }),
37
+ ]);
38
+ }
39
+ finally {
40
+ if (timer)
41
+ clearTimeout(timer);
42
+ }
43
+ }
44
+ async #observe(event) {
45
+ await this.#reads.observe(event);
46
+ // Observation cannot backpressure terminal rendering or grow an unbounded
47
+ // queue when the private evidence store is slow.
48
+ if (this.#pending >= 16)
49
+ return;
50
+ if (this.run.backend !== "codex" && this.run.backend !== "claude")
51
+ return;
52
+ const usage = supportedUsage(this.run.backend, event);
53
+ if (!usage.tokens)
54
+ return;
55
+ const data = event;
56
+ // Claude emits partial messages with the same id. Codex repeats token_count
57
+ // for rate-limit notifications; its cumulative totals identify that usage
58
+ // observation but are never charged as per-step token amounts.
59
+ const message = this.run.backend === "claude" ? data.message?.id ?? data.uuid : undefined;
60
+ const total = this.run.backend === "codex" ? data.payload?.info?.total_token_usage : undefined;
61
+ const counters = total && typeof total === "object" ? Object.fromEntries(["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_output_tokens", "total_tokens"]
62
+ .flatMap(key => {
63
+ const value = total[key];
64
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? [[key, value]] : [];
65
+ })) : undefined;
66
+ const stepId = `${this.#attempt}:${typeof message === "string" ? message : counters && Object.keys(counters).length ? JSON.stringify(counters) : ++this.#sequence}`;
67
+ this.#pending++;
68
+ try {
69
+ await this.#recorder.record({ projectId: this.run.repoRoot, runId: this.run.id, stepId,
70
+ provider: this.run.backend, model: usage.model ?? this.run.model, effort: this.run.effort, ...usage });
71
+ }
72
+ finally {
73
+ this.#pending--;
74
+ }
75
+ }
76
+ }
77
+ //# sourceMappingURL=backend-observer.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"backend-observer.js","sourceRoot":"","sources":["../../src/agent-efficiency/backend-observer.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;GAEG;AACH,MAAM,OAAO,wBAAwB;IAClB,GAAG,CAAY;IAChC,SAAS,CAAoB;IAC7B,QAAQ,GAAG,UAAU,EAAE,CAAC;IACxB,SAAS,GAAG,CAAC,CAAC;IACd,QAAQ,GAAG,CAAC,CAAC;IACb,MAAM,CAAmB;IACzB,SAAS,GAAG,IAAI,GAAG,EAAiB,CAAC;IACrC,YAAY,GAAc;QACxB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,SAAS,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC;QACnG,IAAI,CAAC,MAAM,GAAG,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,CAAC,KAAc;QACpB,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE;YAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACzD,CAAC;IACD;2EACuE;IACvE,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI;QAC1B,IAAI,KAAgD,CAAC;QACrD,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,IAAI,CAAC;gBACjB,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;gBACvC,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE,GAAG,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aACvG,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YAAC,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;IAC/C,CAAC;IACD,KAAK,CAAC,QAAQ,CAAC,KAAc;QAC3B,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjC,0EAA0E;QAC1E,iDAAiD;QACjD,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE;YAAE,OAAO;QAChC,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,KAAK,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO;QAC1E,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtD,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,OAAO;QAC1B,MAAM,IAAI,GAAG,KAA6G,CAAC;QAC3H,4EAA4E;QAC5E,0EAA0E;QAC1E,+DAA+D;QAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1F,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/F,MAAM,QAAQ,GAAG,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CACtE,CAAC,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAAE,yBAAyB,EAAE,cAAc,CAAC;aAChG,OAAO,CAAC,GAAG,CAAC,EAAE;YACb,MAAM,KAAK,GAAI,KAAiC,CAAC,GAAG,CAAC,CAAC;YACtD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACpB,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;QACpK,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM;gBACpF,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QAC3G,CAAC;gBAAS,CAAC;YAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAAC,CAAC;IAChC,CAAC;CACF"}
@@ -0,0 +1,9 @@
1
+ export type HandoffInput = {
2
+ task: string;
3
+ constraints: string[];
4
+ openObligations: string[];
5
+ recentChanges: string[];
6
+ evidenceRefs?: string[];
7
+ };
8
+ /** Data snapshot after compaction, never a new grant of authority. */
9
+ export declare function compactionHandoff(input: HandoffInput, maxBytes?: number): string;
@@ -0,0 +1,42 @@
1
+ import { evidenceId, redact } from "./privacy.js";
2
+ /** Data snapshot after compaction, never a new grant of authority. */
3
+ export function compactionHandoff(input, maxBytes = 8192) {
4
+ if (!Number.isSafeInteger(maxBytes) || maxBytes < 1024 || maxBytes > 16384)
5
+ throw new Error("invalid_handoff_budget");
6
+ const fields = ["constraints", "openObligations", "recentChanges"];
7
+ const result = {
8
+ schema: 1, kind: "compaction_handoff", authority: "context_only",
9
+ task: redact(input.task, 1200), constraints: [], openObligations: [], recentChanges: [],
10
+ evidenceRefs: (input.evidenceRefs ?? []).slice(0, 4).map(evidenceId),
11
+ omitted: { constraints: input.constraints.length, openObligations: input.openObligations.length, recentChanges: input.recentChanges.length },
12
+ needsRetrieval: input.task.length > 1200 || (input.evidenceRefs?.length ?? 0) > 4,
13
+ };
14
+ // Reserve room for all four sections even with a minimum-size budget.
15
+ result.task = redact(input.task, Math.min(1200, Math.floor(maxBytes / 6)));
16
+ result.needsRetrieval ||= result.task.length < input.task.length;
17
+ // Round robin keeps a long constraints list from hiding every obligation.
18
+ for (let index = 0; index < 8; index++) {
19
+ for (const field of fields) {
20
+ const text = input[field][index];
21
+ if (text === undefined)
22
+ continue;
23
+ const safe = redact(text, Math.min(320, Math.floor(maxBytes / 12)));
24
+ result[field].push(safe);
25
+ result.omitted[field]--;
26
+ if (Buffer.byteLength(JSON.stringify(result)) > maxBytes) {
27
+ result[field].pop();
28
+ result.omitted[field]++;
29
+ }
30
+ else if (safe.length < text.length)
31
+ result.needsRetrieval = true;
32
+ }
33
+ }
34
+ result.needsRetrieval ||= Object.values(result.omitted).some(count => count > 0);
35
+ // A multibyte task may consume more bytes than its character budget.
36
+ while (Buffer.byteLength(JSON.stringify(result)) > maxBytes && result.task.length) {
37
+ result.task = result.task.slice(0, Math.floor(result.task.length / 2));
38
+ result.needsRetrieval = true;
39
+ }
40
+ return JSON.stringify(result);
41
+ }
42
+ //# sourceMappingURL=handoff.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/agent-efficiency/handoff.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,11 @@
1
+ export { TelemetryRecorder, normalizeStep, supportedUsage } from "./telemetry.js";
2
+ export type { StepObservation, StepTelemetry, Tokens } from "./telemetry.js";
3
+ export { BoundedWaitRegistry } from "./waits.js";
4
+ export type { WaitScope, WaitResult, SettledOutcome } from "./waits.js";
5
+ export { compactionHandoff } from "./handoff.js";
6
+ export type { HandoffInput } from "./handoff.js";
7
+ export { deriveLesson, ScopedLessonStore } from "./lessons.js";
8
+ export type { Lesson, LessonKind, LessonScope, TraceFinding } from "./lessons.js";
9
+ export { deriveTraceLessons, traceFindings } from "./trace-lessons.js";
10
+ export type { AcceptedTrace, TraceAction } from "./trace-lessons.js";
11
+ export { evidenceId } from "./privacy.js";
@@ -0,0 +1,7 @@
1
+ export { TelemetryRecorder, normalizeStep, supportedUsage } from "./telemetry.js";
2
+ export { BoundedWaitRegistry } from "./waits.js";
3
+ export { compactionHandoff } from "./handoff.js";
4
+ export { deriveLesson, ScopedLessonStore } from "./lessons.js";
5
+ export { deriveTraceLessons, traceFindings } from "./trace-lessons.js";
6
+ export { evidenceId } from "./privacy.js";
7
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent-efficiency/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAElF,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
@@ -0,0 +1,55 @@
1
+ export type LessonKind = "targeted_read" | "bounded_wait" | "affected_check";
2
+ export type LessonScope = {
3
+ projectId: string;
4
+ paths: string[];
5
+ sourceRevision: string;
6
+ toolchain: string;
7
+ };
8
+ export type TraceFinding = {
9
+ kind: LessonKind;
10
+ traceId: string;
11
+ stepIds: string[];
12
+ outcome: {
13
+ id: string;
14
+ accepted: boolean;
15
+ failedChecks: number;
16
+ reviewRejected: boolean;
17
+ };
18
+ scope: LessonScope;
19
+ observedAt: number;
20
+ repetitions: number;
21
+ unchangedInputs: boolean;
22
+ };
23
+ export type Lesson = {
24
+ schema: 1;
25
+ id: string;
26
+ kind: LessonKind;
27
+ project: string;
28
+ paths: string[];
29
+ sourceRevision: string;
30
+ toolchain: string;
31
+ provenance: string[];
32
+ createdAt: number;
33
+ expiresAt: number;
34
+ recheck: "revision_or_toolchain_change";
35
+ authority: "advisory_only";
36
+ };
37
+ /** Derive only from bounded numeric findings and an authoritative accepted outcome.
38
+ * The caller obtains acceptance from integration/review, never model prose. */
39
+ export declare function deriveLesson(finding: TraceFinding, now: number, ttlMs?: number): Lesson | undefined;
40
+ /** Shared retrieval for Claude and Codex. No backend-specific prompt or scheduler. */
41
+ export declare class ScopedLessonStore {
42
+ readonly file: string;
43
+ constructor(file: string);
44
+ learn(finding: TraceFinding, now: number, ttlMs?: number): Promise<Lesson | undefined>;
45
+ reject(id: string): Promise<void>;
46
+ retrieve(scope: LessonScope, now: number, options?: {
47
+ maxLessons?: number;
48
+ maxBytes?: number;
49
+ }): Promise<{
50
+ id: string;
51
+ text: string;
52
+ provenance: string[];
53
+ authority: "advisory_only";
54
+ }[]>;
55
+ }
@@ -0,0 +1,107 @@
1
+ import { evidenceId, redact } from "./privacy.js";
2
+ import { boundedRows, editEvidence } from "./storage.js";
3
+ import { readJson } from "../util.js";
4
+ const advice = {
5
+ targeted_read: "Retrieve the relevant symbol or line range before repeating a read of unchanged content.",
6
+ bounded_wait: "Subscribe once with a deadline and read the settled result. A timeout does not release worker admission.",
7
+ affected_check: "Reuse a successful check only when its exact declared inputs and toolchain are unchanged. Required release gates still apply.",
8
+ };
9
+ function pathsWithinRepo(paths) {
10
+ return [...new Set(paths.filter(p => p.length > 0 && p.length <= 160 && redact(p, 160) === p && !p.startsWith("/") && !p.includes("\\") && p.split("/").every(part => part !== ".." && part !== "." && part !== "") && /^[\w./-]+$/.test(p)))].slice(0, 8);
11
+ }
12
+ /** Derive only from bounded numeric findings and an authoritative accepted outcome.
13
+ * The caller obtains acceptance from integration/review, never model prose. */
14
+ export function deriveLesson(finding, now, ttlMs = 7 * 86400_000) {
15
+ if (!Object.hasOwn(advice, finding.kind) || !Number.isFinite(now) || now < 0 || !Number.isFinite(ttlMs) || ttlMs <= 0 || ttlMs > 7 * 86400_000)
16
+ return undefined;
17
+ if (!Number.isFinite(finding.observedAt) || finding.observedAt < 0 || finding.observedAt > now || finding.observedAt + ttlMs <= now)
18
+ return undefined;
19
+ if (!finding.outcome.accepted || finding.outcome.failedChecks !== 0 || finding.outcome.reviewRejected || !finding.unchangedInputs || !Number.isSafeInteger(finding.repetitions) || finding.repetitions < 2)
20
+ return undefined;
21
+ const paths = pathsWithinRepo(finding.scope.paths);
22
+ if (!paths.length || !finding.traceId || !finding.outcome.id || !finding.stepIds.length || !finding.scope.projectId || !finding.scope.sourceRevision || !finding.scope.toolchain)
23
+ return undefined;
24
+ const provenance = [evidenceId(finding.traceId), evidenceId(finding.outcome.id), ...finding.stepIds.slice(0, 6).map(evidenceId)];
25
+ const project = evidenceId(finding.scope.projectId);
26
+ const sourceRevision = evidenceId(finding.scope.sourceRevision);
27
+ const toolchain = evidenceId(finding.scope.toolchain);
28
+ const id = evidenceId(JSON.stringify([project, finding.kind, paths, sourceRevision, toolchain, provenance]));
29
+ return { schema: 1, id, kind: finding.kind, project, paths, sourceRevision, toolchain, provenance, createdAt: finding.observedAt, expiresAt: finding.observedAt + ttlMs, recheck: "revision_or_toolchain_change", authority: "advisory_only" };
30
+ }
31
+ const digest = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
32
+ function validLesson(value) {
33
+ if (!value || typeof value !== "object")
34
+ return false;
35
+ const row = value;
36
+ const keys = new Set(["schema", "id", "kind", "project", "paths", "sourceRevision", "toolchain", "provenance", "createdAt", "expiresAt", "recheck", "authority"]);
37
+ return Object.keys(row).every(k => keys.has(k)) && row.schema === 1 && Object.hasOwn(advice, row.kind)
38
+ && [row.id, row.project, row.sourceRevision, row.toolchain].every(digest)
39
+ && row.authority === "advisory_only" && row.recheck === "revision_or_toolchain_change"
40
+ && Number.isFinite(row.createdAt) && row.createdAt >= 0 && Number.isFinite(row.expiresAt) && row.expiresAt > row.createdAt && row.expiresAt - row.createdAt <= 7 * 86400_000
41
+ && Array.isArray(row.paths) && row.paths.length > 0 && row.paths.length <= 8 && row.paths.every(p => typeof p === "string") && pathsWithinRepo(row.paths).length === row.paths.length
42
+ && Array.isArray(row.provenance) && row.provenance.length >= 3 && row.provenance.length <= 8 && row.provenance.every(digest);
43
+ }
44
+ function cleanFile(value) {
45
+ return { schema: 1, lessons: value?.schema === 1 && Array.isArray(value.lessons) ? value.lessons.filter(validLesson).slice(-128) : [], rejected: value?.schema === 1 && Array.isArray(value.rejected) ? value.rejected.filter(digest).slice(-512) : [] };
46
+ }
47
+ /** Shared retrieval for Claude and Codex. No backend-specific prompt or scheduler. */
48
+ export class ScopedLessonStore {
49
+ file;
50
+ constructor(file) { this.file = file; }
51
+ async learn(finding, now, ttlMs) {
52
+ const lesson = deriveLesson(finding, now, ttlMs);
53
+ if (!lesson)
54
+ return undefined;
55
+ let stored;
56
+ await editEvidence(this.file, current => {
57
+ const clean = cleanFile(current);
58
+ // An expired short-lived lesson cannot be renewed by replaying its old
59
+ // evidence with the default TTL. A fresh accepted trace is a recheck.
60
+ clean.rejected = [...new Set([...clean.rejected, ...clean.lessons.filter(row => row.expiresAt <= now).map(row => row.id)])].slice(-512);
61
+ clean.lessons = clean.lessons.filter(row => row.expiresAt > now);
62
+ // Saturation fails closed rather than evicting a rejection and later
63
+ // resurrecting it. A new scoped store requires an explicit owner reset.
64
+ if (clean.rejected.length < 512 && !clean.rejected.includes(lesson.id)) {
65
+ // Re-observing the same evidence cannot extend its lifetime.
66
+ if (!clean.lessons.some(row => row.id === lesson.id))
67
+ clean.lessons.push(lesson);
68
+ clean.lessons = boundedRows(clean.lessons, 128, 128 * 1024);
69
+ stored = clean.lessons.find(row => row.id === lesson.id);
70
+ }
71
+ return clean;
72
+ });
73
+ return stored;
74
+ }
75
+ async reject(id) {
76
+ if (!digest(id))
77
+ throw new Error("invalid_lesson_id");
78
+ await editEvidence(this.file, current => {
79
+ const clean = cleanFile(current);
80
+ clean.lessons = clean.lessons.filter(row => row.id !== id);
81
+ clean.rejected = [...new Set([...clean.rejected, id])].slice(-512);
82
+ return clean;
83
+ });
84
+ }
85
+ async retrieve(scope, now, options = {}) {
86
+ const maxLessons = options.maxLessons ?? 3;
87
+ const maxBytes = options.maxBytes ?? 2048;
88
+ if (!Number.isSafeInteger(maxLessons) || maxLessons < 1 || maxLessons > 5 || !Number.isSafeInteger(maxBytes) || maxBytes < 128 || maxBytes > 4096 || !Number.isFinite(now))
89
+ throw new Error("invalid_retrieval_bounds");
90
+ const file = cleanFile(await readJson(this.file));
91
+ const paths = pathsWithinRepo(scope.paths);
92
+ const matches = file.lessons.filter(row => row.project === evidenceId(scope.projectId) && row.sourceRevision === evidenceId(scope.sourceRevision) && row.toolchain === evidenceId(scope.toolchain)
93
+ && row.createdAt <= now && row.expiresAt > now && !file.rejected.includes(row.id)
94
+ && row.paths.some(p => paths.some(q => p === q || q.startsWith(`${p}/`) || p.startsWith(`${q}/`))))
95
+ .sort((a, b) => b.createdAt - a.createdAt || a.id.localeCompare(b.id));
96
+ const result = [];
97
+ for (const row of matches) {
98
+ if (result.length >= maxLessons)
99
+ break;
100
+ const item = { id: row.id, text: advice[row.kind], provenance: row.provenance, authority: "advisory_only" };
101
+ if (Buffer.byteLength(JSON.stringify([...result, item])) <= maxBytes)
102
+ result.push(item);
103
+ }
104
+ return result;
105
+ }
106
+ }
107
+ //# sourceMappingURL=lessons.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lessons.js","sourceRoot":"","sources":["../../src/agent-efficiency/lessons.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,6 @@
1
+ /** Evidence references are opaque. Never persist transcript locations or commands. */
2
+ export declare function evidenceId(value: string): string;
3
+ /** Defense in depth for bounded advisory text. Raw traces stay with the adapter. */
4
+ export declare function redact(value: string, limit?: number): string;
5
+ export declare function finiteMetric(value: unknown): number | undefined;
6
+ export declare function label(value: unknown): string | undefined;
@@ -0,0 +1,28 @@
1
+ import { createHash } from "node:crypto";
2
+ /** Evidence references are opaque. Never persist transcript locations or commands. */
3
+ export function evidenceId(value) {
4
+ return createHash("sha256").update(value).digest("hex");
5
+ }
6
+ /** Defense in depth for bounded advisory text. Raw traces stay with the adapter. */
7
+ export function redact(value, limit = 512) {
8
+ const safe = value
9
+ .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|$)/g, "[REDACTED]")
10
+ .replace(/\b(?:Bearer|Basic)\s+[^\s,;]+/gi, "[REDACTED]")
11
+ .replace(/\b(?:sk-[\w-]+|gh[pousr]_[\w]+|github_pat_[\w]+|xox[baprs]-[\w-]+|AKIA[A-Z0-9]{16})\b/g, "[REDACTED]")
12
+ .replace(/([\w.-]*(?:token|secret|password|passwd|api[_-]?key|credential)[\w.-]*["']?\s*[:=]\s*)(?:"[^"\n]*"|'[^'\n]*'|[^\s&,;]+)/gi, "$1[REDACTED]")
13
+ .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, "$1[REDACTED]@")
14
+ .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, "[REDACTED]")
15
+ .replace(/(?:\/Users\/|\/home\/)[^/\s]+/g, "/[PRIVATE_HOME]")
16
+ .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
17
+ return safe.length > limit ? `${safe.slice(0, Math.max(0, limit - 1))}…` : safe;
18
+ }
19
+ export function finiteMetric(value) {
20
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
21
+ }
22
+ export function label(value) {
23
+ if (typeof value !== "string" || !value.length || value.length > 96)
24
+ return undefined;
25
+ const safe = redact(value, 96);
26
+ return safe === value && /^[\w./:-]+$/.test(safe) ? safe : undefined;
27
+ }
28
+ //# sourceMappingURL=privacy.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"privacy.js","sourceRoot":"","sources":["../../src/agent-efficiency/privacy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,sFAAsF;AACtF,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,KAAK,GAAG,GAAG;IAC/C,MAAM,IAAI,GAAG,KAAK;SACf,OAAO,CAAC,+EAA+E,EAAE,YAAY,CAAC;SACtG,OAAO,CAAC,iCAAiC,EAAE,YAAY,CAAC;SACxD,OAAO,CAAC,wFAAwF,EAAE,YAAY,CAAC;SAC/G,OAAO,CAAC,2HAA2H,EAAE,cAAc,CAAC;SACpJ,OAAO,CAAC,mCAAmC,EAAE,eAAe,CAAC;SAC7D,OAAO,CAAC,6CAA6C,EAAE,YAAY,CAAC;SACpE,OAAO,CAAC,gCAAgC,EAAE,iBAAiB,CAAC;SAC5D,OAAO,CAAC,iDAAiD,EAAE,EAAE,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,KAAc;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,SAAS,CAAC;IACtF,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/B,OAAO,IAAI,KAAK,KAAK,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC"}
@@ -0,0 +1,16 @@
1
+ import type { RunRecord } from "../types.js";
2
+ /** Only structured tool-use/result pairs are evidence. Never classify shell
3
+ * commands or assistant prose as a successful read or check. Raw tool data is
4
+ * hashed in memory and is not persisted in this private bounded trace. */
5
+ export declare class BackendReadTrace {
6
+ #private;
7
+ private readonly run;
8
+ constructor(run: RunRecord);
9
+ observe(event: unknown): Promise<void>;
10
+ }
11
+ /** Called only by the successful local integration path. Review failure or
12
+ * unfinished verification cannot teach advice; a backend exit alone never does. */
13
+ export declare function learnIntegratedRun(run: RunRecord): Promise<void>;
14
+ /** Shared by both backends on ordinary start, resume and steering. The compact
15
+ * context carries open obligations and advisory provenance, never new authority. */
16
+ export declare function efficiencyContext(run: RunRecord): Promise<string>;