afyx-engineering-kit 0.1.0-alpha.7 → 0.1.0-alpha.8

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 (55) hide show
  1. package/.afyx-source-revision +1 -1
  2. package/afyx-context/src/budget.js +39 -153
  3. package/afyx-context/src/documentation.js +116 -0
  4. package/afyx-context/src/index.js +2 -0
  5. package/afyx-context/src/memory.js +122 -229
  6. package/afyx-context/src/usage.js +91 -0
  7. package/afyx-forge/src/cli.js +14 -1
  8. package/afyx-forge/src/index.js +3 -0
  9. package/afyx-forge/src/workflow-refiner.js +48 -15
  10. package/afyx-forge/src/workflow.js +226 -0
  11. package/afyx-graph/engine/release/RELEASE-MANIFEST.json +16 -6
  12. package/afyx-graph/engine/release/SHA256SUMS +4 -2
  13. package/afyx-graph/engine/release/afyx-graph-darwin-arm64.tar.gz +0 -0
  14. package/afyx-graph/engine/release/afyx-graph-darwin-x64.tar.gz +0 -0
  15. package/afyx-graph/engine/release/afyx-graph-linux-x64.tar.gz +0 -0
  16. package/afyx-graph/engine/release/afyx-graph-win32-x64.zip +0 -0
  17. package/bin/afyx-engineering-kit.mjs +14 -6
  18. package/install.ps1 +52 -6
  19. package/install.sh +11 -7
  20. package/package.json +3 -1
  21. package/scripts/afyx-capability-orchestrator.mjs +159 -41
  22. package/scripts/afyx-graph-artifact.mjs +1 -1
  23. package/scripts/afyx-graph-targets.mjs +8 -0
  24. package/scripts/afyx-host-adapters.mjs +52 -0
  25. package/scripts/afyx-host-bridge-lifecycle.mjs +4 -0
  26. package/scripts/afyx-host-bridge.mjs +25 -0
  27. package/scripts/afyx-install-backend.mjs +34 -13
  28. package/scripts/afyx-install-contract.mjs +5 -2
  29. package/scripts/afyx-install-progress.mjs +88 -0
  30. package/scripts/afyx-installer-environment.mjs +150 -0
  31. package/scripts/afyx-local-link-ownership.mjs +16 -0
  32. package/scripts/afyx-midnight-circuit.mjs +322 -79
  33. package/scripts/afyx-modular-integration.mjs +3 -0
  34. package/scripts/afyx-modular-runtime.mjs +3 -0
  35. package/scripts/afyx-native-execution.mjs +168 -0
  36. package/scripts/afyx-native-github.mjs +155 -0
  37. package/scripts/afyx-npm-installer.mjs +56 -28
  38. package/scripts/afyx-provider-inventory.mjs +6 -3
  39. package/scripts/afyx-security-auditor.mjs +61 -64
  40. package/scripts/afyx-skill-catalog.mjs +83 -0
  41. package/scripts/afyx-skill-engineering.mjs +2 -0
  42. package/scripts/afyx-universal-runtime.mjs +74 -12
  43. package/scripts/install-afyx-graph.sh +4 -4
  44. package/scripts/lib/AfyxInstallerProgress.psm1 +11 -0
  45. package/scripts/lib/AfyxSkillLifecycle.psm1 +42 -6
  46. package/scripts/lib/afyx-installer-progress.sh +30 -0
  47. package/scripts/link-global-dev.ps1 +10 -3
  48. package/scripts/link-global-dev.sh +10 -8
  49. package/scripts/prepare-g6-package.mjs +13 -28
  50. package/scripts/resolve-git-release-artifacts.mjs +5 -4
  51. package/scripts/stage-npm-release.mjs +3 -1
  52. package/scripts/validate-release-zip-graph.mjs +2 -2
  53. package/uninstall.ps1 +2 -0
  54. package/verify.ps1 +7 -1
  55. package/verify.sh +5 -3
