@hassangameryt/freeflow 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/.codex-plugin/plugin.json +1 -1
  4. package/README.md +148 -154
  5. package/capabilities/cognitive-routing/SKILL.md +229 -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 -13
  9. package/hooks/freeflow-runtime-context.mjs +35 -91
  10. package/hooks/tests/check-runtime-context-hook.sh +56 -39
  11. package/package.json +24 -16
  12. package/pi-extension/dist/cognitive-routing/commands.js +96 -0
  13. package/pi-extension/dist/cognitive-routing/config.js +236 -0
  14. package/pi-extension/dist/cognitive-routing/controller.js +862 -0
  15. package/pi-extension/dist/cognitive-routing/history.js +439 -0
  16. package/pi-extension/dist/cognitive-routing/host.js +126 -0
  17. package/pi-extension/dist/cognitive-routing/runtime.js +43 -0
  18. package/pi-extension/dist/cognitive-routing/tool.js +211 -0
  19. package/pi-extension/dist/cognitive-routing/types.js +6 -0
  20. package/pi-extension/dist/context-virtualization/commands.js +89 -0
  21. package/pi-extension/dist/context-virtualization/projector.js +42 -0
  22. package/pi-extension/dist/context-virtualization/runtime.js +356 -0
  23. package/pi-extension/dist/context-virtualization/state.js +57 -0
  24. package/pi-extension/dist/context-virtualization/types.js +10 -0
  25. package/pi-extension/dist/conversation-history/passages.js +66 -0
  26. package/pi-extension/dist/conversation-history/ranking.js +105 -0
  27. package/pi-extension/dist/conversation-history/runtime.js +226 -0
  28. package/pi-extension/dist/conversation-history/search.js +56 -0
  29. package/pi-extension/dist/conversation-history/types.js +1 -0
  30. package/pi-extension/dist/freeflow-context/resolver.js +120 -0
  31. package/pi-extension/dist/freeflow-context/runtime.js +80 -0
  32. package/pi-extension/dist/freeflow-context/source-projector.js +95 -0
  33. package/pi-extension/dist/freeflow-context/tool.js +308 -0
  34. package/pi-extension/dist/freeflow-context/types.js +12 -0
  35. package/pi-extension/dist/freeflow-context/visibility.js +28 -0
  36. package/pi-extension/dist/index.js +516 -98
  37. package/pi-extension/dist/runtime/runtime-context.js +318 -271
  38. package/pi-extension/dist/runtime/runtime-identity.js +5 -0
  39. package/pi-extension/dist/settings/settings-tui.js +78 -0
  40. package/pi-extension/dist/settings/settings-ui.js +593 -563
  41. package/pi-extension/dist/ui/text-component.js +57 -0
  42. package/pi-extension/src/cognitive-routing/commands.ts +119 -0
  43. package/pi-extension/src/cognitive-routing/config.ts +307 -0
  44. package/pi-extension/src/cognitive-routing/controller.ts +1118 -0
  45. package/pi-extension/src/cognitive-routing/history.ts +638 -0
  46. package/pi-extension/src/cognitive-routing/host.ts +172 -0
  47. package/pi-extension/src/cognitive-routing/runtime.ts +57 -0
  48. package/pi-extension/src/cognitive-routing/tool.ts +272 -0
  49. package/pi-extension/src/cognitive-routing/types.ts +89 -0
  50. package/pi-extension/src/context-virtualization/commands.ts +111 -0
  51. package/pi-extension/src/context-virtualization/projector.ts +62 -0
  52. package/pi-extension/src/context-virtualization/runtime.ts +406 -0
  53. package/pi-extension/src/context-virtualization/state.ts +79 -0
  54. package/pi-extension/src/context-virtualization/types.ts +92 -0
  55. package/pi-extension/src/conversation-history/passages.ts +81 -0
  56. package/pi-extension/src/conversation-history/ranking.ts +155 -0
  57. package/pi-extension/src/conversation-history/runtime.ts +250 -0
  58. package/pi-extension/src/conversation-history/search.ts +79 -0
  59. package/pi-extension/src/conversation-history/types.ts +31 -0
  60. package/pi-extension/src/freeflow-context/resolver.ts +139 -0
  61. package/pi-extension/src/freeflow-context/runtime.ts +100 -0
  62. package/pi-extension/src/freeflow-context/source-projector.ts +106 -0
  63. package/pi-extension/src/freeflow-context/tool.ts +360 -0
  64. package/pi-extension/src/freeflow-context/types.ts +70 -0
  65. package/pi-extension/src/freeflow-context/visibility.ts +53 -0
  66. package/pi-extension/src/index.ts +553 -101
  67. package/pi-extension/src/runtime/runtime-context.ts +339 -281
  68. package/pi-extension/src/runtime/runtime-identity.ts +8 -0
  69. package/pi-extension/src/settings/settings-tui.ts +93 -0
  70. package/pi-extension/src/settings/settings-ui.ts +700 -613
  71. package/pi-extension/src/ui/text-component.ts +66 -0
  72. package/pi-extension/tests/cognitive-routing/commands.test.js +134 -0
  73. package/pi-extension/tests/cognitive-routing/controller.test.js +1099 -0
  74. package/pi-extension/tests/cognitive-routing/extension-lifecycle.test.js +1071 -0
  75. package/pi-extension/tests/cognitive-routing/history.test.js +274 -0
  76. package/pi-extension/tests/cognitive-routing/host-fixture.js +4 -0
  77. package/pi-extension/tests/cognitive-routing/host-identity.test.js +63 -0
  78. package/pi-extension/tests/cognitive-routing/profile-resolution.test.js +236 -0
  79. package/pi-extension/tests/cognitive-routing/tool.test.js +230 -0
  80. package/pi-extension/tests/context-virtualization/extension.test.js +749 -0
  81. package/pi-extension/tests/context-virtualization/projector.test.js +110 -0
  82. package/pi-extension/tests/context-virtualization/runtime.test.js +216 -0
  83. package/pi-extension/tests/conversation-history/runtime.test.js +98 -0
  84. package/pi-extension/tests/conversation-history/search.test.js +97 -0
  85. package/pi-extension/tests/integration/pi-extension.test.js +927 -2048
  86. package/pi-extension/tests/integration/prompt-architecture.test.js +305 -0
  87. package/runtime/prompts/cognitive-routing.md +9 -0
  88. package/runtime/prompts/context-virtualization.md +3 -0
  89. package/runtime/prompts/conversation-history.md +3 -0
  90. package/runtime/prompts/core.md +13 -0
  91. package/runtime/prompts/interaction-contract.md +7 -0
  92. package/runtime/prompts/skills.md +65 -0
  93. package/skills/action-selection/SKILL.md +91 -0
  94. package/skills/bypass/SKILL.md +3 -2
  95. package/skills/commit-work/SKILL.md +1 -1
  96. package/skills/commit-work/references/staging-decisions.md +1 -1
  97. package/skills/decision-gate/SKILL.md +1 -1
  98. package/skills/design-for-depth/SKILL.md +14 -33
  99. package/skills/design-for-depth/references/design-pressure-signals.md +1 -1
  100. package/skills/design-for-depth/references/interface-design-loop.md +1 -1
  101. package/skills/design-for-depth/references/software-design-philosophy.md +1 -1
  102. package/skills/diagnose-failure/SKILL.md +20 -14
  103. package/skills/diagnose-failure/references/diagnostic-loop-catalog.md +1 -3
  104. package/skills/diagnose-failure/references/{flaky-and-performance.md → flaky-and-performance-diagnosis.md} +1 -1
  105. package/skills/discuss/SKILL.md +34 -22
  106. package/skills/discuss/references/discussion-continuity.md +71 -0
  107. package/skills/evaluate-skill/SKILL.md +5 -5
  108. package/skills/evaluate-skill/references/{definition-schema.md → evaluation-definition-schema.md} +42 -2
  109. package/skills/evaluate-skill/references/execution-and-evidence.md +8 -3
  110. package/skills/evaluate-skill/scripts/lib/definitions.mjs +114 -3
  111. package/skills/evaluate-skill/scripts/lib/grade-interaction.mjs +156 -1
  112. package/skills/evaluate-skill/scripts/lib/grade.mjs +9 -1
  113. package/skills/evaluate-skill/scripts/lib/pi.mjs +147 -32
  114. package/skills/evaluate-skill/scripts/lib/rpc.mjs +4 -4
  115. package/skills/evaluate-skill/scripts/lib/runner.mjs +36 -14
  116. package/skills/evaluate-skill/scripts/lib/sandbox.mjs +92 -0
  117. package/skills/evaluate-skill/scripts/pi-guard.mjs +1 -1
  118. package/skills/evaluate-skill/scripts/pi-observer.mjs +66 -0
  119. package/skills/evaluate-skill/scripts/skill-eval.mjs +6 -5
  120. package/skills/execute-work/SKILL.md +18 -15
  121. package/skills/execute-work/references/code-practices.md +1 -1
  122. package/skills/execute-work/references/execute-work-edges.md +42 -0
  123. package/skills/finish-branch/SKILL.md +2 -2
  124. package/skills/finish-branch/references/integration-options.md +1 -1
  125. package/skills/handoff/SKILL.md +3 -3
  126. package/skills/launch-work/SKILL.md +1 -1
  127. package/skills/launch-work/references/launch-readiness.md +2 -2
  128. package/skills/migration-work/SKILL.md +2 -2
  129. package/skills/migration-work/references/migration-lifecycle.md +1 -1
  130. package/skills/mode-contract/SKILL.md +4 -4
  131. package/skills/release-work/SKILL.md +1 -1
  132. package/skills/release-work/references/release-evidence.md +1 -1
  133. package/skills/review-artifact/SKILL.md +28 -26
  134. package/skills/review-work/SKILL.md +28 -26
  135. package/skills/review-work/references/{reviewer-prompt.md → independent-work-reviewer-contract.md} +1 -1
  136. package/skills/review-work/references/security-risk-lens.md +1 -1
  137. package/skills/setup-freeflow/SKILL.md +3 -1
  138. package/skills/setup-freeflow/references/activation-contract.md +2 -2
  139. package/skills/setup-freeflow/references/host-setup.md +2 -2
  140. package/skills/simplify-code/SKILL.md +1 -1
  141. package/skills/simplify-code/references/simplification-patterns.md +1 -1
  142. package/skills/tdd/SKILL.md +18 -38
  143. package/skills/tdd/references/test-design.md +2 -2
  144. package/skills/track-work/SKILL.md +362 -58
  145. package/skills/track-work/scripts/lib/codec.mjs +570 -0
  146. package/skills/track-work/scripts/lib/commands.mjs +568 -0
  147. package/skills/track-work/scripts/lib/contract.mjs +303 -0
  148. package/skills/track-work/scripts/lib/model.mjs +506 -0
  149. package/skills/track-work/scripts/lib/operations.mjs +965 -0
  150. package/skills/track-work/scripts/lib/record-store.mjs +264 -0
  151. package/skills/track-work/scripts/lib/result.mjs +37 -0
  152. package/skills/track-work/scripts/lib/rewrites.mjs +740 -0
  153. package/skills/track-work/scripts/lib/schema.mjs +277 -0
  154. package/skills/track-work/scripts/lib/source-inventory.mjs +162 -0
  155. package/skills/track-work/scripts/lib/views.mjs +443 -0
  156. package/skills/track-work/scripts/lib/workspace.mjs +134 -0
  157. package/skills/track-work/scripts/working-record.mjs +122 -0
  158. package/skills/verify-work/SKILL.md +14 -2
  159. package/skills/verify-work/references/browser-runtime-evidence.md +1 -1
  160. package/skills/verify-work/references/integration-evidence.md +1 -1
  161. package/skills/verify-work/references/performance-evidence.md +1 -1
  162. package/skills/workflow/SKILL.md +105 -53
  163. package/skills/workflow/references/domain-skill-composition.md +22 -42
  164. package/skills/write-plan/SKILL.md +1 -1
  165. package/skills/write-skill/SKILL.md +3 -2
  166. package/skills/write-skill/references/progressive-disclosure.md +17 -3
  167. package/capabilities/output-router/SKILL.md +0 -206
  168. package/capabilities/output-router/references/safety-policy.md +0 -40
  169. package/capabilities/output-router/references/setup.md +0 -110
  170. package/pi-extension/dist/output-router/host-producer-identification.js +0 -232
  171. package/pi-extension/dist/output-router/native-safety-net.js +0 -216
  172. package/pi-extension/dist/output-router/observed-tool-routing.js +0 -122
  173. package/pi-extension/dist/output-router/renderers.js +0 -1023
  174. package/pi-extension/dist/output-router/router-tools.js +0 -554
  175. package/pi-extension/dist/output-router/schemas.js +0 -383
  176. package/pi-extension/dist/output-router/status.js +0 -744
  177. package/pi-extension/dist/output-router/utils.js +0 -502
  178. package/pi-extension/src/output-router/host-producer-identification.ts +0 -256
  179. package/pi-extension/src/output-router/native-safety-net.ts +0 -248
  180. package/pi-extension/src/output-router/observed-tool-routing.ts +0 -134
  181. package/pi-extension/src/output-router/renderers.ts +0 -1108
  182. package/pi-extension/src/output-router/router-tools.ts +0 -579
  183. package/pi-extension/src/output-router/schemas.ts +0 -387
  184. package/pi-extension/src/output-router/status.ts +0 -791
  185. package/pi-extension/src/output-router/utils.ts +0 -554
  186. package/pi-extension/tests/output-router/observed-producers.test.js +0 -132
  187. package/pi-extension/tests/output-router/search.test.js +0 -722
  188. package/router/dist/benchmarks/benchmark-harness.d.ts +0 -35
  189. package/router/dist/benchmarks/benchmark-harness.js +0 -92
  190. package/router/dist/benchmarks/benchmarks.d.ts +0 -109
  191. package/router/dist/benchmarks/benchmarks.js +0 -979
  192. package/router/dist/benchmarks/codex-qa-benchmarks.d.ts +0 -95
  193. package/router/dist/benchmarks/codex-qa-benchmarks.js +0 -500
  194. package/router/dist/benchmarks/command-benchmarks.d.ts +0 -143
  195. package/router/dist/benchmarks/command-benchmarks.js +0 -698
  196. package/router/dist/benchmarks/context-mode-normalized-benchmarks.d.ts +0 -82
  197. package/router/dist/benchmarks/context-mode-normalized-benchmarks.js +0 -773
  198. package/router/dist/benchmarks/context-mode-real-deep-benchmark.d.ts +0 -132
  199. package/router/dist/benchmarks/context-mode-real-deep-benchmark.js +0 -1380
  200. package/router/dist/benchmarks/context-saving-baseline.d.ts +0 -60
  201. package/router/dist/benchmarks/context-saving-baseline.js +0 -470
  202. package/router/dist/benchmarks/index-benchmarks.d.ts +0 -103
  203. package/router/dist/benchmarks/index-benchmarks.js +0 -862
  204. package/router/dist/benchmarks/storage-policy-benchmarks.d.ts +0 -101
  205. package/router/dist/benchmarks/storage-policy-benchmarks.js +0 -618
  206. package/router/dist/benchmarks/vault-index-benchmarks.d.ts +0 -56
  207. package/router/dist/benchmarks/vault-index-benchmarks.js +0 -322
  208. package/router/dist/config/config.d.ts +0 -103
  209. package/router/dist/config/config.js +0 -632
  210. package/router/dist/config/router-contract.d.ts +0 -10
  211. package/router/dist/config/router-contract.js +0 -54
  212. package/router/dist/config/schema.d.ts +0 -27
  213. package/router/dist/config/schema.js +0 -648
  214. package/router/dist/config/types.d.ts +0 -573
  215. package/router/dist/config/types.js +0 -41
  216. package/router/dist/evidence/bounded-evidence.d.ts +0 -40
  217. package/router/dist/evidence/bounded-evidence.js +0 -323
  218. package/router/dist/evidence/evidence-range-selector.d.ts +0 -24
  219. package/router/dist/evidence/evidence-range-selector.js +0 -232
  220. package/router/dist/evidence/evidence-search.d.ts +0 -27
  221. package/router/dist/evidence/evidence-search.js +0 -490
  222. package/router/dist/evidence/evidence.d.ts +0 -38
  223. package/router/dist/evidence/evidence.js +0 -200
  224. package/router/dist/evidence/failure-contracts.d.ts +0 -37
  225. package/router/dist/evidence/failure-contracts.js +0 -166
  226. package/router/dist/evidence/line-ranges.d.ts +0 -24
  227. package/router/dist/evidence/line-ranges.js +0 -22
  228. package/router/dist/experiments/local-index.d.ts +0 -64
  229. package/router/dist/experiments/local-index.js +0 -581
  230. package/router/dist/index.d.ts +0 -30
  231. package/router/dist/index.js +0 -32
  232. package/router/dist/local/local-traversal.d.ts +0 -18
  233. package/router/dist/local/local-traversal.js +0 -334
  234. package/router/dist/processing/engine.d.ts +0 -132
  235. package/router/dist/processing/engine.js +0 -533
  236. package/router/dist/processing/reducers.d.ts +0 -280
  237. package/router/dist/processing/reducers.js +0 -1673
  238. package/router/dist/processing/renderers.d.ts +0 -31
  239. package/router/dist/processing/renderers.js +0 -195
  240. package/router/dist/processing/scripts.d.ts +0 -91
  241. package/router/dist/processing/scripts.js +0 -386
  242. package/router/dist/repo/repo-traversal.d.ts +0 -18
  243. package/router/dist/repo/repo-traversal.js +0 -245
  244. package/router/dist/routing/observed-reducers.d.ts +0 -41
  245. package/router/dist/routing/observed-reducers.js +0 -661
  246. package/router/dist/routing/observed-routing.d.ts +0 -26
  247. package/router/dist/routing/observed-routing.js +0 -378
  248. package/router/dist/routing/parsers.d.ts +0 -16
  249. package/router/dist/routing/parsers.js +0 -521
  250. package/router/dist/routing/run-filters.d.ts +0 -60
  251. package/router/dist/routing/run-filters.js +0 -238
  252. package/router/dist/routing/run-reducers.d.ts +0 -49
  253. package/router/dist/routing/run-reducers.js +0 -122
  254. package/router/dist/sandbox/adapter-roots.d.ts +0 -46
  255. package/router/dist/sandbox/adapter-roots.js +0 -66
  256. package/router/dist/sandbox/eryx-python-adapter.d.ts +0 -13
  257. package/router/dist/sandbox/eryx-python-adapter.js +0 -868
  258. package/router/dist/sandbox/jq-wasm-adapter.d.ts +0 -9
  259. package/router/dist/sandbox/jq-wasm-adapter.js +0 -429
  260. package/router/dist/sandbox/quickjs-wasi-adapter.d.ts +0 -13
  261. package/router/dist/sandbox/quickjs-wasi-adapter.js +0 -384
  262. package/router/dist/sandbox/script-sandbox.d.ts +0 -134
  263. package/router/dist/sandbox/script-sandbox.js +0 -337
  264. package/router/dist/setup/script-transform-adapters.d.ts +0 -32
  265. package/router/dist/setup/script-transform-adapters.js +0 -278
  266. package/router/dist/tools/batch.d.ts +0 -33
  267. package/router/dist/tools/batch.js +0 -586
  268. package/router/dist/tools/run.d.ts +0 -62
  269. package/router/dist/tools/run.js +0 -1304
  270. package/router/dist/tools/search.d.ts +0 -66
  271. package/router/dist/tools/search.js +0 -1364
  272. package/router/dist/transform/engine.d.ts +0 -168
  273. package/router/dist/transform/engine.js +0 -2072
  274. package/router/dist/vault/vault-index.d.ts +0 -125
  275. package/router/dist/vault/vault-index.js +0 -416
  276. package/router/dist/vault/vault.d.ts +0 -138
  277. package/router/dist/vault/vault.js +0 -630
  278. package/runtime/interaction-contract.md +0 -16
  279. package/skills/discuss/references/checkpoints.md +0 -66
  280. package/skills/execute-work/references/execution-loop.md +0 -77
  281. package/skills/track-work/references/working-record-schema.md +0 -378
  282. package/skills/workflow/references/workflow-loop.md +0 -92
  283. /package/skills/handoff/references/{templates.md → handoff-templates.md} +0 -0
  284. /package/skills/review-artifact/references/{reviewer-prompt.md → independent-artifact-reviewer-contract.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
- }