@hassangameryt/freeflow 0.5.0 → 0.7.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 (301) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +2 -2
  3. package/.codex-plugin/plugin.json +4 -5
  4. package/README.md +141 -163
  5. package/capabilities/cognitive-routing/SKILL.md +387 -0
  6. package/capabilities/context-virtualization/SKILL.md +103 -0
  7. package/capabilities/conversation-history/SKILL.md +53 -0
  8. package/command-surface.json +6 -37
  9. package/hooks/freeflow-runtime-context.mjs +50 -541
  10. package/hooks/hooks.json +1 -26
  11. package/hooks/tests/check-runtime-context-hook.sh +114 -308
  12. package/package.json +27 -17
  13. package/pi-extension/dist/cognitive-routing/commands.js +96 -0
  14. package/pi-extension/dist/cognitive-routing/config.js +232 -0
  15. package/pi-extension/dist/cognitive-routing/controller.js +1292 -0
  16. package/pi-extension/dist/cognitive-routing/history.js +451 -0
  17. package/pi-extension/dist/cognitive-routing/host.js +188 -0
  18. package/pi-extension/dist/cognitive-routing/pi-routing-session.js +414 -0
  19. package/pi-extension/dist/cognitive-routing/pi-session-control.js +320 -0
  20. package/pi-extension/dist/cognitive-routing/runtime.js +43 -0
  21. package/pi-extension/dist/cognitive-routing/tool.js +212 -0
  22. package/pi-extension/dist/cognitive-routing/types.js +6 -0
  23. package/pi-extension/dist/context-virtualization/commands.js +89 -0
  24. package/pi-extension/dist/context-virtualization/projector.js +42 -0
  25. package/pi-extension/dist/context-virtualization/runtime.js +356 -0
  26. package/pi-extension/dist/context-virtualization/state.js +57 -0
  27. package/pi-extension/dist/context-virtualization/types.js +10 -0
  28. package/pi-extension/dist/conversation-history/passages.js +66 -0
  29. package/pi-extension/dist/conversation-history/ranking.js +105 -0
  30. package/pi-extension/dist/conversation-history/runtime.js +226 -0
  31. package/pi-extension/dist/conversation-history/search.js +56 -0
  32. package/pi-extension/dist/conversation-history/types.js +1 -0
  33. package/pi-extension/dist/freeflow-context/resolver.js +120 -0
  34. package/pi-extension/dist/freeflow-context/runtime.js +80 -0
  35. package/pi-extension/dist/freeflow-context/source-projector.js +95 -0
  36. package/pi-extension/dist/freeflow-context/tool.js +308 -0
  37. package/pi-extension/dist/freeflow-context/types.js +12 -0
  38. package/pi-extension/dist/freeflow-context/visibility.js +28 -0
  39. package/pi-extension/dist/index.js +564 -129
  40. package/pi-extension/dist/runtime/runtime-context.js +357 -470
  41. package/pi-extension/dist/runtime/runtime-identity.js +5 -0
  42. package/pi-extension/dist/settings/settings-tui.js +78 -0
  43. package/pi-extension/dist/settings/settings-ui.js +572 -826
  44. package/pi-extension/dist/ui/text-component.js +57 -0
  45. package/pi-extension/src/cognitive-routing/commands.ts +129 -0
  46. package/pi-extension/src/cognitive-routing/config.ts +303 -0
  47. package/pi-extension/src/cognitive-routing/controller.ts +1628 -0
  48. package/pi-extension/src/cognitive-routing/history.ts +650 -0
  49. package/pi-extension/src/cognitive-routing/host.ts +266 -0
  50. package/pi-extension/src/cognitive-routing/pi-routing-session.ts +538 -0
  51. package/pi-extension/src/cognitive-routing/pi-session-control.ts +444 -0
  52. package/pi-extension/src/cognitive-routing/runtime.ts +57 -0
  53. package/pi-extension/src/cognitive-routing/tool.ts +273 -0
  54. package/pi-extension/src/cognitive-routing/types.ts +89 -0
  55. package/pi-extension/src/context-virtualization/commands.ts +111 -0
  56. package/pi-extension/src/context-virtualization/projector.ts +62 -0
  57. package/pi-extension/src/context-virtualization/runtime.ts +406 -0
  58. package/pi-extension/src/context-virtualization/state.ts +79 -0
  59. package/pi-extension/src/context-virtualization/types.ts +92 -0
  60. package/pi-extension/src/conversation-history/passages.ts +81 -0
  61. package/pi-extension/src/conversation-history/ranking.ts +155 -0
  62. package/pi-extension/src/conversation-history/runtime.ts +250 -0
  63. package/pi-extension/src/conversation-history/search.ts +79 -0
  64. package/pi-extension/src/conversation-history/types.ts +31 -0
  65. package/pi-extension/src/freeflow-context/resolver.ts +139 -0
  66. package/pi-extension/src/freeflow-context/runtime.ts +100 -0
  67. package/pi-extension/src/freeflow-context/source-projector.ts +106 -0
  68. package/pi-extension/src/freeflow-context/tool.ts +360 -0
  69. package/pi-extension/src/freeflow-context/types.ts +70 -0
  70. package/pi-extension/src/freeflow-context/visibility.ts +53 -0
  71. package/pi-extension/src/index.ts +597 -135
  72. package/pi-extension/src/runtime/runtime-context.ts +373 -491
  73. package/pi-extension/src/runtime/runtime-identity.ts +8 -0
  74. package/pi-extension/src/settings/settings-tui.ts +93 -0
  75. package/pi-extension/src/settings/settings-ui.ts +679 -910
  76. package/pi-extension/src/ui/text-component.ts +66 -0
  77. package/pi-extension/tests/cognitive-routing/commands.test.js +134 -0
  78. package/pi-extension/tests/cognitive-routing/controller.test.js +1128 -0
  79. package/pi-extension/tests/cognitive-routing/extension-lifecycle.test.js +1142 -0
  80. package/pi-extension/tests/cognitive-routing/history.test.js +274 -0
  81. package/pi-extension/tests/cognitive-routing/host-fixture.js +4 -0
  82. package/pi-extension/tests/cognitive-routing/host-identity.test.js +63 -0
  83. package/pi-extension/tests/cognitive-routing/pi-normal-lifecycle.test.js +434 -0
  84. package/pi-extension/tests/cognitive-routing/pi-session-control.test.js +174 -0
  85. package/pi-extension/tests/cognitive-routing/pi-session-history.test.js +91 -0
  86. package/pi-extension/tests/cognitive-routing/profile-resolution.test.js +279 -0
  87. package/pi-extension/tests/cognitive-routing/tool.test.js +230 -0
  88. package/pi-extension/tests/context-virtualization/extension.test.js +749 -0
  89. package/pi-extension/tests/context-virtualization/projector.test.js +110 -0
  90. package/pi-extension/tests/context-virtualization/runtime.test.js +216 -0
  91. package/pi-extension/tests/conversation-history/runtime.test.js +98 -0
  92. package/pi-extension/tests/conversation-history/search.test.js +97 -0
  93. package/pi-extension/tests/integration/mode-free-core.test.js +218 -0
  94. package/pi-extension/tests/integration/pi-extension.test.js +532 -3701
  95. package/pi-extension/tests/integration/prompt-architecture.test.js +350 -0
  96. package/pi-extension/tests/integration/unaffected-regressions.test.js +411 -0
  97. package/runtime/prompts/cognitive-routing.md +10 -0
  98. package/runtime/prompts/context-virtualization.md +3 -0
  99. package/runtime/prompts/conversation-history.md +3 -0
  100. package/runtime/prompts/core.md +84 -0
  101. package/runtime/prompts/interaction-contract.md +11 -0
  102. package/skills/action-selection/SKILL.md +140 -0
  103. package/skills/action-selection/references/trajectory-stalls.md +71 -0
  104. package/skills/bypass/SKILL.md +109 -38
  105. package/skills/commit-work/SKILL.md +94 -55
  106. package/skills/commit-work/references/git-state-edges.md +94 -0
  107. package/skills/commit-work/references/simple-push.md +92 -0
  108. package/skills/commit-work/references/staging-decisions.md +79 -46
  109. package/skills/decision-gate/SKILL.md +80 -22
  110. package/skills/design-for-depth/SKILL.md +206 -60
  111. package/skills/design-for-depth/references/design-pressure-signals.md +108 -240
  112. package/skills/design-for-depth/references/interface-design-loop.md +77 -97
  113. package/skills/design-for-depth/references/module-and-dependency-design.md +147 -0
  114. package/skills/design-for-depth/references/software-design-philosophy.md +128 -174
  115. package/skills/design-for-depth/references/state-and-failure-boundaries.md +136 -0
  116. package/skills/diagnose-failure/SKILL.md +200 -48
  117. package/skills/diagnose-failure/references/diagnostic-loop-catalog.md +18 -6
  118. package/skills/diagnose-failure/references/{flaky-and-performance.md → flaky-and-performance-diagnosis.md} +13 -5
  119. package/skills/discuss/SKILL.md +119 -65
  120. package/skills/discuss/references/discussion-continuity.md +123 -0
  121. package/skills/evaluate-skill/SKILL.md +166 -52
  122. package/skills/evaluate-skill/references/{definition-schema.md → evaluation-definition-schema.md} +43 -3
  123. package/skills/evaluate-skill/references/evaluation-design.md +56 -30
  124. package/skills/evaluate-skill/references/execution-and-evidence.md +8 -3
  125. package/skills/evaluate-skill/references/review-and-revision.md +62 -21
  126. package/skills/evaluate-skill/scripts/lib/definitions.mjs +114 -3
  127. package/skills/evaluate-skill/scripts/lib/grade-interaction.mjs +156 -1
  128. package/skills/evaluate-skill/scripts/lib/grade.mjs +9 -1
  129. package/skills/evaluate-skill/scripts/lib/pi.mjs +147 -32
  130. package/skills/evaluate-skill/scripts/lib/rpc.mjs +4 -4
  131. package/skills/evaluate-skill/scripts/lib/runner.mjs +36 -14
  132. package/skills/evaluate-skill/scripts/lib/sandbox.mjs +92 -0
  133. package/skills/evaluate-skill/scripts/pi-guard.mjs +1 -1
  134. package/skills/evaluate-skill/scripts/pi-observer.mjs +66 -0
  135. package/skills/evaluate-skill/scripts/skill-eval.mjs +6 -5
  136. package/skills/execute-work/SKILL.md +99 -57
  137. package/skills/execute-work/references/code-practices.md +4 -4
  138. package/skills/execute-work/references/execute-work-edges.md +62 -0
  139. package/skills/finish-branch/SKILL.md +2 -2
  140. package/skills/finish-branch/references/integration-options.md +1 -1
  141. package/skills/handoff/SKILL.md +3 -3
  142. package/skills/launch-work/SKILL.md +1 -1
  143. package/skills/launch-work/references/launch-readiness.md +2 -2
  144. package/skills/migration-work/SKILL.md +2 -2
  145. package/skills/migration-work/references/migration-lifecycle.md +1 -1
  146. package/skills/release-work/SKILL.md +1 -1
  147. package/skills/release-work/references/release-evidence.md +1 -1
  148. package/skills/review-artifact/SKILL.md +129 -66
  149. package/skills/review-artifact/references/adjudicate-artifact-review.md +101 -0
  150. package/skills/review-artifact/references/independent-artifact-reviewer-contract.md +159 -0
  151. package/skills/review-work/SKILL.md +113 -68
  152. package/skills/review-work/references/adjudicate-work-review.md +97 -0
  153. package/skills/review-work/references/independent-work-reviewer-contract.md +139 -0
  154. package/skills/review-work/references/security-risk-lens.md +18 -16
  155. package/skills/setup-freeflow/SKILL.md +16 -17
  156. package/skills/setup-freeflow/references/activation-contract.md +24 -30
  157. package/skills/setup-freeflow/references/host-setup.md +6 -7
  158. package/skills/simplify-code/SKILL.md +97 -39
  159. package/skills/simplify-code/references/simplification-patterns.md +1 -1
  160. package/skills/tdd/SKILL.md +100 -53
  161. package/skills/tdd/references/test-design.md +3 -3
  162. package/skills/track-work/SKILL.md +195 -58
  163. package/skills/track-work/references/working-record-format.md +515 -0
  164. package/skills/track-work/scripts/lib/document.mjs +713 -0
  165. package/skills/track-work/scripts/lib/format.mjs +166 -0
  166. package/skills/track-work/scripts/lib/store.mjs +233 -0
  167. package/skills/track-work/scripts/lib/transitions.mjs +790 -0
  168. package/skills/track-work/scripts/lib/views.mjs +40 -0
  169. package/skills/track-work/scripts/working-record.mjs +316 -0
  170. package/skills/verify-work/SKILL.md +57 -19
  171. package/skills/verify-work/references/browser-runtime-evidence.md +2 -2
  172. package/skills/verify-work/references/integration-evidence.md +1 -7
  173. package/skills/verify-work/references/performance-evidence.md +2 -2
  174. package/skills/workflow/SKILL.md +137 -55
  175. package/skills/workflow/references/domain-skill-composition.md +26 -40
  176. package/skills/write-plan/SKILL.md +1 -1
  177. package/skills/write-skill/SKILL.md +218 -61
  178. package/skills/write-skill/references/activation-boundaries.md +63 -21
  179. package/skills/write-skill/references/agent-first-instructions.md +61 -27
  180. package/skills/write-skill/references/progressive-disclosure.md +97 -33
  181. package/skills/write-skill/references/skill-dependency-graphs.md +190 -0
  182. package/capabilities/output-router/SKILL.md +0 -206
  183. package/capabilities/output-router/references/safety-policy.md +0 -40
  184. package/capabilities/output-router/references/setup.md +0 -110
  185. package/pi-extension/dist/output-router/host-producer-identification.js +0 -232
  186. package/pi-extension/dist/output-router/native-safety-net.js +0 -216
  187. package/pi-extension/dist/output-router/observed-tool-routing.js +0 -122
  188. package/pi-extension/dist/output-router/renderers.js +0 -1023
  189. package/pi-extension/dist/output-router/router-tools.js +0 -554
  190. package/pi-extension/dist/output-router/schemas.js +0 -383
  191. package/pi-extension/dist/output-router/status.js +0 -744
  192. package/pi-extension/dist/output-router/utils.js +0 -502
  193. package/pi-extension/src/output-router/host-producer-identification.ts +0 -256
  194. package/pi-extension/src/output-router/native-safety-net.ts +0 -248
  195. package/pi-extension/src/output-router/observed-tool-routing.ts +0 -134
  196. package/pi-extension/src/output-router/renderers.ts +0 -1108
  197. package/pi-extension/src/output-router/router-tools.ts +0 -579
  198. package/pi-extension/src/output-router/schemas.ts +0 -387
  199. package/pi-extension/src/output-router/status.ts +0 -791
  200. package/pi-extension/src/output-router/utils.ts +0 -554
  201. package/pi-extension/tests/output-router/observed-producers.test.js +0 -132
  202. package/pi-extension/tests/output-router/search.test.js +0 -722
  203. package/router/dist/benchmarks/benchmark-harness.d.ts +0 -35
  204. package/router/dist/benchmarks/benchmark-harness.js +0 -92
  205. package/router/dist/benchmarks/benchmarks.d.ts +0 -109
  206. package/router/dist/benchmarks/benchmarks.js +0 -979
  207. package/router/dist/benchmarks/codex-qa-benchmarks.d.ts +0 -95
  208. package/router/dist/benchmarks/codex-qa-benchmarks.js +0 -500
  209. package/router/dist/benchmarks/command-benchmarks.d.ts +0 -143
  210. package/router/dist/benchmarks/command-benchmarks.js +0 -698
  211. package/router/dist/benchmarks/context-mode-normalized-benchmarks.d.ts +0 -82
  212. package/router/dist/benchmarks/context-mode-normalized-benchmarks.js +0 -773
  213. package/router/dist/benchmarks/context-mode-real-deep-benchmark.d.ts +0 -132
  214. package/router/dist/benchmarks/context-mode-real-deep-benchmark.js +0 -1380
  215. package/router/dist/benchmarks/context-saving-baseline.d.ts +0 -60
  216. package/router/dist/benchmarks/context-saving-baseline.js +0 -470
  217. package/router/dist/benchmarks/index-benchmarks.d.ts +0 -103
  218. package/router/dist/benchmarks/index-benchmarks.js +0 -862
  219. package/router/dist/benchmarks/storage-policy-benchmarks.d.ts +0 -101
  220. package/router/dist/benchmarks/storage-policy-benchmarks.js +0 -618
  221. package/router/dist/benchmarks/vault-index-benchmarks.d.ts +0 -56
  222. package/router/dist/benchmarks/vault-index-benchmarks.js +0 -322
  223. package/router/dist/config/config.d.ts +0 -103
  224. package/router/dist/config/config.js +0 -632
  225. package/router/dist/config/router-contract.d.ts +0 -10
  226. package/router/dist/config/router-contract.js +0 -54
  227. package/router/dist/config/schema.d.ts +0 -27
  228. package/router/dist/config/schema.js +0 -648
  229. package/router/dist/config/types.d.ts +0 -573
  230. package/router/dist/config/types.js +0 -41
  231. package/router/dist/evidence/bounded-evidence.d.ts +0 -40
  232. package/router/dist/evidence/bounded-evidence.js +0 -323
  233. package/router/dist/evidence/evidence-range-selector.d.ts +0 -24
  234. package/router/dist/evidence/evidence-range-selector.js +0 -232
  235. package/router/dist/evidence/evidence-search.d.ts +0 -27
  236. package/router/dist/evidence/evidence-search.js +0 -490
  237. package/router/dist/evidence/evidence.d.ts +0 -38
  238. package/router/dist/evidence/evidence.js +0 -200
  239. package/router/dist/evidence/failure-contracts.d.ts +0 -37
  240. package/router/dist/evidence/failure-contracts.js +0 -166
  241. package/router/dist/evidence/line-ranges.d.ts +0 -24
  242. package/router/dist/evidence/line-ranges.js +0 -22
  243. package/router/dist/experiments/local-index.d.ts +0 -64
  244. package/router/dist/experiments/local-index.js +0 -581
  245. package/router/dist/index.d.ts +0 -30
  246. package/router/dist/index.js +0 -32
  247. package/router/dist/local/local-traversal.d.ts +0 -18
  248. package/router/dist/local/local-traversal.js +0 -334
  249. package/router/dist/processing/engine.d.ts +0 -132
  250. package/router/dist/processing/engine.js +0 -533
  251. package/router/dist/processing/reducers.d.ts +0 -280
  252. package/router/dist/processing/reducers.js +0 -1673
  253. package/router/dist/processing/renderers.d.ts +0 -31
  254. package/router/dist/processing/renderers.js +0 -195
  255. package/router/dist/processing/scripts.d.ts +0 -91
  256. package/router/dist/processing/scripts.js +0 -386
  257. package/router/dist/repo/repo-traversal.d.ts +0 -18
  258. package/router/dist/repo/repo-traversal.js +0 -245
  259. package/router/dist/routing/observed-reducers.d.ts +0 -41
  260. package/router/dist/routing/observed-reducers.js +0 -661
  261. package/router/dist/routing/observed-routing.d.ts +0 -26
  262. package/router/dist/routing/observed-routing.js +0 -378
  263. package/router/dist/routing/parsers.d.ts +0 -16
  264. package/router/dist/routing/parsers.js +0 -521
  265. package/router/dist/routing/run-filters.d.ts +0 -60
  266. package/router/dist/routing/run-filters.js +0 -238
  267. package/router/dist/routing/run-reducers.d.ts +0 -49
  268. package/router/dist/routing/run-reducers.js +0 -122
  269. package/router/dist/sandbox/adapter-roots.d.ts +0 -46
  270. package/router/dist/sandbox/adapter-roots.js +0 -66
  271. package/router/dist/sandbox/eryx-python-adapter.d.ts +0 -13
  272. package/router/dist/sandbox/eryx-python-adapter.js +0 -868
  273. package/router/dist/sandbox/jq-wasm-adapter.d.ts +0 -9
  274. package/router/dist/sandbox/jq-wasm-adapter.js +0 -429
  275. package/router/dist/sandbox/quickjs-wasi-adapter.d.ts +0 -13
  276. package/router/dist/sandbox/quickjs-wasi-adapter.js +0 -384
  277. package/router/dist/sandbox/script-sandbox.d.ts +0 -134
  278. package/router/dist/sandbox/script-sandbox.js +0 -337
  279. package/router/dist/setup/script-transform-adapters.d.ts +0 -32
  280. package/router/dist/setup/script-transform-adapters.js +0 -278
  281. package/router/dist/tools/batch.d.ts +0 -33
  282. package/router/dist/tools/batch.js +0 -586
  283. package/router/dist/tools/run.d.ts +0 -62
  284. package/router/dist/tools/run.js +0 -1304
  285. package/router/dist/tools/search.d.ts +0 -66
  286. package/router/dist/tools/search.js +0 -1364
  287. package/router/dist/transform/engine.d.ts +0 -168
  288. package/router/dist/transform/engine.js +0 -2072
  289. package/router/dist/vault/vault-index.d.ts +0 -125
  290. package/router/dist/vault/vault-index.js +0 -416
  291. package/router/dist/vault/vault.d.ts +0 -138
  292. package/router/dist/vault/vault.js +0 -630
  293. package/runtime/interaction-contract.md +0 -16
  294. package/skills/discuss/references/checkpoints.md +0 -66
  295. package/skills/execute-work/references/execution-loop.md +0 -77
  296. package/skills/mode-contract/SKILL.md +0 -104
  297. package/skills/review-artifact/references/reviewer-prompt.md +0 -148
  298. package/skills/review-work/references/reviewer-prompt.md +0 -134
  299. package/skills/track-work/references/working-record-schema.md +0 -378
  300. package/skills/workflow/references/workflow-loop.md +0 -92
  301. /package/skills/handoff/references/{templates.md → handoff-templates.md} +0 -0
