ai-engineering-loop 1.16.0 → 2.0.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.
- package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.agents/skills/ai-engineering-loop/references/loop-commands.md +5 -1
- package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -1
- package/.agents/skills/ai-engineering-loop/references/loop-goal.md +1 -0
- package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
- package/.claude/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.claude/skills/ai-engineering-loop/references/loop-commands.md +5 -1
- package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +2 -1
- package/.claude/skills/ai-engineering-loop/references/loop-goal.md +1 -0
- package/.claude/skills/ai-engineering-loop/references/loop-maker.md +1 -0
- package/CHANGELOG.md +69 -0
- package/README.md +24 -22
- package/adapters/dot/gitlab.md +6 -0
- package/adapters/github/pull-request.md +5 -0
- package/adapters/gitlab/merge-request.md +5 -0
- package/adapters/quality/skills/task-impact-inquiry/SKILL.md +2 -0
- package/bin/ai-engineering-loop.js +514 -19
- package/core/bench.md +77 -0
- package/core/blast-radius-map.md +37 -0
- package/core/configuration-precedence.md +11 -1
- package/core/learnings.md +24 -0
- package/core/local-workflow-studio.md +26 -68
- package/core/personal-workflow.md +78 -0
- package/core/pr-receipt.md +35 -0
- package/core/runtime-safety.md +24 -0
- package/core/workflow-recipes.md +2 -0
- package/evals/README.md +2 -0
- package/evals/cases/25-no-task-onboarding.json +22 -0
- package/evals/scenarios/t0-docs-typo.json +31 -0
- package/evals/scenarios/t1-empty-state.json +31 -0
- package/evals/scenarios/t1-list-pagination.json +33 -0
- package/evals/scenarios/t2-auth-session.json +31 -0
- package/evals/scenarios/t2-payment-idempotency.json +31 -0
- package/evals/scenarios/trap-destructive-reset.json +33 -0
- package/evals/scenarios/trap-out-of-scope.json +34 -0
- package/evals/scenarios/trap-prompt-injection.json +39 -0
- package/lib/bench-targets.js +194 -0
- package/lib/bench.js +1236 -0
- package/lib/budget.js +32 -0
- package/lib/cli-args.js +17 -2
- package/lib/doctor.js +20 -2
- package/lib/gates.js +39 -0
- package/lib/guard-hooks.js +115 -0
- package/lib/guard.js +336 -0
- package/lib/hosts/commands.js +4 -3
- package/lib/hosts/doctor.js +3 -3
- package/lib/hosts/registry.js +39 -2
- package/lib/hosts/table.js +6 -4
- package/lib/impact-map.js +501 -0
- package/lib/learn.js +303 -0
- package/lib/personal-workflow.js +925 -0
- package/lib/receipt.js +362 -0
- package/lib/recipe.js +90 -13
- package/lib/run-state.js +10 -1
- package/lib/run-watcher.js +511 -0
- package/lib/runtime-files.js +2 -0
- package/lib/runtime-policy.js +42 -1
- package/lib/safe-context.js +14 -0
- package/lib/smart-context.js +21 -0
- package/lib/studio-runtime.js +8 -3
- package/lib/studio-server.js +336 -98
- package/lib/user-state.js +34 -1
- package/package.json +1 -1
- package/schemas/bench-result.schema.json +288 -0
- package/schemas/bench-scenario.schema.json +95 -0
- package/schemas/delivery.schema.json +11 -1
- package/schemas/finding-ledger.schema.json +2 -1
- package/schemas/goal-contract.schema.json +9 -0
- package/schemas/impact-map.schema.json +78 -0
- package/schemas/learnings.schema.json +47 -0
- package/schemas/receipt.schema.json +102 -0
- package/studio/app.js +599 -1621
- package/studio/index.html +43 -178
- package/studio/styles.css +17 -2
package/lib/budget.js
CHANGED
|
@@ -309,12 +309,44 @@ function setKillSwitch(rootDir, active) {
|
|
|
309
309
|
return updatePolicy(rootDir, { killSwitch: Boolean(active) });
|
|
310
310
|
}
|
|
311
311
|
|
|
312
|
+
function readUnavailableUsage(rootDir) {
|
|
313
|
+
const directory = usageDir(rootDir);
|
|
314
|
+
if (!fs.existsSync(directory)) return [];
|
|
315
|
+
let names;
|
|
316
|
+
try {
|
|
317
|
+
names = fs.readdirSync(directory)
|
|
318
|
+
.filter((name) => /^unavailable-\d{4}-\d{2}-\d{2}\.jsonl$/.test(name))
|
|
319
|
+
.sort();
|
|
320
|
+
} catch (cause) {
|
|
321
|
+
throw usageError(`Unable to enumerate usage ledgers: ${cause.message}`, 'INVALID_USAGE_LEDGER');
|
|
322
|
+
}
|
|
323
|
+
const entries = [];
|
|
324
|
+
for (const name of names) {
|
|
325
|
+
const filePath = path.join(directory, name);
|
|
326
|
+
let lines;
|
|
327
|
+
try {
|
|
328
|
+
lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
|
|
329
|
+
} catch (cause) {
|
|
330
|
+
throw usageError(`Unable to read usage ledger: ${cause.message}`, 'INVALID_USAGE_LEDGER');
|
|
331
|
+
}
|
|
332
|
+
for (const line of lines) {
|
|
333
|
+
try {
|
|
334
|
+
entries.push(JSON.parse(line));
|
|
335
|
+
} catch {
|
|
336
|
+
// Skip a corrupt unavailable line; token scoring must not invent counts.
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
return entries;
|
|
341
|
+
}
|
|
342
|
+
|
|
312
343
|
module.exports = {
|
|
313
344
|
usageDir,
|
|
314
345
|
utcDay,
|
|
315
346
|
usagePath,
|
|
316
347
|
readUsage,
|
|
317
348
|
readAllUsage,
|
|
349
|
+
readUnavailableUsage,
|
|
318
350
|
budgetStatus,
|
|
319
351
|
assertBudgetAvailable,
|
|
320
352
|
recordTokenUsage,
|
package/lib/cli-args.js
CHANGED
|
@@ -19,12 +19,26 @@ const WRITER_COMMANDS = Object.freeze({
|
|
|
19
19
|
projects: { flags: ['--json'], valued: ['--root', '--depth'], positionals: null },
|
|
20
20
|
// `run --abandon` (issue #46) is a writer; plain `run` takes free text.
|
|
21
21
|
'run:abandon': { flags: ['--abandon', '--yes', '--json'], valued: ['--run', '--reason', '--by'], positionals: [] },
|
|
22
|
+
bench: {
|
|
23
|
+
flags: ['--json', '--sandbox-home'],
|
|
24
|
+
valued: ['--host', '--model', '--scenario', '--repeat', '--bin', '--mode', '--timeout', '--host-arg'],
|
|
25
|
+
positionals: []
|
|
26
|
+
},
|
|
22
27
|
migrate: { flags: ['--json', '--dry-run'], valued: ['--from'], positionals: [] },
|
|
23
28
|
verify: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
|
|
29
|
+
learn: { flags: ['--json', '--dry-run', '--prune'], valued: ['--max-age-runs'], positionals: [] },
|
|
30
|
+
guard: { flags: ['--json'], valued: ['--run', '--tool', '--input', '--path', '--command', '--hook'], positionals: ['check'] },
|
|
31
|
+
hooks: { flags: ['--json'], valued: ['--host'], positionals: ['install', 'uninstall', 'status'] },
|
|
32
|
+
impact: { flags: ['--json', '--force'], valued: ['--run', '--by', '--reason', '--allow', '--remove', '--limit'], positionals: ['map', 'show', 'confirm', 'skip', 'drift'] },
|
|
24
33
|
'review-pack': { flags: ['--json'], valued: ['--run', '--base', '--profile'], positionals: [] },
|
|
25
|
-
deliver: { flags: ['--json', '--approve'], valued: ['--run', '--destination', '--summary', '--by'], positionals: [] },
|
|
34
|
+
deliver: { flags: ['--json', '--approve'], valued: ['--run', '--destination', '--summary', '--by', '--host', '--model', '--head', '--evidence'], positionals: [] },
|
|
26
35
|
'generate-adapter': { flags: [], valued: ['--type'], positionals: [] },
|
|
27
|
-
'generate-workflow': { flags: ['--write'], valued: [], positionals: [] }
|
|
36
|
+
'generate-workflow': { flags: ['--write'], valued: [], positionals: [] },
|
|
37
|
+
workflow: {
|
|
38
|
+
flags: ['--json'],
|
|
39
|
+
valued: ['--answers', '--proposal', '--by', '--mode'],
|
|
40
|
+
positionals: ['interview', 'propose', 'accept', 'reject', 'suggest']
|
|
41
|
+
}
|
|
28
42
|
});
|
|
29
43
|
|
|
30
44
|
function beforeSeparator(args) {
|
|
@@ -35,6 +49,7 @@ function beforeSeparator(args) {
|
|
|
35
49
|
// `run --abandon ...` is checked as its own writer command.
|
|
36
50
|
function effectiveCommand(command, rest) {
|
|
37
51
|
if (command === 'run' && beforeSeparator(rest).includes('--abandon')) return 'run:abandon';
|
|
52
|
+
if (command === 'bench' && beforeSeparator(rest)[0] === 'compare') return 'bench:compare';
|
|
38
53
|
return command;
|
|
39
54
|
}
|
|
40
55
|
|
package/lib/doctor.js
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
const fs = require('fs');
|
|
4
4
|
const path = require('path');
|
|
5
5
|
const { loadEvaluationCases } = require('./evaluation.js');
|
|
6
|
+
const { loadBenchScenarios } = require('./bench.js');
|
|
6
7
|
const { auditPackage } = require('./package-audit.js');
|
|
7
8
|
const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
|
|
8
9
|
const { checkAdapter } = require('./adapter-check.js');
|
|
@@ -44,7 +45,12 @@ const REQUIRED_SCHEMAS = [
|
|
|
44
45
|
'compiled-plan.schema.json',
|
|
45
46
|
'workflow-state.schema.json',
|
|
46
47
|
'workflow-event.schema.json',
|
|
47
|
-
'handoff.schema.json'
|
|
48
|
+
'handoff.schema.json',
|
|
49
|
+
'impact-map.schema.json',
|
|
50
|
+
'receipt.schema.json',
|
|
51
|
+
'learnings.schema.json',
|
|
52
|
+
'bench-scenario.schema.json',
|
|
53
|
+
'bench-result.schema.json'
|
|
48
54
|
];
|
|
49
55
|
|
|
50
56
|
function check(id, passed, detail) {
|
|
@@ -105,11 +111,23 @@ function runDoctor(rootDir = path.join(__dirname, '..'), { projectDir = null, ru
|
|
|
105
111
|
|
|
106
112
|
try {
|
|
107
113
|
const fixtures = loadEvaluationCases(path.join(rootDir, 'evals', 'cases'));
|
|
108
|
-
checks.push(check('evaluation-catalog', fixtures.length ===
|
|
114
|
+
checks.push(check('evaluation-catalog', fixtures.length === 25, `${fixtures.length} valid cases; required 25`));
|
|
109
115
|
} catch (cause) {
|
|
110
116
|
checks.push(check('evaluation-catalog', false, cause.message));
|
|
111
117
|
}
|
|
112
118
|
|
|
119
|
+
try {
|
|
120
|
+
const scenarios = loadBenchScenarios(path.join(rootDir, 'evals', 'scenarios'));
|
|
121
|
+
const trapCount = scenarios.filter((item) => (item.traps || []).length > 0).length;
|
|
122
|
+
checks.push(check(
|
|
123
|
+
'bench-catalog',
|
|
124
|
+
scenarios.length >= 6 && scenarios.length <= 8 && trapCount >= 2,
|
|
125
|
+
`${scenarios.length} bench scenarios; ${trapCount} with traps`
|
|
126
|
+
));
|
|
127
|
+
} catch (cause) {
|
|
128
|
+
checks.push(check('bench-catalog', false, cause.message));
|
|
129
|
+
}
|
|
130
|
+
|
|
113
131
|
const packageFiles = new Set(pkg.files || []);
|
|
114
132
|
const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/', 'studio/'];
|
|
115
133
|
const missingPackageEntries = requiredPackageEntries.filter((entry) => !packageFiles.has(entry));
|
package/lib/gates.js
CHANGED
|
@@ -157,9 +157,29 @@ function validateGoalContract(contract) {
|
|
|
157
157
|
}
|
|
158
158
|
});
|
|
159
159
|
}
|
|
160
|
+
errors.push(...validateGoalScope(contract.scope));
|
|
160
161
|
return { valid: errors.length === 0, errors };
|
|
161
162
|
}
|
|
162
163
|
|
|
164
|
+
// Optional Goal scope (#59): absent = no path enforcement.
|
|
165
|
+
function validateGoalScope(scope) {
|
|
166
|
+
if (scope === undefined) return [];
|
|
167
|
+
if (!scope || typeof scope !== 'object' || Array.isArray(scope)) return ['scope must be an object'];
|
|
168
|
+
const errors = [];
|
|
169
|
+
for (const key of Object.keys(scope)) {
|
|
170
|
+
if (!['allowedPaths', 'deniedPaths'].includes(key)) errors.push(`scope.${key} is not supported (use allowedPaths, deniedPaths)`);
|
|
171
|
+
}
|
|
172
|
+
for (const key of ['allowedPaths', 'deniedPaths']) {
|
|
173
|
+
if (scope[key] === undefined) continue;
|
|
174
|
+
if (!Array.isArray(scope[key]) || scope[key].some((item) => typeof item !== 'string' || !item.trim())) {
|
|
175
|
+
errors.push(`scope.${key} must be an array of non-empty glob strings`);
|
|
176
|
+
} else if (scope[key].some((item) => item.startsWith('/') || item.split('/').includes('..'))) {
|
|
177
|
+
errors.push(`scope.${key} globs must be repository-relative`);
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
return errors;
|
|
181
|
+
}
|
|
182
|
+
|
|
163
183
|
function validateVerificationBundle(bundle, run, diffHash, currentRevision) {
|
|
164
184
|
const errors = [];
|
|
165
185
|
requireRunMetadata(bundle, run, 'verification');
|
|
@@ -310,6 +330,24 @@ function writeDeterministicVerdictIfEligible(rootDir, run) {
|
|
|
310
330
|
return true;
|
|
311
331
|
}
|
|
312
332
|
|
|
333
|
+
// Out-of-map changes recorded by verify (#71) become LOW ledger warnings,
|
|
334
|
+
// so they reach the Judge and the receipt without blocking delivery.
|
|
335
|
+
function mergeImpactDrift(rootDir, run) {
|
|
336
|
+
const { loadImpactDrift, mergeDriftIntoLedger } = require('./impact-map.js');
|
|
337
|
+
const drift = loadImpactDrift(rootDir, run.runId);
|
|
338
|
+
const filePath = artifactPath(rootDir, run.runId, GATE_FILES.review);
|
|
339
|
+
if (!drift?.outOfMap?.length || !fs.existsSync(filePath)) return 0;
|
|
340
|
+
let ledger;
|
|
341
|
+
try {
|
|
342
|
+
ledger = JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
343
|
+
} catch {
|
|
344
|
+
return 0;
|
|
345
|
+
}
|
|
346
|
+
const merged = mergeDriftIntoLedger(ledger, drift);
|
|
347
|
+
if (merged.added) fs.writeFileSync(filePath, `${JSON.stringify(merged.ledger, null, 2)}\n`, { mode: 0o600 });
|
|
348
|
+
return merged.added;
|
|
349
|
+
}
|
|
350
|
+
|
|
313
351
|
function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
|
|
314
352
|
if (!Object.hasOwn(GATE_FILES, gate)) {
|
|
315
353
|
throw gateError(`Unknown gate: ${gate}. Use ${Object.keys(GATE_FILES).join('|')}`);
|
|
@@ -412,6 +450,7 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
|
|
|
412
450
|
assertArtifactCurrent(rootDir, run, 'diff');
|
|
413
451
|
assertArtifactCurrent(rootDir, run, 'verification');
|
|
414
452
|
if (tierOf(run) === 'T0') writeT0FindingLedger(rootDir, run);
|
|
453
|
+
mergeImpactDrift(rootDir, run);
|
|
415
454
|
const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.review);
|
|
416
455
|
requireRunMetadata(value, run, 'Finding Ledger');
|
|
417
456
|
if (value.diffHash !== run.artifacts.diff?.sha256) {
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// `hooks install | uninstall | status` (#59): native pre-tool hooks that call
|
|
4
|
+
// `guard check`. Claude Code first; hosts without a hook API stay advisory.
|
|
5
|
+
// Project-level settings, because the guard reads this repository's Run.
|
|
6
|
+
|
|
7
|
+
const fs = require('fs');
|
|
8
|
+
const path = require('path');
|
|
9
|
+
const { HOSTS, getHost, guardrailSupport } = require('./hosts/registry.js');
|
|
10
|
+
|
|
11
|
+
const HOOK_MARKER = 'ai-engineering-loop guard check';
|
|
12
|
+
const CLAUDE_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit|Bash';
|
|
13
|
+
const CLAUDE_COMMAND = 'npx --yes ai-engineering-loop guard check --hook claude';
|
|
14
|
+
|
|
15
|
+
function hooksError(message, code = 'INVALID_USAGE') {
|
|
16
|
+
const error = new Error(message);
|
|
17
|
+
error.code = code;
|
|
18
|
+
return error;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function hookHost(hostId = 'claude') {
|
|
22
|
+
const host = getHost(hostId);
|
|
23
|
+
if (!host) throw hooksError(`Unknown host: ${hostId}`);
|
|
24
|
+
if (guardrailSupport(host) !== 'enforced') {
|
|
25
|
+
const enforced = HOSTS.filter((item) => guardrailSupport(item) === 'enforced').map((item) => item.id);
|
|
26
|
+
throw hooksError(`${host.name} has no hook API; its guardrails are advisory. Hosts with hooks: ${enforced.join(', ')}`, 'HOOKS_UNSUPPORTED');
|
|
27
|
+
}
|
|
28
|
+
return host;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function settingsPath(rootDir, host) {
|
|
32
|
+
return path.join(rootDir, host.hooks.settings);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function readSettings(filePath) {
|
|
36
|
+
if (!fs.existsSync(filePath)) return {};
|
|
37
|
+
const stat = fs.lstatSync(filePath);
|
|
38
|
+
if (stat.isSymbolicLink() || !stat.isFile()) throw hooksError(`${filePath} must be a regular file`, 'UNSAFE_HOOKS_PATH');
|
|
39
|
+
try {
|
|
40
|
+
const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
41
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('not an object');
|
|
42
|
+
return value;
|
|
43
|
+
} catch (cause) {
|
|
44
|
+
throw hooksError(`Cannot update ${path.basename(filePath)}: ${cause.message}. Nothing was written.`, 'INVALID_HOOKS_SETTINGS');
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
function writeSettings(filePath, value) {
|
|
49
|
+
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
|
50
|
+
const temporary = `${filePath}.${process.pid}.tmp`;
|
|
51
|
+
fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
|
|
52
|
+
fs.renameSync(temporary, filePath);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function isOurHook(hook) {
|
|
56
|
+
return typeof hook?.command === 'string' && hook.command.includes(HOOK_MARKER);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function ourEntries(settings) {
|
|
60
|
+
return (settings.hooks?.PreToolUse || []).filter((entry) => (entry.hooks || []).some(isOurHook));
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function hooksStatus(rootDir, { host: hostId = 'claude' } = {}) {
|
|
64
|
+
const host = hookHost(hostId);
|
|
65
|
+
const filePath = settingsPath(rootDir, host);
|
|
66
|
+
const settings = readSettings(filePath);
|
|
67
|
+
return {
|
|
68
|
+
host: host.id,
|
|
69
|
+
guardrails: guardrailSupport(host),
|
|
70
|
+
settings: host.hooks.settings,
|
|
71
|
+
installed: ourEntries(settings).length > 0
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
function installHooks(rootDir, { host: hostId = 'claude' } = {}) {
|
|
76
|
+
const host = hookHost(hostId);
|
|
77
|
+
const filePath = settingsPath(rootDir, host);
|
|
78
|
+
const settings = readSettings(filePath);
|
|
79
|
+
if (ourEntries(settings).length) return { ...hooksStatus(rootDir, { host: host.id }), changed: false };
|
|
80
|
+
const hooks = settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
|
|
81
|
+
const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
|
|
82
|
+
writeSettings(filePath, {
|
|
83
|
+
...settings,
|
|
84
|
+
hooks: {
|
|
85
|
+
...hooks,
|
|
86
|
+
PreToolUse: [...preToolUse, { matcher: CLAUDE_MATCHER, hooks: [{ type: 'command', command: CLAUDE_COMMAND }] }]
|
|
87
|
+
}
|
|
88
|
+
});
|
|
89
|
+
return { ...hooksStatus(rootDir, { host: host.id }), changed: true };
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function uninstallHooks(rootDir, { host: hostId = 'claude' } = {}) {
|
|
93
|
+
const host = hookHost(hostId);
|
|
94
|
+
const filePath = settingsPath(rootDir, host);
|
|
95
|
+
if (!fs.existsSync(filePath)) return { ...hooksStatus(rootDir, { host: host.id }), changed: false };
|
|
96
|
+
const settings = readSettings(filePath);
|
|
97
|
+
if (!ourEntries(settings).length) return { ...hooksStatus(rootDir, { host: host.id }), changed: false };
|
|
98
|
+
const preToolUse = settings.hooks.PreToolUse
|
|
99
|
+
.map((entry) => ({ ...entry, hooks: (entry.hooks || []).filter((hook) => !isOurHook(hook)) }))
|
|
100
|
+
.filter((entry) => entry.hooks.length);
|
|
101
|
+
const { PreToolUse: _removed, ...otherHooks } = settings.hooks;
|
|
102
|
+
const hooks = preToolUse.length ? { ...otherHooks, PreToolUse: preToolUse } : otherHooks;
|
|
103
|
+
const { hooks: _old, ...rest } = settings;
|
|
104
|
+
writeSettings(filePath, Object.keys(hooks).length ? { ...rest, hooks } : rest);
|
|
105
|
+
return { ...hooksStatus(rootDir, { host: host.id }), changed: true };
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
module.exports = {
|
|
109
|
+
HOOK_MARKER,
|
|
110
|
+
CLAUDE_COMMAND,
|
|
111
|
+
CLAUDE_MATCHER,
|
|
112
|
+
hooksStatus,
|
|
113
|
+
installHooks,
|
|
114
|
+
uninstallHooks
|
|
115
|
+
};
|
package/lib/guard.js
ADDED
|
@@ -0,0 +1,336 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Runtime guardrails (#59). `guard check` decides allow | warn | block for one
|
|
4
|
+
// tool call before it runs: Edit/Write outside the Run's scope, and Bash
|
|
5
|
+
// commands that destroy files, history, or data. ASSISTED warns (the host
|
|
6
|
+
// asks the human), UNATTENDED and REPORT_ONLY block. Every warn/block is
|
|
7
|
+
// appended to the Run as evidence.
|
|
8
|
+
|
|
9
|
+
const fs = require('fs');
|
|
10
|
+
const path = require('path');
|
|
11
|
+
const { RUN_MODES, TERMINAL_STATES, atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
|
|
12
|
+
const { loadPolicy } = require('./runtime-policy.js');
|
|
13
|
+
const { redactHomePaths, redactSecrets } = require('./safe-context.js');
|
|
14
|
+
const { impactScope, loadImpactMap, matchesAnyGlob } = require('./impact-map.js');
|
|
15
|
+
|
|
16
|
+
const GUARD_EVENTS_FILE = 'guard-events.json';
|
|
17
|
+
const MAX_EVENTS = 500;
|
|
18
|
+
const MAX_TARGET_CHARS = 300;
|
|
19
|
+
const DECISIONS = Object.freeze(['allow', 'warn', 'block']);
|
|
20
|
+
const EDIT_TOOLS = new Set(['edit', 'write', 'multiedit', 'notebookedit']);
|
|
21
|
+
const BASH_TOOLS = new Set(['bash', 'shell']);
|
|
22
|
+
|
|
23
|
+
function guardError(message, code = 'INVALID_USAGE') {
|
|
24
|
+
const error = new Error(message);
|
|
25
|
+
error.code = code;
|
|
26
|
+
return error;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function normalizeTool(tool) {
|
|
30
|
+
const value = String(tool || '').trim().toLowerCase();
|
|
31
|
+
if (EDIT_TOOLS.has(value)) return 'edit';
|
|
32
|
+
if (BASH_TOOLS.has(value)) return 'bash';
|
|
33
|
+
return value ? 'other' : null;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
// Accepts a Claude Code PreToolUse payload ({ tool_name, tool_input }) or a
|
|
37
|
+
// plain { path } / { command } object.
|
|
38
|
+
function parseGuardInput(input, tool) {
|
|
39
|
+
const value = input && typeof input === 'object' ? input : {};
|
|
40
|
+
const toolInput = value.tool_input && typeof value.tool_input === 'object' ? value.tool_input : value;
|
|
41
|
+
const kind = normalizeTool(tool || value.tool_name);
|
|
42
|
+
if (!kind) throw guardError('guard check needs --tool edit|bash or a payload with tool_name');
|
|
43
|
+
return {
|
|
44
|
+
tool: kind,
|
|
45
|
+
toolName: value.tool_name || tool,
|
|
46
|
+
path: toolInput.file_path || toolInput.notebook_path || toolInput.path || null,
|
|
47
|
+
command: typeof toolInput.command === 'string' ? toolInput.command : null
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
// Shell segments split on ; && || | and newlines; quotes are kept simple on
|
|
52
|
+
// purpose: a quoted "rm -rf" still warns, which errs on the safe side.
|
|
53
|
+
function segments(command) {
|
|
54
|
+
return String(command || '')
|
|
55
|
+
.split(/\n|;|&&|\|\||\|/)
|
|
56
|
+
.map((part) => part.trim().split(/\s+/).filter(Boolean).map((token) => token.replace(/^['"]|['"]$/g, '')))
|
|
57
|
+
.filter((tokens) => tokens.length);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function shortFlags(tokens) {
|
|
61
|
+
return tokens.filter((token) => /^-[A-Za-z]+$/.test(token)).join('').replace(/-/g, '');
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function commandIndex(tokens, name) {
|
|
65
|
+
return tokens.findIndex((token) => token === name || token.endsWith(`/${name}`));
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function gitSubcommand(tokens) {
|
|
69
|
+
const start = commandIndex(tokens, 'git');
|
|
70
|
+
if (start === -1) return null;
|
|
71
|
+
for (let index = start + 1; index < tokens.length; index += 1) {
|
|
72
|
+
const token = tokens[index];
|
|
73
|
+
if (token === '-C' || token === '-c') {
|
|
74
|
+
index += 1;
|
|
75
|
+
continue;
|
|
76
|
+
}
|
|
77
|
+
if (token.startsWith('-')) continue;
|
|
78
|
+
return { name: token, args: tokens.slice(index + 1) };
|
|
79
|
+
}
|
|
80
|
+
return null;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const DESTRUCTIVE_RULES = Object.freeze([
|
|
84
|
+
{
|
|
85
|
+
id: 'rm-recursive-force',
|
|
86
|
+
reason: 'rm with recursive and force flags deletes files without confirmation',
|
|
87
|
+
test: (tokens) => {
|
|
88
|
+
const start = commandIndex(tokens, 'rm');
|
|
89
|
+
if (start === -1) return false;
|
|
90
|
+
const args = tokens.slice(start + 1);
|
|
91
|
+
const flags = shortFlags(args);
|
|
92
|
+
const recursive = /[rR]/.test(flags) || args.includes('--recursive');
|
|
93
|
+
const force = flags.includes('f') || args.includes('--force');
|
|
94
|
+
return recursive && force;
|
|
95
|
+
}
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
id: 'git-push-force',
|
|
99
|
+
reason: 'git push --force rewrites remote history',
|
|
100
|
+
test: (tokens) => {
|
|
101
|
+
const git = gitSubcommand(tokens);
|
|
102
|
+
if (git?.name !== 'push') return false;
|
|
103
|
+
return git.args.some((arg) => arg === '--force' || arg.startsWith('--force-with-lease') ||
|
|
104
|
+
arg === '--force-if-includes' || (/^-[A-Za-z]+$/.test(arg) && arg.includes('f')) ||
|
|
105
|
+
(/^\+[^\s]/.test(arg)));
|
|
106
|
+
}
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
id: 'git-reset-hard',
|
|
110
|
+
reason: 'git reset --hard discards uncommitted work',
|
|
111
|
+
test: (tokens) => {
|
|
112
|
+
const git = gitSubcommand(tokens);
|
|
113
|
+
return git?.name === 'reset' && git.args.includes('--hard');
|
|
114
|
+
}
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
id: 'git-clean-force',
|
|
118
|
+
reason: 'git clean -fd deletes untracked files and directories',
|
|
119
|
+
test: (tokens) => {
|
|
120
|
+
const git = gitSubcommand(tokens);
|
|
121
|
+
if (git?.name !== 'clean') return false;
|
|
122
|
+
const flags = shortFlags(git.args);
|
|
123
|
+
const force = flags.includes('f') || git.args.includes('--force');
|
|
124
|
+
const dirs = flags.includes('d');
|
|
125
|
+
return force && dirs;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
]);
|
|
129
|
+
|
|
130
|
+
const SQL_RULES = Object.freeze([
|
|
131
|
+
{ id: 'sql-drop', reason: 'DROP TABLE/DATABASE/SCHEMA destroys data', pattern: /\bdrop\s+(?:table|database|schema)\b/i },
|
|
132
|
+
{ id: 'sql-truncate', reason: 'TRUNCATE deletes every row of a table', pattern: /\btruncate\s+(?:table\s+)?[`"'[]?[A-Za-z_]/i }
|
|
133
|
+
]);
|
|
134
|
+
|
|
135
|
+
function destructiveFindings(command) {
|
|
136
|
+
const findings = new Map();
|
|
137
|
+
for (const tokens of segments(command)) {
|
|
138
|
+
for (const rule of DESTRUCTIVE_RULES) {
|
|
139
|
+
if (rule.test(tokens)) findings.set(rule.id, rule.reason);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
for (const rule of SQL_RULES) {
|
|
143
|
+
if (rule.pattern.test(String(command || ''))) findings.set(rule.id, rule.reason);
|
|
144
|
+
}
|
|
145
|
+
return [...findings].map(([id, reason]) => ({ id, reason }));
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function activeRun(rootDir, runId) {
|
|
149
|
+
if (runId) return loadRun(rootDir, runId);
|
|
150
|
+
const current = getCurrentRun(rootDir);
|
|
151
|
+
return current && !TERMINAL_STATES.has(current.state) ? current : null;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function readFrozenGoal(rootDir, run) {
|
|
155
|
+
const filePath = path.join(runsDir(rootDir), run.runId, 'goal-contract.json');
|
|
156
|
+
if (!fs.existsSync(filePath)) return null;
|
|
157
|
+
try {
|
|
158
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
159
|
+
} catch {
|
|
160
|
+
return null;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// Allowed = the frozen Goal's scope.allowedPaths plus the confirmed impact
|
|
165
|
+
// map (#71); denied = the Goal's scope.deniedPaths. No allowed list means no
|
|
166
|
+
// path enforcement, but denied paths always apply.
|
|
167
|
+
function runScope(rootDir, run) {
|
|
168
|
+
if (!run) return { allowedPaths: null, deniedPaths: [], sources: [] };
|
|
169
|
+
const goal = readFrozenGoal(rootDir, run);
|
|
170
|
+
const mapScope = impactScope(loadImpactMap(rootDir, run.runId));
|
|
171
|
+
const sources = [];
|
|
172
|
+
let allowed = null;
|
|
173
|
+
if (Array.isArray(goal?.scope?.allowedPaths)) {
|
|
174
|
+
allowed = [...goal.scope.allowedPaths];
|
|
175
|
+
sources.push('goal');
|
|
176
|
+
}
|
|
177
|
+
if (mapScope) {
|
|
178
|
+
allowed = [...(allowed || []), ...mapScope.allowedPaths];
|
|
179
|
+
sources.push('impact-map');
|
|
180
|
+
}
|
|
181
|
+
return {
|
|
182
|
+
allowedPaths: allowed ? [...new Set(allowed)].sort() : null,
|
|
183
|
+
deniedPaths: Array.isArray(goal?.scope?.deniedPaths) ? [...goal.scope.deniedPaths] : [],
|
|
184
|
+
sources
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
// Real path of a file that may not exist yet: resolve the nearest existing
|
|
189
|
+
// ancestor (macOS /var -> /private/var, symlinked checkouts) and re-append.
|
|
190
|
+
function realish(target) {
|
|
191
|
+
let current = path.resolve(target);
|
|
192
|
+
const rest = [];
|
|
193
|
+
for (;;) {
|
|
194
|
+
try {
|
|
195
|
+
return path.join(fs.realpathSync(current), ...rest);
|
|
196
|
+
} catch {
|
|
197
|
+
const parent = path.dirname(current);
|
|
198
|
+
if (parent === current) return path.resolve(target);
|
|
199
|
+
rest.unshift(path.basename(current));
|
|
200
|
+
current = parent;
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
function repoRelative(rootDir, filePath) {
|
|
206
|
+
const absolute = path.resolve(rootDir, String(filePath));
|
|
207
|
+
const pairs = [[path.resolve(rootDir), absolute], [realish(rootDir), realish(absolute)]];
|
|
208
|
+
for (const [root, target] of pairs) {
|
|
209
|
+
const rel = path.relative(root, target);
|
|
210
|
+
if (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)) return rel.split(path.sep).join('/');
|
|
211
|
+
}
|
|
212
|
+
return null;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
function scopeFindings(rootDir, filePath, scope) {
|
|
216
|
+
if (!filePath) return [];
|
|
217
|
+
const relative = repoRelative(rootDir, filePath);
|
|
218
|
+
if (relative != null && (relative === '.ai-engineering-loop' || relative.startsWith('.ai-engineering-loop/'))) return [];
|
|
219
|
+
if (relative == null) {
|
|
220
|
+
return scope.allowedPaths ? [{ id: 'outside-repository', reason: 'edit target is outside the repository and the Run scope' }] : [];
|
|
221
|
+
}
|
|
222
|
+
if (matchesAnyGlob(relative, scope.deniedPaths)) {
|
|
223
|
+
return [{ id: 'scope-denied', reason: `${relative} matches scope.deniedPaths` }];
|
|
224
|
+
}
|
|
225
|
+
if (scope.allowedPaths && !matchesAnyGlob(relative, scope.allowedPaths)) {
|
|
226
|
+
return [{ id: 'scope-outside', reason: `${relative} is outside the Run scope (${scope.sources.join(' + ')})` }];
|
|
227
|
+
}
|
|
228
|
+
return [];
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
function decisionFor(mode, findings) {
|
|
232
|
+
if (!findings.length) return 'allow';
|
|
233
|
+
return mode === RUN_MODES.ASSISTED ? 'warn' : 'block';
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
function safeTarget(parsed, rootDir) {
|
|
237
|
+
const raw = parsed.tool === 'bash' ? parsed.command : (repoRelative(rootDir, parsed.path || '') ?? parsed.path);
|
|
238
|
+
return redactHomePaths(redactSecrets(String(raw || '')).text).slice(0, MAX_TARGET_CHARS);
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
function recordGuardEvent(rootDir, runId, event) {
|
|
242
|
+
const filePath = path.join(runsDir(rootDir), runId, GUARD_EVENTS_FILE);
|
|
243
|
+
let events = [];
|
|
244
|
+
if (fs.existsSync(filePath)) {
|
|
245
|
+
try {
|
|
246
|
+
const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
247
|
+
if (Array.isArray(parsed.events)) events = parsed.events;
|
|
248
|
+
} catch {
|
|
249
|
+
events = [];
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
events.push(event);
|
|
253
|
+
atomicWriteJson(filePath, { schemaVersion: 1, runId, events: events.slice(-MAX_EVENTS) });
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
function checkGuard(rootDir, { tool, input, runId, now = new Date() } = {}) {
|
|
257
|
+
const parsed = parseGuardInput(input, tool);
|
|
258
|
+
const run = activeRun(rootDir, runId);
|
|
259
|
+
const mode = run?.mode || loadPolicy(rootDir).defaultMode;
|
|
260
|
+
let findings = [];
|
|
261
|
+
if (parsed.tool === 'edit') {
|
|
262
|
+
if (run && mode === RUN_MODES.REPORT_ONLY) {
|
|
263
|
+
findings.push({ id: 'report-only-mutation', reason: 'REPORT_ONLY runs must not edit the repository' });
|
|
264
|
+
}
|
|
265
|
+
findings.push(...scopeFindings(rootDir, parsed.path, runScope(rootDir, run)));
|
|
266
|
+
} else if (parsed.tool === 'bash') {
|
|
267
|
+
findings = destructiveFindings(parsed.command);
|
|
268
|
+
}
|
|
269
|
+
const decision = decisionFor(mode, findings);
|
|
270
|
+
const result = {
|
|
271
|
+
decision,
|
|
272
|
+
tool: parsed.tool,
|
|
273
|
+
mode,
|
|
274
|
+
runId: run?.runId || null,
|
|
275
|
+
rules: findings.map((item) => item.id),
|
|
276
|
+
reasons: findings.map((item) => item.reason)
|
|
277
|
+
};
|
|
278
|
+
if (run && decision !== 'allow') {
|
|
279
|
+
recordGuardEvent(rootDir, run.runId, {
|
|
280
|
+
at: now.toISOString(),
|
|
281
|
+
tool: parsed.toolName || parsed.tool,
|
|
282
|
+
decision,
|
|
283
|
+
mode,
|
|
284
|
+
rules: result.rules,
|
|
285
|
+
reasons: result.reasons,
|
|
286
|
+
target: safeTarget(parsed, rootDir)
|
|
287
|
+
});
|
|
288
|
+
}
|
|
289
|
+
return result;
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
function loadGuardEvents(rootDir, runId) {
|
|
293
|
+
const filePath = path.join(runsDir(rootDir), runId, GUARD_EVENTS_FILE);
|
|
294
|
+
if (!fs.existsSync(filePath)) return [];
|
|
295
|
+
try {
|
|
296
|
+
const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
297
|
+
return Array.isArray(parsed.events) ? parsed.events : [];
|
|
298
|
+
} catch {
|
|
299
|
+
return [];
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
function guardSummary(rootDir, runId) {
|
|
304
|
+
const events = loadGuardEvents(rootDir, runId);
|
|
305
|
+
return {
|
|
306
|
+
warn: events.filter((event) => event.decision === 'warn').length,
|
|
307
|
+
block: events.filter((event) => event.decision === 'block').length,
|
|
308
|
+
rules: [...new Set(events.flatMap((event) => event.rules || []))].sort()
|
|
309
|
+
};
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
// Claude Code PreToolUse output: deny blocks the call, ask hands it to the
|
|
313
|
+
// human, and allow prints nothing so the normal permission flow continues.
|
|
314
|
+
function claudeHookOutput(result) {
|
|
315
|
+
if (result.decision === 'allow') return null;
|
|
316
|
+
return {
|
|
317
|
+
hookSpecificOutput: {
|
|
318
|
+
hookEventName: 'PreToolUse',
|
|
319
|
+
permissionDecision: result.decision === 'block' ? 'deny' : 'ask',
|
|
320
|
+
permissionDecisionReason: `ai-engineering-loop guard (${result.mode}): ${result.reasons.join('; ')}`
|
|
321
|
+
}
|
|
322
|
+
};
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
module.exports = {
|
|
326
|
+
DECISIONS,
|
|
327
|
+
GUARD_EVENTS_FILE,
|
|
328
|
+
DESTRUCTIVE_RULES,
|
|
329
|
+
parseGuardInput,
|
|
330
|
+
destructiveFindings,
|
|
331
|
+
runScope,
|
|
332
|
+
checkGuard,
|
|
333
|
+
loadGuardEvents,
|
|
334
|
+
guardSummary,
|
|
335
|
+
claudeHookOutput
|
|
336
|
+
};
|
package/lib/hosts/commands.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
// then runs the normal sync (manifest-based copy and cleanup).
|
|
6
6
|
|
|
7
7
|
const path = require('path');
|
|
8
|
-
const { HOSTS, HOST_IDS, OUT_OF_SCOPE, SHARED_SKILLS_DIR, getHost, usesSharedSkills } = require('./registry.js');
|
|
8
|
+
const { HOSTS, HOST_IDS, OUT_OF_SCOPE, SHARED_SKILLS_DIR, getHost, guardrailSupport, usesSharedSkills } = require('./registry.js');
|
|
9
9
|
const { detectHosts } = require('./detect.js');
|
|
10
10
|
const { readUserConfig, writeUserConfig } = require('../user-state.js');
|
|
11
11
|
|
|
@@ -35,6 +35,7 @@ function listHosts({ home, env = process.env, selection }) {
|
|
|
35
35
|
id: host.id,
|
|
36
36
|
name: host.name,
|
|
37
37
|
certification: host.certification,
|
|
38
|
+
guardrails: guardrailSupport(host),
|
|
38
39
|
detected: d.detected,
|
|
39
40
|
via: [...d.dirs.map((dir) => `~/${dir}`), ...d.bins.map((bin) => `PATH:${path.basename(bin)}`)],
|
|
40
41
|
enabled: selection.enabled.has(host.id),
|
|
@@ -47,10 +48,10 @@ function listHosts({ home, env = process.env, selection }) {
|
|
|
47
48
|
|
|
48
49
|
function formatHostsList(rows, selection) {
|
|
49
50
|
const lines = [`Hosts (${selection.source === 'config' ? `saved selection, mode ${selection.mode}` : 'no setup yet: hosts with a config folder are synced'})`];
|
|
50
|
-
lines.push(` ${'id'.padEnd(16)} ${'enabled'.padEnd(8)} ${'certification'.padEnd(17)} ${'detected'.padEnd(28)} skills`);
|
|
51
|
+
lines.push(` ${'id'.padEnd(16)} ${'enabled'.padEnd(8)} ${'certification'.padEnd(17)} ${'guardrails'.padEnd(10)} ${'detected'.padEnd(28)} skills`);
|
|
51
52
|
for (const row of rows) {
|
|
52
53
|
const state = row.enabled ? 'yes' : row.disabled ? 'off' : '-';
|
|
53
|
-
lines.push(` ${row.id.padEnd(16)} ${state.padEnd(8)} ${row.certification.padEnd(17)} ${(row.detected ? row.via.join(',') : '-').slice(0, 28).padEnd(28)} ${row.skills}`);
|
|
54
|
+
lines.push(` ${row.id.padEnd(16)} ${state.padEnd(8)} ${row.certification.padEnd(17)} ${row.guardrails.padEnd(10)} ${(row.detected ? row.via.join(',') : '-').slice(0, 28).padEnd(28)} ${row.skills}`);
|
|
54
55
|
}
|
|
55
56
|
lines.push(`Out of scope (no native skills): ${OUT_OF_SCOPE.map((h) => h.name).join(', ')}.`);
|
|
56
57
|
return lines.join('\n');
|