afyx-engineering-kit 0.0.0-stage → 0.1.0-alpha.3

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 (208) hide show
  1. package/.afyx-source-revision +1 -0
  2. package/LICENSE +21 -0
  3. package/README.md +377 -2
  4. package/SECURITY.md +74 -0
  5. package/afyx-context/LICENSE +21 -0
  6. package/afyx-context/README.md +155 -0
  7. package/afyx-context/afyx-context.json +30 -0
  8. package/afyx-context/contracts/integration-v1.schema.json +34 -0
  9. package/afyx-context/package-lock.json +53 -0
  10. package/afyx-context/package.json +34 -0
  11. package/afyx-context/scripts/benchmark.mjs +39 -0
  12. package/afyx-context/scripts/build.mjs +15 -0
  13. package/afyx-context/scripts/comparative-benchmark.mjs +342 -0
  14. package/afyx-context/scripts/comparative-worker.mjs +74 -0
  15. package/afyx-context/scripts/graph-integration-e2e.mjs +188 -0
  16. package/afyx-context/scripts/integrated-dogfood.mjs +309 -0
  17. package/afyx-context/src/budget.js +166 -0
  18. package/afyx-context/src/cli.js +110 -0
  19. package/afyx-context/src/coordination.js +343 -0
  20. package/afyx-context/src/engine.js +198 -0
  21. package/afyx-context/src/errors.js +14 -0
  22. package/afyx-context/src/graph-integration-worker.js +70 -0
  23. package/afyx-context/src/graph-integration.js +373 -0
  24. package/afyx-context/src/graph-mcp-bridge.js +103 -0
  25. package/afyx-context/src/index.js +25 -0
  26. package/afyx-context/src/integrations.js +87 -0
  27. package/afyx-context/src/memory.js +255 -0
  28. package/afyx-context/src/storage.js +364 -0
  29. package/afyx-context/test-fixtures/coordination-worker.mjs +52 -0
  30. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__init__.py +1 -0
  31. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__manifest__.py +4 -0
  32. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/__init__.py +1 -0
  33. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/sale_order.py +5 -0
  34. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__init__.py +1 -0
  35. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__manifest__.py +10 -0
  36. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/__init__.py +2 -0
  37. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order.py +20 -0
  38. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order_audit.py +11 -0
  39. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/security/ir.model.access.csv +2 -0
  40. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/views/sale_order_views.xml +14 -0
  41. package/afyx-forge/LICENSE +55 -0
  42. package/afyx-forge/README.md +126 -0
  43. package/afyx-forge/afyx-forge.json +28 -0
  44. package/afyx-forge/bin/afyx-forge +4 -0
  45. package/afyx-forge/bin/afyx-forge.cmd +3 -0
  46. package/afyx-forge/bin/afyx-forge.js +16 -0
  47. package/afyx-forge/contracts/forge-plan-v1.schema.json +172 -0
  48. package/afyx-forge/package.json +26 -0
  49. package/afyx-forge/src/classifier.js +190 -0
  50. package/afyx-forge/src/cli.js +111 -0
  51. package/afyx-forge/src/doctor.js +105 -0
  52. package/afyx-forge/src/guidance.js +120 -0
  53. package/afyx-forge/src/index.js +273 -0
  54. package/afyx-forge/src/planning.js +107 -0
  55. package/afyx-forge/src/policy.js +109 -0
  56. package/afyx-forge/src/workflow-refiner.js +151 -0
  57. package/afyx-graph/afyx-graph.json +20 -0
  58. package/afyx-graph/engine/LICENSE +21 -0
  59. package/afyx-graph/engine/README.md +104 -0
  60. package/afyx-graph/engine/release/RELEASE-MANIFEST.json +21 -0
  61. package/afyx-graph/engine/release/SHA256SUMS +2 -0
  62. package/afyx-graph/engine/release/afyx-graph-linux-x64.tar.gz +0 -0
  63. package/afyx-graph/engine/release/afyx-graph-win32-x64.zip +0 -0
  64. package/afyx-graph/engine/scripts/distribution-contract.mjs +212 -0
  65. package/afyx-graph/engine/scripts/distribution-product.json +33 -0
  66. package/bin/afyx-engineering-kit.mjs +61 -0
  67. package/install.ps1 +1053 -0
  68. package/install.sh +617 -0
  69. package/package.json +66 -4
  70. package/scripts/afyx-capability-orchestrator.mjs +752 -0
  71. package/scripts/afyx-claude-integration.mjs +547 -0
  72. package/scripts/afyx-context-artifact.mjs +105 -0
  73. package/scripts/afyx-credential-broker.mjs +75 -0
  74. package/scripts/afyx-doctor.ps1 +152 -0
  75. package/scripts/afyx-doctor.sh +146 -0
  76. package/scripts/afyx-forge-artifact.mjs +183 -0
  77. package/scripts/afyx-global-routing-policy.md +12 -0
  78. package/scripts/afyx-global-routing.mjs +168 -0
  79. package/scripts/afyx-graph-artifact.mjs +178 -0
  80. package/scripts/afyx-host-adapters.mjs +543 -0
  81. package/scripts/afyx-host-bridge-lifecycle.mjs +174 -0
  82. package/scripts/afyx-host-bridge.mjs +288 -0
  83. package/scripts/afyx-integration-contracts.mjs +825 -0
  84. package/scripts/afyx-mcp-integration.mjs +528 -0
  85. package/scripts/afyx-modular-integration.mjs +361 -0
  86. package/scripts/afyx-modular-runtime.mjs +451 -0
  87. package/scripts/afyx-native-skill-host.mjs +124 -0
  88. package/scripts/afyx-npm-installer.mjs +486 -0
  89. package/scripts/afyx-project.ps1 +205 -0
  90. package/scripts/afyx-project.sh +207 -0
  91. package/scripts/afyx-provider-backup.mjs +1206 -0
  92. package/scripts/afyx-provider-integration.mjs +724 -0
  93. package/scripts/afyx-provider-inventory.mjs +147 -0
  94. package/scripts/afyx-security-auditor.mjs +224 -0
  95. package/scripts/afyx-skill-engineering.mjs +354 -0
  96. package/scripts/afyx-tool-family-routing.mjs +64 -0
  97. package/scripts/afyx-universal-runtime.mjs +530 -0
  98. package/scripts/alpha_acceptance_preflight.py +240 -0
  99. package/scripts/benchmark-graph-memory.mjs +96 -0
  100. package/scripts/benchmark_capability_orchestrator.mjs +64 -0
  101. package/scripts/build-windows-installer.ps1 +259 -0
  102. package/scripts/build_forge_synthetic_image.py +328 -0
  103. package/scripts/check-reference-staleness.py +71 -0
  104. package/scripts/components.json +254 -0
  105. package/scripts/contracts/afyx-capability-request-v1.schema.json +189 -0
  106. package/scripts/contracts/afyx-capability-result-v1.schema.json +32 -0
  107. package/scripts/dogfood_engineering_comparison.mjs +303 -0
  108. package/scripts/engineering-assurance.json +28 -0
  109. package/scripts/install-afyx-context.ps1 +142 -0
  110. package/scripts/install-afyx-context.sh +126 -0
  111. package/scripts/install-afyx-forge.ps1 +265 -0
  112. package/scripts/install-afyx-forge.sh +273 -0
  113. package/scripts/install-afyx-graph.ps1 +571 -0
  114. package/scripts/install-afyx-graph.sh +438 -0
  115. package/scripts/install-codex-usage-tracker.ps1 +172 -0
  116. package/scripts/lib/AfyxComponents.psm1 +399 -0
  117. package/scripts/lib/AfyxSkillLifecycle.psm1 +289 -0
  118. package/scripts/lib/AfyxTerminal.psm1 +838 -0
  119. package/scripts/lib/afyx-components.sh +256 -0
  120. package/scripts/lib/afyx-skill-lifecycle.sh +271 -0
  121. package/scripts/link-global-dev.ps1 +193 -0
  122. package/scripts/link-global-dev.sh +130 -0
  123. package/scripts/phase8-paired-evidence.mjs +195 -0
  124. package/scripts/phase8-representative-workload.mjs +771 -0
  125. package/scripts/phase8-session-recorder.mjs +157 -0
  126. package/scripts/phase8_event_ledger.py +248 -0
  127. package/scripts/phase8_evidence_discovery.py +189 -0
  128. package/scripts/prepare-g6-package.mjs +349 -0
  129. package/scripts/resolve-git-release-artifacts.mjs +321 -0
  130. package/scripts/stage-npm-release.mjs +94 -0
  131. package/scripts/validate-afyx-graph.py +203 -0
  132. package/scripts/validate-components.py +194 -0
  133. package/scripts/validate-engineering-assurance.py +281 -0
  134. package/scripts/verify-graph-archive.mjs +64 -0
  135. package/skills/afyx-context/SKILL.md +26 -0
  136. package/skills/afyx-engineering-expert/README.md +42 -0
  137. package/skills/afyx-engineering-expert/SKILL.md +70 -0
  138. package/skills/afyx-engineering-expert/assets/result-template.md +15 -0
  139. package/skills/afyx-engineering-expert/references/ai-ml-engineer.md +17 -0
  140. package/skills/afyx-engineering-expert/references/business-analyst.md +17 -0
  141. package/skills/afyx-engineering-expert/references/clean-code-engineer.md +26 -0
  142. package/skills/afyx-engineering-expert/references/code-reviewer.md +24 -0
  143. package/skills/afyx-engineering-expert/references/cybersecurity-devsecops.md +17 -0
  144. package/skills/afyx-engineering-expert/references/data-analyst-bi.md +24 -0
  145. package/skills/afyx-engineering-expert/references/data-engineer.md +24 -0
  146. package/skills/afyx-engineering-expert/references/database-administrator.md +17 -0
  147. package/skills/afyx-engineering-expert/references/debugging-specialist.md +24 -0
  148. package/skills/afyx-engineering-expert/references/embedded-iot-engineer.md +24 -0
  149. package/skills/afyx-engineering-expert/references/erp-technical-specialist.md +17 -0
  150. package/skills/afyx-engineering-expert/references/hardware-diagnostics-auditor.md +24 -0
  151. package/skills/afyx-engineering-expert/references/hardware-electronics-engineer.md +24 -0
  152. package/skills/afyx-engineering-expert/references/integration-engineer.md +24 -0
  153. package/skills/afyx-engineering-expert/references/legacy-modernization-engineer.md +24 -0
  154. package/skills/afyx-engineering-expert/references/llmops-prompt-engineer.md +24 -0
  155. package/skills/afyx-engineering-expert/references/network-engineer.md +24 -0
  156. package/skills/afyx-engineering-expert/references/performance-benchmark-engineer.md +24 -0
  157. package/skills/afyx-engineering-expert/references/platform-engineer.md +24 -0
  158. package/skills/afyx-engineering-expert/references/product-manager.md +17 -0
  159. package/skills/afyx-engineering-expert/references/qa-engineer.md +17 -0
  160. package/skills/afyx-engineering-expert/references/site-reliability-engineer.md +17 -0
  161. package/skills/afyx-engineering-expert/references/software-engineer.md +17 -0
  162. package/skills/afyx-engineering-expert/references/solutions-architect.md +17 -0
  163. package/skills/afyx-engineering-expert/references/specialists-index.md +33 -0
  164. package/skills/afyx-engineering-expert/references/subject-matter-expert.md +17 -0
  165. package/skills/afyx-engineering-expert/references/system-analyst.md +17 -0
  166. package/skills/afyx-engineering-expert/references/technical-project-manager.md +24 -0
  167. package/skills/afyx-engineering-expert/references/technical-writer.md +24 -0
  168. package/skills/afyx-engineering-expert/references/ui-ux-designer.md +17 -0
  169. package/skills/afyx-engineering-expert/workflows/ai-data-erp.md +20 -0
  170. package/skills/afyx-engineering-expert/workflows/debugging.md +10 -0
  171. package/skills/afyx-engineering-expert/workflows/discovery-design.md +11 -0
  172. package/skills/afyx-engineering-expert/workflows/implementation.md +12 -0
  173. package/skills/afyx-engineering-expert/workflows/incident-reliability.md +12 -0
  174. package/skills/afyx-engineering-expert/workflows/review-audit.md +13 -0
  175. package/skills/afyx-forge/SKILL.md +43 -0
  176. package/skills/afyx-forge/references/adaptive-policy.md +19 -0
  177. package/skills/efficient-coding/SKILL.md +33 -0
  178. package/skills/efficient-coding/references/investigation.md +27 -0
  179. package/skills/efficient-coding/references/token-efficiency.md +25 -0
  180. package/skills/efficient-coding/references/tool-routing.md +13 -0
  181. package/skills/odoo-engineering/SKILL.md +33 -0
  182. package/skills/odoo-engineering/references/common.md +9 -0
  183. package/skills/odoo-engineering/references/odoo-10.md +32 -0
  184. package/skills/odoo-engineering/references/odoo-11.md +26 -0
  185. package/skills/odoo-engineering/references/odoo-12.md +31 -0
  186. package/skills/odoo-engineering/references/odoo-13.md +27 -0
  187. package/skills/odoo-engineering/references/odoo-14.md +31 -0
  188. package/skills/odoo-engineering/references/odoo-15.md +34 -0
  189. package/skills/odoo-engineering/references/odoo-16.md +37 -0
  190. package/skills/odoo-engineering/references/odoo-17.md +37 -0
  191. package/skills/odoo-engineering/references/odoo-18.md +48 -0
  192. package/skills/odoo-engineering/references/odoo-19.md +43 -0
  193. package/skills/odoo-engineering/references/odoo-20.md +39 -0
  194. package/skills/odoo-engineering/references/reference-schema.md +16 -0
  195. package/skills/odoo-engineering/references/version-detection.md +13 -0
  196. package/tools/codex-usage/CodexUsage.psm1 +496 -0
  197. package/tools/codex-usage/codex-usage-doctor.ps1 +150 -0
  198. package/tools/codex-usage/codex-usage-pricing.json +25 -0
  199. package/tools/codex-usage/codex-usage-stop.ps1 +167 -0
  200. package/tools/codex-usage/codex-usage-watch.ps1 +250 -0
  201. package/tools/codex-usage/vscode-user-task.json +31 -0
  202. package/tools/windows-setup/SetupBootstrapper.cs +258 -0
  203. package/uninstall.ps1 +189 -0
  204. package/uninstall.sh +167 -0
  205. package/update.ps1 +95 -0
  206. package/update.sh +67 -0
  207. package/verify.ps1 +411 -0
  208. package/verify.sh +265 -0