@@ -1,95 +0,0 @@
1
- export interface RunCodexQaBenchmarksOptions {
2
- iterations?: number;
3
- generatedAt?: string;
4
- }
5
- export interface CodexQaBenchmarkReport {
6
- generatedAt: string;
7
- iterations: number;
8
- summary: CodexQaBenchmarkSummary;
9
- fixtures: CodexQaBenchmarkFixtureResult[];
10
- skippedExternalTools: CodexQaSkippedExternalTool[];
11
- }
12
- export interface CodexQaBenchmarkSummary {
13
- fixtures: number;
14
- modeResults: number;
15
- improved: CodexQaModeSummary;
16
- nativeBaseline: CodexQaModeSummary;
17
- sandboxFailureFixed: boolean;
18
- generatedFalsePositiveCount: number;
19
- }
20
- export interface CodexQaModeSummary {
21
- passed: number;
22
- failed: number;
23
- skipped: number;
24
- answerCorrect: number;
25
- citationCorrect: number;
26
- evidenceCorrect: number;
27
- generatedFalsePositiveCount: number;
28
- totalRawBytes: number;
29
- totalContextBytes: number;
30
- totalRawTokensApprox: number;
31
- totalContextTokensApprox: number;
32
- weightedByteReductionPercent: number;
33
- weightedTokenReductionPercent: number;
34
- }
35
- export interface CodexQaBenchmarkFixtureResult {
36
- id: string;
37
- title: string;
38
- question: string;
39
- expected: CodexQaExpected;
40
- results: CodexQaModeResult[];
41
- }
42
- export interface CodexQaExpected {
43
- path: string;
44
- requiredEvidence: string[];
45
- requiredAnswer: string[];
46
- sourceCitationStatus: "skipped-unavailable" | "checked";
47
- }
48
- export interface CodexQaModeResult {
49
- mode: CodexQaBenchmarkMode;
50
- toolPathUsed: string;
51
- skipped: boolean;
52
- skipReason?: string;
53
- proxyCalls: number;
54
- rawBytes: number;
55
- rawTokensApprox: number;
56
- contextBytes: number;
57
- contextTokensApprox: number;
58
- byteReductionPercent: number;
59
- tokenReductionPercent: number;
60
- latencyMs: {
61
- p50: number;
62
- p95: number;
63
- };
64
- actualPath?: string;
65
- actualLines?: string;
66
- answer: string;
67
- evidenceExcerpt: string;
68
- correctness: CodexQaCorrectness;
69
- notes: string[];
70
- }
71
- export interface CodexQaCorrectness {
72
- passed: boolean;
73
- answerCorrect: boolean;
74
- citationCorrect: boolean;
75
- evidenceCorrect: boolean;
76
- generatedFalsePositive: boolean;
77
- }
78
- export interface CodexQaSkippedExternalTool {
79
- name: string;
80
- reason: string;
81
- }
82
- type CodexQaBenchmarkMode = "native-broad-search-proxy" | "improved-freeflow-router";
83
- export declare function runCodexQaBenchmarks(options?: RunCodexQaBenchmarksOptions): Promise<CodexQaBenchmarkReport>;
84
- export declare function writeCodexQaBenchmarkReports(
85
- report: CodexQaBenchmarkReport,
86
- markdownReportPath: string,
87
- options?: {
88
- jsonReportPath?: string | false | undefined;
89
- },
90
- ): Promise<{
91
- markdown: string;
92
- json?: string;
93
- }>;
94
- export declare function renderCodexQaBenchmarkReport(report: CodexQaBenchmarkReport): string;
95
- export {};
@@ -1,500 +0,0 @@
1
- import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
2
- import { tmpdir } from "node:os";
3
- import { dirname, join, relative, resolve } from "node:path";
4
- import { fileURLToPath } from "node:url";
5
- import { performance } from "node:perf_hooks";
6
- import {
7
- approximateTokens,
8
- defaultJsonRunReportPath,
9
- escapeMarkdownTableCell as escapeTable,
10
- formatPercent,
11
- latencySummary,
12
- normalizeIterations,
13
- parseBenchmarkCliArgs,
14
- reductionPercent,
15
- writeBenchmarkReportPair,
16
- } from "./benchmark-harness.js";
17
- import { freeflowSearch } from "../tools/search.js";
18
- const SANDBOX_DOC_PATH = "router/evals/fixtures/output-router-corpus/sandbox-permissions.md";
19
- const GENERATED_GRAPH_PATH = "graphify-out/graph.html";
20
- const SANDBOX_QUESTION =
21
- "Find the Sandbox Permissions section, report file/lines, and explain UseDefault, RequireEscalated, and WithAdditionalPermissions.";
22
- const SANDBOX_QUERY =
23
- "Sandbox Permissions SandboxPermissions UseDefault RequireEscalated WithAdditionalPermissions Plain-language meaning";
24
- const SANDBOX_REQUIRED_EVIDENCE = [
25
- "SandboxPermissions is a per-command request shape",
26
- "UseDefault",
27
- "Run with the turn's normal sandbox",
28
- "RequireEscalated",
29
- "Request unsandboxed execution",
30
- "WithAdditionalPermissions",
31
- "Stay sandboxed but widen permissions for this one command",
32
- ];
33
- const SANDBOX_REQUIRED_ANSWER = [
34
- "UseDefault: run with the turn's normal sandbox",
35
- "RequireEscalated: request unsandboxed execution",
36
- "WithAdditionalPermissions: stay sandboxed but widen permissions for this one command",
37
- ];
38
- export async function runCodexQaBenchmarks(options = {}) {
39
- const iterations = normalizeIterations(options.iterations, 1);
40
- const fixture = await createSandboxPermissionsFixture();
41
- try {
42
- const results = [];
43
- const modeResults = [];
44
- for (const mode of ["native-broad-search-proxy", "improved-freeflow-router"]) {
45
- modeResults.push(await runModeIterations(fixture, mode, iterations));
46
- }
47
- results.push({
48
- id: fixture.id,
49
- title: fixture.title,
50
- question: fixture.question,
51
- expected: fixture.expected,
52
- results: modeResults,
53
- });
54
- return {
55
- generatedAt: options.generatedAt ?? new Date().toISOString(),
56
- iterations,
57
- summary: summarizeCodexQaReport(results),
58
- fixtures: results,
59
- skippedExternalTools: skippedExternalTools(),
60
- };
61
- } finally {
62
- await fixture.cleanup();
63
- }
64
- }
65
- export async function writeCodexQaBenchmarkReports(report, markdownReportPath, options = {}) {
66
- return writeBenchmarkReportPair({
67
- report,
68
- markdownReportPath,
69
- jsonReportPath: options.jsonReportPath ?? defaultJsonRunReportPath(markdownReportPath),
70
- renderMarkdown: renderCodexQaBenchmarkReport,
71
- });
72
- }
73
- export function renderCodexQaBenchmarkReport(report) {
74
- const lines = [
75
- "# Codex Structured Q&A Macro Benchmark Report - Iteration 1",
76
- "",
77
- `Date: ${report.generatedAt.slice(0, 10)}`,
78
- "",
79
- "## Scope",
80
- "",
81
- "Fast, deterministic Stage 1 macro benchmark for the neutral Output Router research corpus. The benchmark asks one structured Q&A question from the Sandbox Permissions fixture and grades retrieval-backed answer quality, citation quality, evidence quality, context size, and latency.",
82
- "",
83
- "The fixture uses existing Freeflow research docs as oracle scaffolding and includes a generated `graphify-out` decoy to preserve the original broad-retrieval failure shape. Upstream Codex source citation comparison is marked skipped until a source snapshot is explicitly supplied.",
84
- "",
85
- "## Command",
86
- "",
87
- "```sh",
88
- "npm run bench:router:codex-qa",
89
- "```",
90
- "",
91
- "The CLI writes machine-readable JSON under `router/evals/runs/` by default. That JSON is generated run data; this Markdown file is the durable runtime report.",
92
- "",
93
- "## Summary",
94
- "",
95
- `- Iterations per mode: ${report.iterations}`,
96
- `- Fixtures: ${report.summary.fixtures}`,
97
- `- Improved Freeflow Router gated pass: ${report.summary.improved.passed}/${report.summary.fixtures}`,
98
- `- Native broad-search proxy pass: ${report.summary.nativeBaseline.passed}/${report.summary.fixtures}`,
99
- `- Sandbox failure fixed: ${report.summary.sandboxFailureFixed ? "yes" : "no"}`,
100
- `- Generated false positives observed: ${report.summary.generatedFalsePositiveCount}/${report.summary.modeResults} mode results`,
101
- `- Improved answer/citation/evidence: ${report.summary.improved.answerCorrect}/${report.summary.fixtures} answer, ${report.summary.improved.citationCorrect}/${report.summary.fixtures} citation, ${report.summary.improved.evidenceCorrect}/${report.summary.fixtures} evidence`,
102
- `- Improved weighted byte/token reduction: ${formatPercent(report.summary.improved.weightedByteReductionPercent)} / ${formatPercent(report.summary.improved.weightedTokenReductionPercent)} (${report.summary.improved.totalRawBytes}/${report.summary.improved.totalRawTokensApprox} raw to ${report.summary.improved.totalContextBytes}/${report.summary.improved.totalContextTokensApprox} context)`,
103
- "",
104
- "## Results",
105
- "",
106
- "| fixture | mode | correctness | checks | path | lines | raw bytes/tokens | context bytes/tokens | byte/token reduction | latency p50/p95 ms | proxy calls | answer | notes |",
107
- "| --- | --- | --- | --- | --- | --- | ---: | ---: | ---: | ---: | ---: | --- | --- |",
108
- ];
109
- for (const fixture of report.fixtures) {
110
- for (const result of fixture.results) {
111
- lines.push(
112
- [
113
- fixture.id,
114
- result.mode,
115
- result.correctness.passed ? "pass" : "fail",
116
- `answer ${mark(result.correctness.answerCorrect)} citation ${mark(result.correctness.citationCorrect)} evidence ${mark(result.correctness.evidenceCorrect)} gen-fp ${mark(!result.correctness.generatedFalsePositive)}`,
117
- result.actualPath ?? "-",
118
- result.actualLines ?? "-",
119
- `${result.rawBytes}/${result.rawTokensApprox}`,
120
- `${result.contextBytes}/${result.contextTokensApprox}`,
121
- `${formatPercent(result.byteReductionPercent)}/${formatPercent(result.tokenReductionPercent)}`,
122
- `${result.latencyMs.p50.toFixed(2)}/${result.latencyMs.p95.toFixed(2)}`,
123
- String(result.proxyCalls),
124
- result.answer,
125
- result.notes.join("; "),
126
- ]
127
- .map((cell) => escapeTable(String(cell)))
128
- .join(" | ")
129
- .replace(/^/, "|")
130
- .replace(/$/, " |"),
131
- );
132
- }
133
- }
134
- lines.push("", "## Fixture Questions", "");
135
- for (const fixture of report.fixtures) {
136
- lines.push(`- ${fixture.id}: ${fixture.question}`);
137
- lines.push(` - expected doc: \`${fixture.expected.path}\``);
138
- lines.push(` - upstream source citation comparison: ${fixture.expected.sourceCitationStatus}`);
139
- }
140
- lines.push("", "## Skipped External Comparators", "");
141
- for (const skipped of report.skippedExternalTools) {
142
- lines.push(`- ${skipped.name}: ${skipped.reason}`);
143
- }
144
- return `${lines.join("\n")}\n`;
145
- }
146
- async function runModeIterations(fixture, mode, iterations) {
147
- const latencies = [];
148
- let firstObservation;
149
- for (let index = 0; index < iterations; index += 1) {
150
- const startedAt = performance.now();
151
- const observation =
152
- mode === "native-broad-search-proxy"
153
- ? await nativeBroadSearchObservation(fixture)
154
- : await improvedFreeflowObservation(fixture);
155
- latencies.push(performance.now() - startedAt);
156
- firstObservation ??= observation;
157
- }
158
- if (!firstObservation) {
159
- throw new Error("Codex Q&A benchmark produced no observation");
160
- }
161
- const correctness = gradeObservation(fixture, firstObservation);
162
- return {
163
- mode,
164
- toolPathUsed: firstObservation.toolPathUsed,
165
- skipped: false,
166
- proxyCalls: firstObservation.proxyCalls,
167
- rawBytes: firstObservation.rawBytes,
168
- rawTokensApprox: approximateTokens(firstObservation.rawBytes),
169
- contextBytes: firstObservation.contextBytes,
170
- contextTokensApprox: approximateTokens(firstObservation.contextBytes),
171
- byteReductionPercent: reductionPercent(firstObservation.rawBytes, firstObservation.contextBytes),
172
- tokenReductionPercent: reductionPercent(
173
- approximateTokens(firstObservation.rawBytes),
174
- approximateTokens(firstObservation.contextBytes),
175
- ),
176
- latencyMs: latencySummary(latencies),
177
- ...(firstObservation.actualPath !== undefined ? { actualPath: firstObservation.actualPath } : {}),
178
- ...(firstObservation.actualLines !== undefined ? { actualLines: firstObservation.actualLines } : {}),
179
- answer: firstObservation.answer,
180
- evidenceExcerpt: firstObservation.evidenceExcerpt,
181
- correctness,
182
- notes: firstObservation.notes,
183
- };
184
- }
185
- async function improvedFreeflowObservation(fixture) {
186
- const queryResult = await freeflowSearch({
187
- action: "query",
188
- source: { kind: "repo", root: fixture.root },
189
- query: fixture.query,
190
- preserve: "important",
191
- topK: 1,
192
- });
193
- const seedEvidence = queryResult.evidence?.[0];
194
- const expandedResult = seedEvidence
195
- ? await freeflowSearch({
196
- action: "expand",
197
- source: { kind: "repo", root: fixture.root },
198
- evidence: seedEvidence,
199
- expansion: "lines_30",
200
- preserve: "important",
201
- })
202
- : undefined;
203
- const evidence = expandedResult?.evidence?.[0] ?? seedEvidence;
204
- const evidenceExcerpt = evidence?.excerpt ?? "";
205
- return {
206
- toolPathUsed: "freeflowSearch repo query + expand",
207
- proxyCalls: expandedResult ? 2 : 1,
208
- rawBytes: await repoRawBytes(fixture.root),
209
- contextBytes: byteLength(JSON.stringify(queryResult)) + byteLength(JSON.stringify(expandedResult ?? {})),
210
- ...(evidence?.path !== undefined ? { actualPath: evidence.path } : {}),
211
- ...(evidence?.lines !== undefined ? { actualLines: evidence.lines } : {}),
212
- evidenceExcerpt,
213
- answer: answerFromEvidence(evidence, evidenceExcerpt),
214
- notes: [
215
- queryResult.routing.reason,
216
- ...(expandedResult ? [expandedResult.routing.reason] : ["expand skipped: no seed evidence"]),
217
- ],
218
- };
219
- }
220
- async function nativeBroadSearchObservation(fixture) {
221
- const files = await readRepoTextFiles(fixture.root);
222
- const tokens = tokenize(fixture.query);
223
- const scored = files
224
- .map((file) => ({ ...file, score: scoreText(file.text, tokens) }))
225
- .filter((file) => file.score > 0)
226
- .sort((a, b) => b.score - a.score || b.bytes - a.bytes || a.path.localeCompare(b.path));
227
- const selected = scored[0];
228
- const evidenceExcerpt = selected?.text ?? "";
229
- return {
230
- toolPathUsed: "native broad text-search proxy including generated artifacts",
231
- proxyCalls: 1,
232
- rawBytes: await repoRawBytes(fixture.root),
233
- contextBytes: byteLength(evidenceExcerpt),
234
- ...(selected?.path !== undefined ? { actualPath: selected.path } : {}),
235
- ...(selected ? { actualLines: `1-${selected.lineCount}` } : {}),
236
- evidenceExcerpt,
237
- answer: answerFromEvidence(
238
- selected ? { path: selected.path, lines: `1-${selected.lineCount}` } : undefined,
239
- evidenceExcerpt,
240
- ),
241
- notes: selected ? [`lexical score=${selected.score}`] : ["no native match"],
242
- };
243
- }
244
- function gradeObservation(fixture, observation) {
245
- const answerCorrect = fixture.expected.requiredAnswer.every((phrase) =>
246
- includesNormalized(observation.answer, phrase),
247
- );
248
- const citationCorrect =
249
- observation.actualPath === fixture.expected.path && typeof observation.actualLines === "string";
250
- const evidenceCorrect = fixture.expected.requiredEvidence.every((phrase) =>
251
- includesNormalized(observation.evidenceExcerpt, phrase),
252
- );
253
- const generatedFalsePositive = observation.actualPath?.startsWith("graphify-out/") ?? false;
254
- return {
255
- passed: answerCorrect && citationCorrect && evidenceCorrect && !generatedFalsePositive,
256
- answerCorrect,
257
- citationCorrect,
258
- evidenceCorrect,
259
- generatedFalsePositive,
260
- };
261
- }
262
- function summarizeCodexQaReport(fixtures) {
263
- const improved = summarizeMode(fixtures, "improved-freeflow-router");
264
- const nativeBaseline = summarizeMode(fixtures, "native-broad-search-proxy");
265
- const modeResults = fixtures.reduce((count, fixture) => count + fixture.results.length, 0);
266
- const generatedFalsePositiveCount = fixtures
267
- .flatMap((fixture) => fixture.results)
268
- .filter((result) => result.correctness.generatedFalsePositive).length;
269
- return {
270
- fixtures: fixtures.length,
271
- modeResults,
272
- improved,
273
- nativeBaseline,
274
- sandboxFailureFixed: improved.failed === 0 && nativeBaseline.generatedFalsePositiveCount > 0,
275
- generatedFalsePositiveCount,
276
- };
277
- }
278
- function summarizeMode(fixtures, mode) {
279
- const results = fixtures
280
- .map((fixture) => fixture.results.find((result) => result.mode === mode))
281
- .filter((result) => Boolean(result));
282
- const totalRawBytes = results.reduce((sum, result) => sum + result.rawBytes, 0);
283
- const totalContextBytes = results.reduce((sum, result) => sum + result.contextBytes, 0);
284
- const totalRawTokensApprox = results.reduce((sum, result) => sum + result.rawTokensApprox, 0);
285
- const totalContextTokensApprox = results.reduce((sum, result) => sum + result.contextTokensApprox, 0);
286
- return results.reduce(
287
- (summary, result) => {
288
- if (result.skipped) {
289
- summary.skipped += 1;
290
- } else if (result.correctness.passed) {
291
- summary.passed += 1;
292
- } else {
293
- summary.failed += 1;
294
- }
295
- if (result.correctness.answerCorrect) {
296
- summary.answerCorrect += 1;
297
- }
298
- if (result.correctness.citationCorrect) {
299
- summary.citationCorrect += 1;
300
- }
301
- if (result.correctness.evidenceCorrect) {
302
- summary.evidenceCorrect += 1;
303
- }
304
- if (result.correctness.generatedFalsePositive) {
305
- summary.generatedFalsePositiveCount += 1;
306
- }
307
- return summary;
308
- },
309
- {
310
- passed: 0,
311
- failed: 0,
312
- skipped: 0,
313
- answerCorrect: 0,
314
- citationCorrect: 0,
315
- evidenceCorrect: 0,
316
- generatedFalsePositiveCount: 0,
317
- totalRawBytes,
318
- totalContextBytes,
319
- totalRawTokensApprox,
320
- totalContextTokensApprox,
321
- weightedByteReductionPercent: reductionPercent(totalRawBytes, totalContextBytes),
322
- weightedTokenReductionPercent: reductionPercent(totalRawTokensApprox, totalContextTokensApprox),
323
- },
324
- );
325
- }
326
- async function createSandboxPermissionsFixture() {
327
- const root = await mkdtemp(join(tmpdir(), "freeflow-codex-qa-fixture-"));
328
- await writeTextFile(join(root, SANDBOX_DOC_PATH), sandboxDocumentText());
329
- await writeTextFile(
330
- join(root, GENERATED_GRAPH_PATH),
331
- [
332
- "<html><body>",
333
- `${"Sandbox Permissions SandboxPermissions UseDefault RequireEscalated WithAdditionalPermissions Plain-language meaning ".repeat(5_000)}GENERATED_GRAPH_DECOY_SENTINEL`,
334
- "</body></html>",
335
- ].join("\n"),
336
- );
337
- return {
338
- id: "sandbox-permissions-structured-qa",
339
- title: "Sandbox Permissions structured Q&A",
340
- question: SANDBOX_QUESTION,
341
- query: SANDBOX_QUERY,
342
- expected: {
343
- path: SANDBOX_DOC_PATH,
344
- requiredEvidence: SANDBOX_REQUIRED_EVIDENCE,
345
- requiredAnswer: SANDBOX_REQUIRED_ANSWER,
346
- sourceCitationStatus: "skipped-unavailable",
347
- },
348
- root,
349
- cleanup: () => rm(root, { recursive: true, force: true }),
350
- };
351
- }
352
- function sandboxDocumentText() {
353
- return [
354
- "# Pass 3",
355
- "",
356
- "### Sandbox Permissions",
357
- "",
358
- "SandboxPermissions is a per-command request shape.",
359
- "",
360
- "Codex defines:",
361
- "",
362
- "```text",
363
- "UseDefault",
364
- "RequireEscalated",
365
- "WithAdditionalPermissions",
366
- "```",
367
- "",
368
- "Plain-language meaning:",
369
- "",
370
- "```text",
371
- "UseDefault:",
372
- " Run with the turn's normal sandbox.",
373
- "",
374
- "RequireEscalated:",
375
- " Request unsandboxed execution.",
376
- "",
377
- "WithAdditionalPermissions:",
378
- " Stay sandboxed but widen permissions for this one command.",
379
- "```",
380
- "",
381
- "This is a strong pattern for local agents.",
382
- ].join("\n");
383
- }
384
- function answerFromEvidence(evidence, text) {
385
- const citation = evidence?.path ? `${evidence.path}${evidence.lines ? `:${evidence.lines}` : ""}` : "unknown source";
386
- const facts = [];
387
- if (includesNormalized(text, "Run with the turn's normal sandbox")) {
388
- facts.push("UseDefault: run with the turn's normal sandbox");
389
- }
390
- if (includesNormalized(text, "Request unsandboxed execution")) {
391
- facts.push("RequireEscalated: request unsandboxed execution");
392
- }
393
- if (includesNormalized(text, "Stay sandboxed but widen permissions for this one command")) {
394
- facts.push("WithAdditionalPermissions: stay sandboxed but widen permissions for this one command");
395
- }
396
- if (facts.length === 0) {
397
- return `Sandbox Permissions evidence from ${citation} did not include enough plain-language definitions to answer.`;
398
- }
399
- return `Sandbox Permissions are documented at ${citation}. ${facts.join(". ")}.`;
400
- }
401
- async function readRepoTextFiles(root) {
402
- const files = [];
403
- await walk(root, async (absolutePath) => {
404
- const text = await readFile(absolutePath, "utf8");
405
- files.push({
406
- path: relative(root, absolutePath),
407
- text,
408
- bytes: byteLength(text),
409
- lineCount: text.length === 0 ? 1 : text.split("\n").length,
410
- });
411
- });
412
- return files;
413
- }
414
- async function repoRawBytes(root) {
415
- let total = 0;
416
- await walk(root, async (absolutePath) => {
417
- total += (await stat(absolutePath)).size;
418
- });
419
- return total;
420
- }
421
- async function walk(root, visit) {
422
- const entries = await readdir(root, { withFileTypes: true });
423
- for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
424
- const absolutePath = join(root, entry.name);
425
- if (entry.isDirectory()) {
426
- await walk(absolutePath, visit);
427
- } else if (entry.isFile()) {
428
- await visit(absolutePath);
429
- }
430
- }
431
- }
432
- async function writeTextFile(path, text) {
433
- await mkdir(dirname(path), { recursive: true });
434
- await writeFile(path, text, "utf8");
435
- }
436
- function scoreText(text, queryTokens) {
437
- const counts = tokenCounts(text);
438
- return queryTokens.reduce((score, token) => score + (counts.get(token) ?? 0), 0);
439
- }
440
- function tokenCounts(text) {
441
- const counts = new Map();
442
- for (const token of tokenize(text)) {
443
- counts.set(token, (counts.get(token) ?? 0) + 1);
444
- }
445
- return counts;
446
- }
447
- function tokenize(text) {
448
- return text.toLowerCase().match(/[a-z0-9_./-]+/g) ?? [];
449
- }
450
- function includesNormalized(text, phrase) {
451
- return normalizeText(text).includes(normalizeText(phrase));
452
- }
453
- function normalizeText(text) {
454
- return text.toLowerCase().replace(/[`*_]/g, "").replace(/\s+/g, " ").trim();
455
- }
456
- function mark(value) {
457
- return value ? "✓" : "✗";
458
- }
459
- function byteLength(text) {
460
- return Buffer.byteLength(text, "utf8");
461
- }
462
- function skippedExternalTools() {
463
- return [
464
- {
465
- name: "Graphify",
466
- reason: "Skipped unless a fresh graph for the benchmark fixture is explicitly supplied.",
467
- },
468
- {
469
- name: "Claude Context",
470
- reason: "Skipped unless an index is configured and fresh for the benchmark fixture.",
471
- },
472
- ];
473
- }
474
- function defaultReportPath() {
475
- return resolve(process.cwd(), "router/evals/reports/output-router-codex-qa-benchmark-1-report.md");
476
- }
477
- async function main() {
478
- const { iterations, reportPath, jsonReportPath } = parseBenchmarkCliArgs(process.argv.slice(2), {
479
- reportPath: defaultReportPath(),
480
- });
481
- const options = {};
482
- if (iterations !== undefined) {
483
- options.iterations = iterations;
484
- }
485
- const report = await runCodexQaBenchmarks(options);
486
- const reports = await writeCodexQaBenchmarkReports(report, reportPath, { jsonReportPath });
487
- console.log(
488
- `Freeflow Codex Q&A benchmark: improved ${report.summary.improved.passed}/${report.summary.fixtures} pass; native ${report.summary.nativeBaseline.passed}/${report.summary.fixtures} pass`,
489
- );
490
- console.log(`Markdown report: ${reports.markdown}`);
491
- if (reports.json) {
492
- console.log(`JSON run data: ${reports.json}`);
493
- }
494
- }
495
- if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
496
- main().catch((error) => {
497
- console.error(error);
498
- process.exitCode = 1;
499
- });
500
- }