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