@@ -0,0 +1,157 @@
1
+ #!/usr/bin/env node
2
+ // Phase 8 local-only typed event recorder. No agent execution, network or customer content capture.
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import crypto from 'node:crypto';
6
+ import readline from 'node:readline';
7
+ import { fileURLToPath } from 'node:url';
8
+
9
+ const SOURCE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
10
+ const SHA = input => crypto.createHash('sha256').update(input).digest('hex');
11
+ const COVERAGE = { toolEvents: false, humanEvents: false, reworkEvents: false, providerUsage: false };
12
+ const QUALITY = { correctness: 'NOT_RUN', tests: 'NOT_RUN', security: 'NOT_RUN', evaluatorReceiptSha256: null };
13
+ const MAX_BYTES = 4 * 1024 * 1024;
14
+ const MAX_EVENTS = 20000;
15
+ const MAX_INPUT_LINE = 4096;
16
+
17
+ class CaptureError extends Error {}
18
+ function requireCapture(condition, reason) {
19
+ if (!condition) throw new CaptureError(reason);
20
+ }
21
+ function identity(candidate) {
22
+ requireCapture(typeof candidate === 'string' && /^[A-Za-z0-9_.-]{1,100}$/.test(candidate), 'invalid run ID');
23
+ return candidate;
24
+ }
25
+ function contained(root, candidate) {
26
+ const relative = path.relative(root, candidate);
27
+ return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
28
+ }
29
+ function privateRoot(candidate, workspace) {
30
+ requireCapture(typeof candidate === 'string' && path.isAbsolute(candidate), 'capture root must be absolute');
31
+ requireCapture(fs.lstatSync(candidate).isDirectory() && !fs.lstatSync(candidate).isSymbolicLink(),
32
+ 'capture root must be a physical directory');
33
+ const canonical = fs.realpathSync.native(candidate);
34
+ requireCapture(!contained(SOURCE_ROOT, canonical), 'capture must remain outside source repository');
35
+ if (workspace) {
36
+ requireCapture(path.isAbsolute(workspace), 'workspace root must be absolute');
37
+ requireCapture(!contained(fs.realpathSync.native(workspace), canonical),
38
+ 'capture must remain outside application repository');
39
+ }
40
+ return canonical;
41
+ }
42
+ function parseOptions(args) {
43
+ const allowed = new Set(['--mode', '--root', '--run-id', '--workspace-root']);
44
+ const out = {};
45
+ requireCapture(args.length % 2 === 0, 'expected paired argument/value options');
46
+ for (let i = 0; i < args.length; i += 2) {
47
+ requireCapture(allowed.has(args[i]) && !Object.hasOwn(out, args[i]), 'invalid or repeated option');
48
+ out[args[i]] = args[i + 1];
49
+ }
50
+ requireCapture(['OFF','ON'].includes(out['--mode']), 'mode must be OFF or ON');
51
+ identity(out['--run-id']);
52
+ requireCapture(typeof out['--root'] === 'string', 'missing root');
53
+ return out;
54
+ }
55
+ function exactKeys(input, keys) {
56
+ requireCapture(input && typeof input === 'object' && !Array.isArray(input), 'event must be an object');
57
+ requireCapture(Object.keys(input).sort().join('|') === keys.slice().sort().join('|'),
58
+ 'unsupported event fields: capture only typed telemetry, no text or secrets');
59
+ }
60
+ function safeEvent(input) {
61
+ requireCapture(input && typeof input.kind === 'string', 'missing event kind');
62
+ if (input.kind === 'tool_call') {
63
+ exactKeys(input, ['kind','actor']);
64
+ requireCapture(input.actor === 'agent', 'tool call must be emitted by agent');
65
+ return {kind:'tool_call',actor:'agent'};
66
+ }
67
+ if (input.kind === 'human_intervention') {
68
+ exactKeys(input, ['kind','actor']);
69
+ requireCapture(input.actor === 'human', 'human intervention requires observed human actor');
70
+ return {kind:'human_intervention',actor:'human'};
71
+ }
72
+ if (input.kind === 'rework') {
73
+ exactKeys(input, ['kind','actor']);
74
+ requireCapture(input.actor === 'agent' || input.actor === 'human', 'invalid rework actor');
75
+ return {kind:'rework',actor:input.actor};
76
+ }
77
+ if (input.kind === 'provider_usage') {
78
+ exactKeys(input, ['kind','source','usageSemantics','inputTokens','cachedInputTokens','outputTokens']);
79
+ requireCapture(input.source === 'provider_report', 'provider counter provenance missing');
80
+ requireCapture(input.usageSemantics === 'per_turn_delta',
81
+ 'provider counters must be independently verified per-turn deltas, not cumulative snapshots');
82
+ for (const k of ['inputTokens','cachedInputTokens','outputTokens']) {
83
+ requireCapture(Number.isSafeInteger(input[k]) && input[k] >= 0, 'invalid provider counter');
84
+ }
85
+ requireCapture(input.cachedInputTokens <= input.inputTokens, 'cached input exceeds total input');
86
+ return {kind:'provider_usage',source:'provider_report',usageSemantics:'per_turn_delta',inputTokens:input.inputTokens,
87
+ cachedInputTokens:input.cachedInputTokens,outputTokens:input.outputTokens};
88
+ }
89
+ throw new CaptureError('unrecognized event kind');
90
+ }
91
+ export async function recordEvents({mode, runId, root, workspaceRoot, input}) {
92
+ requireCapture(['OFF','ON'].includes(mode), 'invalid mode');
93
+ identity(runId);
94
+ requireCapture(input && typeof input[Symbol.asyncIterator] === 'function', 'input must be an async iterator');
95
+ const outputRoot = privateRoot(root, workspaceRoot);
96
+ const filename = mode.toLowerCase() + '.ndjson';
97
+ const dest = path.join(outputRoot, filename);
98
+ let fd = null, complete = false, bytes = 0, events = 0;
99
+ const hash = crypto.createHash('sha256');
100
+ const add = record => {
101
+ const buffer = Buffer.from(JSON.stringify(record) + '\n');
102
+ requireCapture(bytes + buffer.length <= MAX_BYTES, 'trace exceeds 4 MiB');
103
+ fs.writeSync(fd, buffer);
104
+ hash.update(buffer);
105
+ bytes += buffer.length;
106
+ };
107
+ try {
108
+ fd = fs.openSync(dest, 'wx', 0o600);
109
+ add({id:'evt-0',runId,at:new Date().toISOString(),kind:'start'});
110
+ for await (const line of input) {
111
+ requireCapture(typeof line === 'string' && Buffer.byteLength(line,'utf8') <= MAX_INPUT_LINE,
112
+ 'event line exceeds 4096 bytes');
113
+ if (!line.trim()) continue;
114
+ requireCapture(events < MAX_EVENTS - 2, 'too many telemetry events');
115
+ let raw;
116
+ try { raw = JSON.parse(line); } catch { throw new CaptureError('invalid telemetry JSON'); }
117
+ add({id:'evt-' + (events+1),runId,at:new Date().toISOString(),...safeEvent(raw)});
118
+ events++;
119
+ }
120
+ add({id:'evt-' + (events+1),runId,at:new Date().toISOString(),kind:'end'});
121
+ fs.fsyncSync(fd);
122
+ complete = true;
123
+ return {
124
+ contract:'afyx.phase8.local-capture/v1',
125
+ run:{mode,runId,eventsFile:filename,eventsSha256:hash.digest('hex'),
126
+ quality:{...QUALITY},coverage:{...COVERAGE},
127
+ timing:{capture:'REPLAY_OR_UNVERIFIED',liveReceiptSha256:null}},
128
+ capturedEvents:events,
129
+ declaredCoverage:'ALL_UNVERIFIED',
130
+ advisory:'Private descriptor only. Confirm complete event-category coverage and independent evaluator quality evidence before paired intake.',
131
+ };
132
+ } finally {
133
+ if (fd !== null) fs.closeSync(fd);
134
+ if (!complete && fd !== null) {
135
+ try { fs.unlinkSync(dest); } catch { /* do not mask the original error */ }
136
+ }
137
+ }
138
+ }
139
+ async function main() {
140
+ try {
141
+ const opts = parseOptions(process.argv.slice(2));
142
+ const lines = readline.createInterface({input:process.stdin,crlfDelay:Infinity,terminal:false});
143
+ const result = await recordEvents({
144
+ mode:opts['--mode'],runId:opts['--run-id'],root:opts['--root'],
145
+ workspaceRoot:opts['--workspace-root'],input:lines,
146
+ });
147
+ process.stdout.write(JSON.stringify(result,null,2) + '\n');
148
+ } catch (error) {
149
+ // Neither private paths nor trace contents must be reflected to logs.
150
+ const reason = error instanceof CaptureError ? error.message : 'private evidence I/O failed';
151
+ process.stderr.write('Phase 8 capture rejected: ' + reason + '\n');
152
+ process.exitCode = 2;
153
+ }
154
+ }
155
+ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
156
+ await main();
157
+ }
@@ -0,0 +1,248 @@
1
+ #!/usr/bin/env python3
2
+ """Local-only, conservative AFYX Phase 8 event evidence ledger.
3
+
4
+ No model/provider invocation, no network access, no raw prompt/body retention.
5
+ This tool reports observed events; completeness is not inferred from silence.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import hashlib
12
+ import json
13
+ import sys
14
+ from pathlib import Path
15
+ from typing import Any
16
+
17
+ CATEGORIES = {
18
+ "human_intervention": "human",
19
+ "policy_denial": "policy",
20
+ "agent_fallback": "agent",
21
+ "rework": "agent",
22
+ "explicit_retry": "agent",
23
+ }
24
+ TOOL_TYPES = frozenset({
25
+ "command_execution", "mcp_tool_call", "collab_tool_call", "web_search",
26
+ "dynamic_tool_call", "function_call",
27
+ })
28
+ # Codex may emit these as item.completed without an item.started notification.
29
+ # They are NOT tool calls and must not be counted as one.
30
+ TERMINAL_ONLY_TYPES = frozenset({"agent_message", "reasoning", "file_change", "todo_list", "plan", "error"})
31
+ USAGE_FIELDS = ("input_tokens", "cached_input_tokens", "cache_write_input_tokens", "output_tokens", "reasoning_output_tokens")
32
+
33
+
34
+ class EvidenceError(ValueError):
35
+ pass
36
+
37
+
38
+ def read_jsonl(path: Path) -> tuple[list[dict[str, Any]], str]:
39
+ digest = hashlib.sha256()
40
+ events: list[dict[str, Any]] = []
41
+ with path.open("rb") as raw:
42
+ for number, line in enumerate(raw, 1):
43
+ digest.update(line)
44
+ if len(line) > 4 * 1024 * 1024:
45
+ raise EvidenceError(f"{path.name}: oversized line {number}")
46
+ if not line.strip():
47
+ continue
48
+ try:
49
+ record = json.loads(line)
50
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
51
+ raise EvidenceError(f"{path.name}: invalid JSONL line {number}") from exc
52
+ if not isinstance(record, dict):
53
+ raise EvidenceError(f"{path.name}: object required at line {number}")
54
+ events.append(record)
55
+ return events, digest.hexdigest()
56
+
57
+
58
+ def parse_tokens(usage: Any) -> dict[str, Any]:
59
+ if not isinstance(usage, dict):
60
+ return {"availability": "NOT_AVAILABLE", "values": None}
61
+ values: dict[str, int | None] = {}
62
+ for key in USAGE_FIELDS:
63
+ value = usage.get(key)
64
+ if value is not None and (type(value) is not int or value < 0):
65
+ raise EvidenceError(f"invalid token field: {key}")
66
+ values[key] = value
67
+ input_tokens, output_tokens = values["input_tokens"], values["output_tokens"]
68
+ if input_tokens is None or output_tokens is None:
69
+ return {"availability": "INCOMPLETE", "values": values}
70
+ for subset in ("cached_input_tokens", "cache_write_input_tokens"):
71
+ if values[subset] is not None and values[subset] > input_tokens:
72
+ raise EvidenceError(f"{subset} exceeds input_tokens")
73
+ if values["reasoning_output_tokens"] is not None and values["reasoning_output_tokens"] > output_tokens:
74
+ raise EvidenceError("reasoning_output_tokens exceeds output_tokens")
75
+ computed = input_tokens + output_tokens
76
+ reported = usage.get("total_tokens")
77
+ if reported is not None and (type(reported) is not int or reported != computed):
78
+ raise EvidenceError("reported total_tokens does not equal input + output")
79
+ values["total_tokens"] = computed
80
+ return {
81
+ "availability": "AUTHORITATIVE" if reported is not None else "DERIVED_TOTAL",
82
+ "values": values,
83
+ "total_tokens_provenance": "AUTHORITATIVE" if reported is not None else "DERIVED",
84
+ "subsets_not_additive": ["cached_input_tokens", "cache_write_input_tokens", "reasoning_output_tokens"],
85
+ }
86
+
87
+
88
+ def parse_annotations(path: Path | None) -> dict[str, Any]:
89
+ by_category: dict[str, list[dict[str, Any]]] = {category: [] for category in CATEGORIES}
90
+ complete: set[str] = set()
91
+ digest: str | None = None
92
+ if path is not None:
93
+ records, digest = read_jsonl(path)
94
+ for i, entry in enumerate(records, 1):
95
+ if entry.get("type") == "coverage":
96
+ for name in entry.get("complete_categories", []):
97
+ if name not in CATEGORIES:
98
+ raise EvidenceError(f"unknown coverage category at line {i}")
99
+ complete.add(name)
100
+ continue
101
+ category = entry.get("event_type")
102
+ if category not in CATEGORIES:
103
+ raise EvidenceError(f"unsupported annotated event at line {i}")
104
+ if entry.get("actor") != CATEGORIES[category]:
105
+ raise EvidenceError(f"actor mismatch for {category} at line {i}")
106
+ if not entry.get("timestamp") or not entry.get("evidence_ref"):
107
+ raise EvidenceError(f"timestamp and evidence_ref required at line {i}")
108
+ if category == "rework":
109
+ if not all(entry.get(key) for key in ("revision_before", "revision_after", "reason")):
110
+ raise EvidenceError(f"rework lineage missing at line {i}")
111
+ if category == "explicit_retry":
112
+ if not entry.get("attempt_group_id") or type(entry.get("attempt_index")) is not int or entry["attempt_index"] < 2:
113
+ raise EvidenceError(f"retry provenance missing at line {i}")
114
+ by_category[category].append(entry)
115
+ summary = {}
116
+ for category, entries in by_category.items():
117
+ # Never turn absent evidence into zero unless coverage explicitly asserts completeness.
118
+ status = "AUTHORITATIVE" if category in complete else ("PARTIAL" if entries else "NOT_AVAILABLE")
119
+ summary[category] = {"availability": status, "observed_minimum": len(entries),
120
+ "total": len(entries) if category in complete else None}
121
+ return {"sha256": digest, "categories": summary}
122
+
123
+
124
+ def analyze(run_id: str, event_file: Path, annotations: Path | None = None,
125
+ expected_thread_id: str | None = None) -> dict[str, Any]:
126
+ events, digest = read_jsonl(event_file)
127
+ started: dict[str, str] = {}
128
+ finished: set[str] = set()
129
+ failures = 0
130
+ completed: list[dict[str, Any]] = []
131
+ threads: set[str] = set()
132
+ unrecognized_item_types: set[str] = set()
133
+ turns_started = 0
134
+ terminal_seen = False
135
+
136
+ for event in events:
137
+ kind = event.get("type")
138
+ if kind == "thread.started":
139
+ tid = event.get("thread_id")
140
+ if not isinstance(tid, str) or not tid or threads or turns_started:
141
+ raise EvidenceError("duplicate, late or invalid thread.started")
142
+ threads.add(tid)
143
+ elif kind == "turn.started":
144
+ if not threads or turns_started:
145
+ raise EvidenceError("missing thread or duplicate turn.started")
146
+ turns_started += 1
147
+ elif kind == "turn.completed":
148
+ if turns_started != 1 or terminal_seen:
149
+ raise EvidenceError("missing turn.started or duplicate turn.completed")
150
+ terminal_seen = True
151
+ completed.append(event)
152
+ elif kind in ("turn.failed", "error"):
153
+ raise EvidenceError("failed or incomplete Codex event stream")
154
+ elif kind in ("item.started", "item.updated", "item.completed", "item.failed"):
155
+ if turns_started != 1 or terminal_seen:
156
+ raise EvidenceError("item event outside active turn")
157
+ item = event.get("item")
158
+ if not isinstance(item, dict) or not isinstance(item.get("id"), str) or not item["id"]:
159
+ raise EvidenceError("item event missing item.id")
160
+ key = item["id"]
161
+ item_type = item.get("type")
162
+ if not isinstance(item_type, str) or not item_type:
163
+ raise EvidenceError("item type missing")
164
+ if item_type not in TOOL_TYPES and item_type not in TERMINAL_ONLY_TYPES:
165
+ unrecognized_item_types.add(item_type)
166
+ if kind == "item.started":
167
+ if key in started or key in finished:
168
+ raise EvidenceError("duplicate item.started")
169
+ started[key] = item_type
170
+ elif kind == "item.updated":
171
+ # Updates must refer to an existing item, but need not carry
172
+ # a tool-specific payload. An unknown item cannot disappear.
173
+ if key not in started or key in finished or started[key] != item_type:
174
+ raise EvidenceError("orphan or inconsistent item.updated")
175
+ else:
176
+ if key in finished:
177
+ raise EvidenceError("duplicate item completion")
178
+ if key in started:
179
+ if started[key] != item_type:
180
+ raise EvidenceError("item type changed between start and completion")
181
+ elif item_type not in TERMINAL_ONLY_TYPES:
182
+ # A tool completed without a corresponding start means the
183
+ # observed tool-call count and event completeness are unsafe.
184
+ raise EvidenceError("orphan tool completion")
185
+ finished.add(key)
186
+ status = item.get("status")
187
+ if kind == "item.failed" or status in ("failed", "declined"):
188
+ failures += 1
189
+ elif item_type == "command_execution" and type(item.get("exit_code")) is int and item["exit_code"] != 0:
190
+ failures += 1
191
+ elif kind is None:
192
+ raise EvidenceError("event missing type")
193
+ else:
194
+ raise EvidenceError("unsupported top-level event type")
195
+
196
+ if not threads or len(threads) != 1 or (expected_thread_id and expected_thread_id not in threads):
197
+ raise EvidenceError("thread identity missing or does not match")
198
+ if turns_started != 1 or len(completed) != 1:
199
+ raise EvidenceError("expected exactly one complete turn")
200
+ if set(started) - finished:
201
+ raise EvidenceError("unclosed item events")
202
+ tool_ids = [key for key, kind in started.items() if kind in TOOL_TYPES]
203
+ return {
204
+ "schema_version": 1,
205
+ "run_id": run_id,
206
+ "thread_id": next(iter(threads)),
207
+ "source_sha256": digest,
208
+ "tool_events": {
209
+ "observed_started": len(tool_ids),
210
+ "observed_item_failures": failures,
211
+ "availability": "OBSERVED_ONLY" if unrecognized_item_types else "COMPLETE_CAPTURE_SCOPE_ONLY",
212
+ "unknown_item_types": sorted(unrecognized_item_types),
213
+ "retry_count": {"availability": "NOT_AVAILABLE", "value": None},
214
+ },
215
+ "tokens": parse_tokens(completed[0].get("usage")),
216
+ "annotations": parse_annotations(annotations),
217
+ "provider_monetary_cost": {"availability": "NOT_AVAILABLE", "value": None},
218
+ "claims": {"human_zero_if_missing": False, "rework_zero_if_missing": False,
219
+ "provider_cost_is_estimated": False},
220
+ "note": "Counts are capture-scoped, never universal tool or human-intervention claims. No raw messages copied.",
221
+ }
222
+
223
+
224
+ def main(argv: list[str] | None = None) -> int:
225
+ ap = argparse.ArgumentParser(description=__doc__)
226
+ ap.add_argument("--run-id", required=True)
227
+ ap.add_argument("--events", type=Path, required=True, help="Codex exec --json JSONL (existing local file)")
228
+ ap.add_argument("--annotations", type=Path, help="Optional timestamped adjudicated events JSONL")
229
+ ap.add_argument("--expected-thread-id")
230
+ ap.add_argument("--output", type=Path, help="New JSON output path, never overwrite existing files")
231
+ ns = ap.parse_args(argv)
232
+ try:
233
+ record = analyze(ns.run_id, ns.events, ns.annotations, ns.expected_thread_id)
234
+ serialized = json.dumps(record, indent=2, sort_keys=True) + "\n"
235
+ if ns.output:
236
+ # Atomic exclusive create: do not overwrite prior evidence or owner files.
237
+ with ns.output.open("x", encoding="utf-8", newline="\n") as handle:
238
+ handle.write(serialized)
239
+ else:
240
+ sys.stdout.write(serialized)
241
+ except (EvidenceError, OSError) as exc:
242
+ print(f"EVIDENCE_BLOCKED: {exc}", file=sys.stderr)
243
+ return 2
244
+ return 0
245
+
246
+
247
+ if __name__ == "__main__":
248
+ raise SystemExit(main())
@@ -0,0 +1,189 @@
1
+ #!/usr/bin/env python3
2
+ """Find retained Codex session metadata for specific Phase 8 run IDs, offline.
3
+
4
+ Reads only explicitly scoped rollout/JSONL files. Emits no prompts, event bodies,
5
+ absolute paths, credentials, or file contents. Never invokes an agent/provider.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import argparse
10
+ import hashlib
11
+ import json
12
+ import os
13
+ import re
14
+ import stat
15
+ import sys
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ UUID = re.compile(r"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$")
20
+ READ_LIMIT = 64
21
+ LINE_LIMIT = 1024 * 1024
22
+ DEFAULT_MAX_SIZE = 128 * 1024 * 1024
23
+
24
+
25
+ class DiscoveryError(ValueError):
26
+ pass
27
+
28
+
29
+ def link_kind(path: Path) -> str | None:
30
+ """Classify links without following them, including Windows reparse points."""
31
+ if path.is_symlink():
32
+ return "SYMLINK"
33
+ attributes = getattr(path.lstat(), "st_file_attributes", 0)
34
+ reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
35
+ return "REPARSE_POINT" if attributes & reparse_flag else None
36
+
37
+
38
+ def default_root() -> Path:
39
+ home = os.environ.get("CODEX_HOME")
40
+ return Path(home).expanduser() / "sessions" if home else Path.home() / ".codex" / "sessions"
41
+
42
+
43
+ def thread_identity(path: Path) -> str | None:
44
+ """Read bounded event *metadata*, not any prompt/body or arbitrary text match."""
45
+ with path.open("rb") as f:
46
+ for index, line in enumerate(f):
47
+ if index >= READ_LIMIT:
48
+ break
49
+ if len(line) > LINE_LIMIT:
50
+ raise DiscoveryError("oversized metadata line")
51
+ try:
52
+ event = json.loads(line)
53
+ except (ValueError, UnicodeDecodeError) as exc:
54
+ raise DiscoveryError("invalid JSONL metadata") from exc
55
+ if not isinstance(event, dict):
56
+ raise DiscoveryError("invalid JSONL event type")
57
+ typ = event.get("type")
58
+ if typ == "session_meta":
59
+ payload = event.get("payload")
60
+ candidate = payload.get("id") if isinstance(payload, dict) else None
61
+ elif typ == "thread.started":
62
+ candidate = event.get("thread_id")
63
+ else:
64
+ continue
65
+ if isinstance(candidate, str) and UUID.fullmatch(candidate):
66
+ return candidate.lower()
67
+ return None
68
+
69
+
70
+ def file_sha256(path: Path) -> str:
71
+ sha = hashlib.sha256()
72
+ with path.open("rb") as stream:
73
+ for chunk in iter(lambda: stream.read(1024 * 1024), b""):
74
+ sha.update(chunk)
75
+ return sha.hexdigest()
76
+
77
+
78
+ def discover(root: Path, thread_ids: list[str], *, max_files: int = 4000,
79
+ max_file_bytes: int = DEFAULT_MAX_SIZE, include_cli_json: bool = False) -> dict[str, Any]:
80
+ if not thread_ids or any(not UUID.fullmatch(t) for t in thread_ids):
81
+ raise DiscoveryError("valid thread UUIDs are required")
82
+ if max_files < 1 or max_file_bytes < 1:
83
+ raise DiscoveryError("positive scan limits required")
84
+ target_ids = list(dict.fromkeys(t.lower() for t in thread_ids))
85
+ base = root.expanduser().resolve(strict=False)
86
+ result: dict[str, Any] = {"schema_version": 1, "scope": "EXPLICIT_ROOT_ONLY", "default_root_used": False,
87
+ "raw_content_exported": False, "provider_calls": 0,
88
+ "file_scan": {"visited": 0, "unreadable": 0, "oversized": 0,
89
+ "unidentified": 0, "symlinks_skipped": 0,
90
+ "reparse_points_skipped": 0, "cap_reached": False},
91
+ "runs": {t: {"status": "NOT_FOUND_IN_SCOPE", "matches": []} for t in target_ids}}
92
+ if not base.is_dir():
93
+ result["scope_status"] = "ROOT_NOT_FOUND"
94
+ for r in result["runs"].values():
95
+ r["status"] = "INCOMPLETE_SCAN"
96
+ return result
97
+ result["scope_status"] = "SCANNED"
98
+ files: list[Path] = []
99
+ counters = result["file_scan"]
100
+ for directory, names, filenames in os.walk(base, followlinks=False):
101
+ retained_names = []
102
+ for name in sorted(names):
103
+ candidate = Path(directory) / name
104
+ try:
105
+ kind = link_kind(candidate)
106
+ except OSError:
107
+ counters["unreadable"] += 1
108
+ continue
109
+ if kind == "SYMLINK":
110
+ counters["symlinks_skipped"] += 1
111
+ elif kind == "REPARSE_POINT":
112
+ counters["reparse_points_skipped"] += 1
113
+ else:
114
+ retained_names.append(name)
115
+ names[:] = retained_names
116
+ for filename in sorted(filenames):
117
+ if (filename.startswith("rollout-") and filename.endswith(".jsonl")) or (include_cli_json and filename.endswith(".jsonl")):
118
+ files.append(Path(directory) / filename)
119
+ if len(files) > max_files:
120
+ result["file_scan"]["cap_reached"] = True
121
+ break
122
+ if result["file_scan"]["cap_reached"]:
123
+ break
124
+ for path in files[:max_files]:
125
+ counters["visited"] += 1
126
+ try:
127
+ kind = link_kind(path)
128
+ if kind == "SYMLINK":
129
+ counters["symlinks_skipped"] += 1
130
+ continue
131
+ if kind == "REPARSE_POINT":
132
+ counters["reparse_points_skipped"] += 1
133
+ continue
134
+ st = path.stat()
135
+ if st.st_size > max_file_bytes:
136
+ counters["oversized"] += 1
137
+ continue
138
+ session_id = thread_identity(path)
139
+ if session_id not in result["runs"]:
140
+ counters["unidentified"] += 1
141
+ continue
142
+ result["runs"][session_id]["matches"].append({
143
+ "relative_path": path.relative_to(base).as_posix(),
144
+ "size_bytes": st.st_size,
145
+ "sha256": file_sha256(path),
146
+ "identity_source": "STRUCTURED_EVENT_METADATA",
147
+ })
148
+ except (OSError, DiscoveryError):
149
+ counters["unreadable"] += 1
150
+ incomplete = any(result["file_scan"][k] for k in
151
+ ("unreadable", "oversized", "symlinks_skipped",
152
+ "reparse_points_skipped", "cap_reached"))
153
+ for item in result["runs"].values():
154
+ count = len(item["matches"])
155
+ item["status"] = ("MULTIPLE_MATCHES" if count > 1 else
156
+ "INCOMPLETE_SCAN" if incomplete else
157
+ "FOUND" if count == 1 else "NOT_FOUND_IN_SCOPE")
158
+ return result
159
+
160
+
161
+ def main(argv: list[str] | None = None) -> int:
162
+ parser = argparse.ArgumentParser(description=__doc__)
163
+ parser.add_argument("--root", type=Path, default=None, help="Only this explicitly selected root is searched")
164
+ parser.add_argument("--thread-id", action="append", required=True, help="Repeat for each target Codex thread UUID")
165
+ parser.add_argument("--include-cli-json", action="store_true", help="Also inspect *.jsonl files under the root")
166
+ parser.add_argument("--max-files", type=int, default=4000)
167
+ parser.add_argument("--max-file-mib", type=int, default=128)
168
+ parser.add_argument("--output", type=Path, help="Create new report exclusively; never overwrite")
169
+ args = parser.parse_args(argv)
170
+ try:
171
+ root = args.root if args.root is not None else default_root()
172
+ report = discover(root, args.thread_id, max_files=args.max_files,
173
+ max_file_bytes=args.max_file_mib * 1024 * 1024,
174
+ include_cli_json=args.include_cli_json)
175
+ report["default_root_used"] = args.root is None
176
+ encoded = json.dumps(report, indent=2, sort_keys=True) + "\n"
177
+ if args.output:
178
+ with args.output.open("x", encoding="utf-8", newline="\n") as f:
179
+ f.write(encoded)
180
+ else:
181
+ print(encoded, end="")
182
+ except (DiscoveryError, OSError) as exc:
183
+ print("DISCOVERY_BLOCKED: " + str(exc), file=sys.stderr)
184
+ return 2
185
+ return 0
186
+
187
+
188
+ if __name__ == "__main__":
189
+ raise SystemExit(main())