@@ -1 +1 @@
1
- 251f73a8f91cd7b9194a2bd730966c1d92f86da0
1
+ 57cfcf2c7b7a48d1c5bbba03fe97af98b71ac5bd
@@ -1,166 +1,52 @@
1
- /**
2
- * AFYX Context Engine - Deterministic Context Budgeting & Compression
3
- *
4
- * Provides deterministic token and byte estimation, redundancy detection,
5
- * and adaptive evidence compression without external model telemetry.
6
- * Ensures critical source references (file paths, symbol names, error spans)
7
- * remain recoverable when trimming oversized tool outputs.
8
- */
9
-
10
- export const DEFAULT_CONTEXT_BUDGET = Object.freeze({
11
- maxTokens: 4000,
12
- maxBytes: 16000,
13
- maxLines: 250,
14
- });
15
-
16
- /**
17
- * Deterministic token counter heuristic (provider-agnostic: ~4 chars per token).
18
- */
1
+ /** AFYX bounded context selection. Token counts are estimates, not provider telemetry. */
2
+ export const DEFAULT_CONTEXT_BUDGET = Object.freeze({ maxTokens: 4000, maxBytes: 16000, maxLines: 250 });
19
3
  export function estimateTokens(text) {
20
4
  if (!text) return 0;
21
- const str = typeof text === 'string' ? text : JSON.stringify(text);
22
- // Accurate code token heuristic: words + punctuation chunks
23
- const wordTokens = str.split(/\s+/).filter(Boolean).length;
24
- const charTokens = Math.ceil(str.length / 4);
25
- return Math.max(wordTokens, charTokens);
5
+ const value = typeof text === 'string' ? text : JSON.stringify(text);
6
+ return Math.max(value.split(/\s+/).filter(Boolean).length, Math.ceil(value.length / 4));
26
7
  }
27
-
28
- /**
29
- * Calculates byte size in UTF-8.
30
- */
31
8
  export function estimateBytes(text) {
32
9
  if (!text) return 0;
33
- const str = typeof text === 'string' ? text : JSON.stringify(text);
34
- return Buffer.byteLength(str, 'utf8');
10
+ return Buffer.byteLength(typeof text === 'string' ? text : JSON.stringify(text), 'utf8');
35
11
  }
36
-
37
- /**
38
- * Detects repetitive / redundant lines across text blocks.
39
- */
40
12
  export function detectRedundancy(lines, { minRepeatCount = 3 } = {}) {
41
- const lineCounts = new Map();
42
- for (const line of lines) {
43
- const trimmed = line.trim();
44
- if (trimmed.length > 10) {
45
- lineCounts.set(trimmed, (lineCounts.get(trimmed) || 0) + 1);
46
- }
47
- }
48
- const redundant = new Set();
49
- for (const [line, count] of lineCounts.entries()) {
50
- if (count >= minRepeatCount) {
51
- redundant.add(line);
52
- }
53
- }
54
- return redundant;
13
+ const counts = new Map();
14
+ for (const line of lines) { const value = line.trim(); if (value.length > 10) counts.set(value, (counts.get(value) || 0) + 1); }
15
+ return new Set([...counts].filter(([, count]) => count >= minRepeatCount).map(([line]) => line));
55
16
  }
56
-
57
- /**
58
- * Compresses an array of text sections or source files within a bounded budget,
59
- * preserving critical references and recording exact truncation metadata.
60
- *
61
- * @param {Array<{ id: string, text: string, priority?: number, references?: string[] }>} items
62
- * @param {Object} [budget]
63
- * @param {number} [budget.maxTokens]
64
- * @param {number} [budget.maxBytes]
65
- * @param {number} [budget.maxLines]
66
- * @returns {Object} Compressed result with retained items and truncation receipts
67
- */
68
17
  export function compressContextItems(items, budget = {}) {
69
- const maxBytes = budget.maxBytes || DEFAULT_CONTEXT_BUDGET.maxBytes;
70
- const maxTokens = budget.maxTokens || DEFAULT_CONTEXT_BUDGET.maxTokens;
71
- const maxLines = budget.maxLines || DEFAULT_CONTEXT_BUDGET.maxLines;
72
-
73
- // Sort by priority descending (higher priority admitted first)
74
- const sorted = [...items].sort((a, b) => (b.priority || 0) - (a.priority || 0));
75
-
76
- let currentBytes = 0;
77
- let currentTokens = 0;
78
- let currentLines = 0;
79
-
80
- const admitted = [];
81
- const truncated = [];
82
- const omitted = [];
18
+ const limits = {};
19
+ for (const [key, fallback] of Object.entries(DEFAULT_CONTEXT_BUDGET)) {
20
+ limits[key] = budget[key] ?? fallback;
21
+ if (!Number.isSafeInteger(limits[key]) || limits[key] < 1) throw new Error(`Invalid context budget: ${key}`);
22
+ }
23
+ if (!Array.isArray(items) || items.some((item) => !item || typeof item.id !== 'string' || !item.id || typeof item.text !== 'string')) throw new Error('Context items require a non-empty id and text string');
24
+ const admitted = [], truncated = [], omitted = [];
83
25
  const preservedReferences = new Set();
84
-
85
- for (const item of sorted) {
86
- const itemBytes = estimateBytes(item.text);
87
- const itemTokens = estimateTokens(item.text);
88
- const itemLinesList = item.text.split('\n');
89
- const itemLinesCount = itemLinesList.length;
90
-
91
- // Register references
92
- if (Array.isArray(item.references)) {
93
- for (const ref of item.references) preservedReferences.add(ref);
94
- }
95
-
96
- // Check if item fits fully
97
- if (
98
- currentBytes + itemBytes <= maxBytes &&
99
- currentTokens + itemTokens <= maxTokens &&
100
- currentLines + itemLinesCount <= maxLines
101
- ) {
102
- admitted.push({
103
- id: item.id,
104
- text: item.text,
105
- status: 'FULL',
106
- originalBytes: itemBytes,
107
- originalTokens: itemTokens,
108
- });
109
- currentBytes += itemBytes;
110
- currentTokens += itemTokens;
111
- currentLines += itemLinesCount;
112
- continue;
113
- }
114
-
115
- // Partial budget remaining: try bounded slice
116
- const remainingBytes = Math.max(0, maxBytes - currentBytes);
117
- const remainingLines = Math.max(0, maxLines - currentLines);
118
-
119
- if (remainingBytes > 300 && remainingLines > 5) {
120
- const halfLines = Math.floor(remainingLines / 2);
121
- const head = itemLinesList.slice(0, halfLines);
122
- const tail = itemLinesList.slice(-halfLines);
123
- const omittedLineCount = itemLinesCount - head.length - tail.length;
124
-
125
- const marker = `\n<!-- AFYX-TRUNCATED: [id=${item.id}] original=${itemLinesCount} lines, omitted=${omittedLineCount} lines; full evidence recoverable on disk -->\n`;
126
- const compressedText = [...head, marker, ...tail].join('\n');
127
-
128
- admitted.push({
129
- id: item.id,
130
- text: compressedText,
131
- status: 'PARTIAL',
132
- originalBytes: itemBytes,
133
- compressedBytes: estimateBytes(compressedText),
134
- omittedLines: omittedLineCount,
135
- });
136
- truncated.push(item.id);
137
- currentBytes += estimateBytes(compressedText);
138
- currentLines += remainingLines;
139
- break;
140
- } else {
141
- omitted.push({
142
- id: item.id,
143
- originalBytes: itemBytes,
144
- references: item.references || [],
145
- });
26
+ let rendered = '';
27
+ const measure = (text) => ({ bytes: estimateBytes(text), tokens: estimateTokens(text), lines: text ? text.split('\n').length : 0 });
28
+ const fits = (text) => { const size = measure((admitted.length ? `${rendered}\n\n` : '') + text); return size.bytes <= limits.maxBytes && size.tokens <= limits.maxTokens && size.lines <= limits.maxLines; };
29
+ for (const item of [...items].sort((a, b) => (b.priority || 0) - (a.priority || 0))) {
30
+ let text = item.text, status = 'FULL';
31
+ if (!fits(text)) {
32
+ const chars = Array.from(text);
33
+ let low = 0, high = chars.length - 1, selected = null;
34
+ // Slice code points so UTF-8 never contains a split surrogate.
35
+ while (low <= high) {
36
+ const keep = Math.floor((low + high) / 2), head = Math.ceil(keep / 2), tail = Math.floor(keep / 2);
37
+ const candidate = chars.slice(0, head).join('') + `\n<!-- AFYX-TRUNCATED: ${chars.length - keep} characters omitted -->\n` + (tail ? chars.slice(-tail).join('') : '');
38
+ if (fits(candidate)) { selected = candidate; low = keep + 1; } else high = keep - 1;
39
+ }
40
+ if (selected === null) { omitted.push({ id: item.id, originalBytes: estimateBytes(item.text), references: item.references || [] }); continue; }
41
+ text = selected; status = 'PARTIAL'; truncated.push(item.id);
146
42
  }
43
+ const references = Array.isArray(item.references) ? [...new Set(item.references.filter((ref) => typeof ref === 'string'))] : [];
44
+ admitted.push({ id: item.id, text, status, references, originalBytes: estimateBytes(item.text), originalTokens: estimateTokens(item.text), ...(status === 'PARTIAL' ? { compressedBytes: estimateBytes(text) } : {}) });
45
+ for (const reference of references) preservedReferences.add(reference);
46
+ rendered += (admitted.length > 1 ? '\n\n' : '') + text;
147
47
  }
148
-
149
- return {
150
- contract: 'afyx-context-budget-v1',
151
- budget: { maxBytes, maxTokens, maxLines },
152
- metrics: {
153
- totalOriginalItems: items.length,
154
- admittedItemsCount: admitted.length,
155
- truncatedItemsCount: truncated.length,
156
- omittedItemsCount: omitted.length,
157
- consumedBytes: currentBytes,
158
- consumedTokens: currentTokens,
159
- consumedLines: currentLines,
160
- },
161
- admitted,
162
- truncated,
163
- omitted,
164
- preservedReferences: Array.from(preservedReferences),
165
- };
48
+ const size = measure(rendered);
49
+ return { contract: 'afyx-context-budget-v1', budget: limits,
50
+ metrics: { totalOriginalItems: items.length, admittedItemsCount: admitted.length, truncatedItemsCount: truncated.length, omittedItemsCount: omitted.length, consumedBytes: size.bytes, consumedTokens: size.tokens, consumedLines: size.lines },
51
+ admitted, truncated, omitted, preservedReferences: [...preservedReferences] };
166
52
  }
@@ -0,0 +1,116 @@
1
+ /** AFYX local documentation catalog. Sources are supplied by trusted host configuration. */
2
+ import { createHash } from 'node:crypto';
3
+ import * as fs from 'node:fs';
4
+ import { isAbsolute, relative, resolve, sep } from 'node:path';
5
+ import { compressContextItems } from './budget.js';
6
+
7
+ export const DOCUMENTATION_CONTRACT = 'afyx-documentation/v1';
8
+ const hash = (value) => createHash('sha256').update(value).digest('hex');
9
+ const words = (text) => String(text).toLowerCase().match(/[\p{L}\p{N}_]+/gu) || [];
10
+ function fail(code) { const error = new Error(code); error.code = code; throw error; }
11
+ function contained(root, file) { const rel = relative(root, file); return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel); }
12
+
13
+ export function createDocumentationCatalog({ projectRoot, sources = [], enabled = true, maxCacheEntries = 32, maxSourceBytes = 1_048_576, maxSearchSources = 32, maxSearchBytes = 4_194_304 } = {}) {
14
+ if (!Array.isArray(sources) || sources.length > 1000 || !Number.isSafeInteger(maxCacheEntries) || maxCacheEntries < 1 || maxCacheEntries > 1000
15
+ || !Number.isSafeInteger(maxSourceBytes) || maxSourceBytes < 1 || maxSourceBytes > 16_777_216
16
+ || !Number.isSafeInteger(maxSearchSources) || maxSearchSources < 1 || maxSearchSources > 1000
17
+ || !Number.isSafeInteger(maxSearchBytes) || maxSearchBytes < 1 || maxSearchBytes > 16_777_216) fail('DOCUMENTATION_INVALID_CONFIG');
18
+ const root = resolve(projectRoot || process.cwd());
19
+ const registry = new Map();
20
+ const cache = new Map();
21
+ let sourceReads = 0, cacheHits = 0;
22
+ for (const source of sources) {
23
+ if (!source || typeof source.id !== 'string' || !source.id || source.id.length > 256 || typeof source.path !== 'string' || !source.path
24
+ || source.path.includes('\0') || registry.has(source.id)) fail('DOCUMENTATION_INVALID_SOURCE');
25
+ const file = resolve(root, source.path);
26
+ if (!contained(root, file) || file === root) fail('DOCUMENTATION_UNSAFE_PATH');
27
+ registry.set(source.id, Object.freeze({ id: source.id, path: relative(root, file), domain: String(source.domain || ''), library: String(source.library || ''), version: String(source.version || '') }));
28
+ }
29
+
30
+ function read(source, { remainingBytes = Infinity, onInspect = () => {} } = {}) {
31
+ if (fs.lstatSync(root).isSymbolicLink()) fail('DOCUMENTATION_UNSAFE_PATH');
32
+ const canonicalRoot = fs.realpathSync(root);
33
+ let file = root;
34
+ for (const part of source.path.split(sep)) {
35
+ file = resolve(file, part);
36
+ if (fs.lstatSync(file).isSymbolicLink()) fail('DOCUMENTATION_UNSAFE_PATH');
37
+ }
38
+ if (!contained(canonicalRoot, fs.realpathSync(file))) fail('DOCUMENTATION_UNSAFE_PATH');
39
+ const stat = fs.statSync(file, { bigint: true });
40
+ if (!stat.isFile() || stat.nlink > 1n || stat.size > BigInt(maxSourceBytes)) fail('DOCUMENTATION_SOURCE_LIMIT');
41
+ if (Number.isFinite(remainingBytes) && stat.size > BigInt(remainingBytes)) fail('DOCUMENTATION_SEARCH_LIMIT');
42
+ onInspect(Number(stat.size));
43
+ const fingerprint = `${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}:${stat.ino}`;
44
+ const known = cache.get(source.id);
45
+ if (known?.fingerprint === fingerprint) { cacheHits++; cache.delete(source.id); cache.set(source.id, known); return known; }
46
+ const handle = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
47
+ let bytes;
48
+ try {
49
+ const opened = fs.fstatSync(handle, { bigint: true });
50
+ if (`${opened.size}:${opened.mtimeNs}:${opened.ctimeNs}:${opened.ino}` !== fingerprint) fail('DOCUMENTATION_SOURCE_CHANGED');
51
+ // Read at most the admitted size plus one byte; concurrent growth cannot allocate unbounded input.
52
+ const buffer = Buffer.alloc(Number(stat.size) + 1);
53
+ let length = 0;
54
+ while (length < buffer.length) { const count = fs.readSync(handle, buffer, length, buffer.length - length, null); if (!count) break; length += count; }
55
+ if (length > Number(stat.size)) fail('DOCUMENTATION_SOURCE_CHANGED');
56
+ bytes = buffer.subarray(0, length);
57
+ } finally { fs.closeSync(handle); }
58
+ sourceReads++;
59
+ if (bytes.length > maxSourceBytes || bytes.includes(0)) fail('DOCUMENTATION_SOURCE_LIMIT');
60
+ let text;
61
+ try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { fail('DOCUMENTATION_INVALID_ENCODING'); }
62
+ const after = fs.statSync(file, { bigint: true });
63
+ if (`${after.size}:${after.mtimeNs}:${after.ctimeNs}:${after.ino}` !== fingerprint) fail('DOCUMENTATION_SOURCE_CHANGED');
64
+ const record = { ...source, title: text.match(/^#\s+(.+)$/m)?.[1] || source.id, text, sha256: hash(bytes), fingerprint };
65
+ cache.set(source.id, record);
66
+ while (cache.size > maxCacheEntries) cache.delete(cache.keys().next().value);
67
+ return record;
68
+ }
69
+
70
+ function search({ query = '', domain, library, version, budget = {}, limit = 5 } = {}) {
71
+ if (!enabled) return { contract: DOCUMENTATION_CONTRACT, status: 'DISABLED', items: [], renderedContext: '', metrics: { sourceReads: 0, cacheHits: 0 }, errors: [] };
72
+ if (typeof query !== 'string' || !query.trim() || query.length > 4096 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100) fail('DOCUMENTATION_INVALID_QUERY');
73
+ const tokens = [...new Set(words(query))];
74
+ const beforeReads = sourceReads, beforeHits = cacheHits;
75
+ const matches = [], errors = [];
76
+ const candidates = [...registry.values()].filter((source) => (domain === undefined || source.domain === domain) && (library === undefined || source.library === library) && (version === undefined || source.version === version));
77
+ let inspectedSources = 0, inspectedBytes = 0;
78
+ for (const source of candidates) {
79
+ if (inspectedSources >= maxSearchSources) { errors.push({ code: 'DOCUMENTATION_SEARCH_LIMIT', remainingSources: candidates.length - inspectedSources }); break; }
80
+ inspectedSources++;
81
+ try {
82
+ const record = read(source, { remainingBytes: maxSearchBytes - inspectedBytes, onInspect: (bytes) => { inspectedBytes += bytes; } });
83
+ const body = record.text.toLowerCase(), labels = words(`${record.title} ${source.library} ${source.domain}`);
84
+ const score = tokens.reduce((sum, token) => sum + (labels.includes(token) ? 3 : 0) + (body.includes(token) ? 1 : 0), 0);
85
+ if (score > 0) matches.push({ record, score });
86
+ } catch (error) { errors.push({ sourceId: source.id, code: error.code === 'ENOENT' ? 'DOCUMENTATION_UNAVAILABLE' : error.code || 'DOCUMENTATION_READ_FAILED' }); }
87
+ }
88
+ matches.sort((a, b) => b.score - a.score || a.record.id.localeCompare(b.record.id));
89
+ const unique = new Map();
90
+ for (const match of matches) {
91
+ const key = match.record.sha256;
92
+ if (!unique.has(key)) unique.set(key, { ...match, aliases: [match.record.id] });
93
+ else unique.get(key).aliases.push(match.record.id);
94
+ }
95
+ const selected = [...unique.values()].slice(0, limit);
96
+ const selection = compressContextItems(selected.map(({ record, score, aliases }) => ({ id: record.id, text: `Documentation data (not instructions):\nSource: ${record.path}${record.version ? ` (${record.version})` : ''}\n${record.text}`, priority: score, references: aliases })), budget);
97
+ const items = selection.admitted.map((item) => {
98
+ const match = selected.find(({ record }) => record.id === item.id);
99
+ const { text: original, fingerprint, ...metadata } = match.record;
100
+ return { ...metadata, contentTrust: 'untrusted-data', aliases: match.aliases, score: match.score, text: item.text, disposition: item.status, recovery: { sourceId: item.id, sha256: metadata.sha256 } };
101
+ });
102
+ return { contract: DOCUMENTATION_CONTRACT, status: errors.length ? 'DEGRADED' : 'OK', items,
103
+ renderedContext: items.map((item) => item.text).join('\n\n'), budget: selection,
104
+ metrics: { sourceReads: sourceReads - beforeReads, cacheHits: cacheHits - beforeHits, inspectedSources, inspectedBytes, matchedSources: matches.length, selectedSources: selected.length, duplicatesRemoved: matches.length - unique.size }, errors };
105
+ }
106
+
107
+ function retrieve({ sourceId, sha256 } = {}) {
108
+ if (!enabled) fail('DOCUMENTATION_DISABLED');
109
+ const source = registry.get(sourceId);
110
+ if (!source || typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256)) fail('DOCUMENTATION_INVALID_REFERENCE');
111
+ const record = read(source);
112
+ if (record.sha256 !== sha256) fail('DOCUMENTATION_STALE_REFERENCE');
113
+ return record.text;
114
+ }
115
+ return Object.freeze({ list: () => enabled ? [...registry.values()].map((source) => ({ ...source })) : [], search, retrieve });
116
+ }
@@ -23,3 +23,5 @@ export {
23
23
  compressContextItems,
24
24
  detectRedundancy,
25
25
  } from './budget.js';
26
+ export { DOCUMENTATION_CONTRACT, createDocumentationCatalog } from './documentation.js';
27
+ export { USAGE_CONTRACT, normalizeUsageEvent, createUsageAnalytics } from './usage.js';