ai-engineering-loop 1.5.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -2
- package/README.npm.md +7 -0
- package/SECURITY.md +3 -1
- package/bin/ai-engineering-loop.js +130 -4
- package/core/local-workflow-studio.md +77 -0
- package/lib/doctor.js +3 -2
- package/lib/handoff.js +209 -0
- package/lib/runtime-files.js +1 -0
- package/lib/studio-server.js +183 -0
- package/lib/workflow-runtime.js +30 -4
- package/package.json +2 -1
- package/schemas/handoff.schema.json +36 -0
- package/schemas/workflow-event.schema.json +1 -0
- package/studio/app.js +461 -0
- package/studio/index.html +31 -0
- package/studio/styles.css +75 -0
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
[](https://github.com/egagofur/ai-engineering-loop/pulls)
|
|
7
7
|
[](https://github.com/egagofur/ai-engineering-loop)
|
|
8
|
-
[](https://github.com/egagofur/ai-engineering-loop/releases)
|
|
9
9
|
|
|
10
10
|
**A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
|
|
11
11
|
|
|
@@ -237,9 +237,19 @@ npx ai-engineering-loop recipe install candidate-v2.json --replace
|
|
|
237
237
|
# Operate a custom node in an immutable recipe-bound run
|
|
238
238
|
npx ai-engineering-loop node status
|
|
239
239
|
npx ai-engineering-loop node start root-cause
|
|
240
|
+
npx ai-engineering-loop node activity root-cause --message "Comparing failing evidence"
|
|
240
241
|
npx ai-engineering-loop node complete root-cause --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
|
|
241
242
|
npx ai-engineering-loop node approve delivery-approval --yes
|
|
242
243
|
|
|
244
|
+
# Open the local workflow canvas (localhost-only, authenticated session)
|
|
245
|
+
npx ai-engineering-loop studio
|
|
246
|
+
npx ai-engineering-loop studio --port 4400 --no-open
|
|
247
|
+
|
|
248
|
+
# Transfer redacted knowledge to another developer or agent
|
|
249
|
+
npx ai-engineering-loop handoff create --audience developer
|
|
250
|
+
npx ai-engineering-loop handoff inspect <run-id>.ael-handoff.json
|
|
251
|
+
npx ai-engineering-loop handoff brief <run-id>.ael-handoff.json
|
|
252
|
+
|
|
243
253
|
# Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
244
254
|
npx ai-engineering-loop sync-hosts
|
|
245
255
|
|
|
@@ -256,7 +266,7 @@ Every full run stores private local artifacts under `.ai-engineering-loop/runs/<
|
|
|
256
266
|
|
|
257
267
|
Declarative recipes let an AI or future visual editor author a workflow graph without weakening the safety gates. Built-in presets and project recipes can be validated, explained, graphed, and simulated deterministically. `run --recipe` opts into an immutable, resumable DAG scheduler; legacy runs remain unchanged. See [`core/workflow-recipes.md`](core/workflow-recipes.md) and [`core/controlled-workflow-runtime.md`](core/controlled-workflow-runtime.md).
|
|
258
268
|
|
|
259
|
-
The deterministic recipe builder scaffolds from safe presets, validates candidates before atomic installation, preserves replaced versions locally, and
|
|
269
|
+
The deterministic recipe builder scaffolds from safe presets, validates candidates before atomic installation, and preserves replaced versions locally. Workflow Studio is a thin local interface over that compiler and controlled runtime: animated DAG state, live activity and budget telemetry, explicit approval/retry controls, decision memory, and integrity-bound handoff export—without model or shell execution in the browser. See [`core/local-workflow-studio.md`](core/local-workflow-studio.md). The host-neutral agent protocol remains available in [`agents/recipe-builder.md`](agents/recipe-builder.md).
|
|
260
270
|
|
|
261
271
|
Shipped adapters (Stage 8 only, after Judge PASS): `standard`, `github`, `gitlab`, `dot`. Catalog: `adapters/README.md`. Each team generates its own; do not copy a neighbour's pipeline.
|
|
262
272
|
|
package/README.npm.md
CHANGED
|
@@ -34,6 +34,12 @@ npx ai-engineering-loop run --mode report-only "audit this repository"
|
|
|
34
34
|
npx ai-engineering-loop policy show
|
|
35
35
|
npx ai-engineering-loop budget status
|
|
36
36
|
|
|
37
|
+
# Author and observe deterministic workflow recipes locally
|
|
38
|
+
npx ai-engineering-loop studio
|
|
39
|
+
|
|
40
|
+
# Export a redacted, integrity-bound knowledge handoff
|
|
41
|
+
npx ai-engineering-loop handoff create --audience developer
|
|
42
|
+
|
|
37
43
|
# 5. Copy package host skills into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
38
44
|
npx ai-engineering-loop sync-hosts
|
|
39
45
|
```
|
|
@@ -48,6 +54,7 @@ npx ai-engineering-loop sync-hosts
|
|
|
48
54
|
4. **Context Impact Assessment**: Evaluates completed tasks (`NONE`, `TARGETED`, `MAJOR`) to keep project context fresh without expensive whole-repo re-analysis.
|
|
49
55
|
5. **Grok CLI host**: Native `spawn_subagent` for Devil's Advocate and Judge (`TRUE_INDEPENDENT_AGENT`). Disabled by `GROK_SUBAGENTS=0`.
|
|
50
56
|
6. **Production runtime controls**: `REPORT_ONLY`, human-approved `ASSISTED`, opt-in `UNATTENDED`, actual token ledgers, a persistent kill switch, and locked disposable Maker worktrees.
|
|
57
|
+
7. **Local Workflow Studio**: A localhost-only authenticated DAG canvas with animated live stage state, token telemetry, explicit approvals, decision memory, atomic recipe installation, and redacted handoff export. It does not execute models or shell commands in the browser.
|
|
51
58
|
|
|
52
59
|
---
|
|
53
60
|
|
package/SECURITY.md
CHANGED
|
@@ -8,6 +8,8 @@ AI Engineering Loop blocks `.env*`, private-key formats, common credential files
|
|
|
8
8
|
|
|
9
9
|
No telemetry is collected. Token usage ledgers stay local and contain counts plus provider model identifiers, not prompts or responses. Stage 0–7 require no AI Engineering Loop network service. Delivery adapters may use authenticated forge tools only after Judge `PASS`; ASSISTED requires explicit human approval before delivery.
|
|
10
10
|
|
|
11
|
+
Workflow Studio binds to `127.0.0.1`, validates local `Host` headers, and requires a random process-local session token exchanged for an HttpOnly SameSite cookie. Its bundled browser client has no model, shell, telemetry, or remote-asset capability. Do not expose the Studio port through a reverse proxy or public tunnel. Handoff exports omit source content and redact recognized secrets and home paths; verify their integrity hash on import, and still review them before sharing because pattern-based redaction cannot recognize every private value.
|
|
12
|
+
|
|
11
13
|
UNATTENDED is disabled by default and Maker uses a locked disposable Git worktree when enabled. This protects the parent checkout and prevents concurrent Maker sessions; it is not an OS sandbox. For untrusted code, use a container or VM with restricted credentials, filesystem, processes, and network. See `core/runtime-safety.md`.
|
|
12
14
|
|
|
13
15
|
Package releases use npm trusted publishing from `.github/workflows/publish.yml`, with a pinned OIDC-capable npm CLI and provenance. The package owner must configure `egagofur/ai-engineering-loop`, workflow `publish.yml`, and environment `npm` as the trusted publisher on npmjs.com. Do not add `NPM_TOKEN` or another long-lived publish credential to the repository or GitHub environment.
|
|
@@ -18,7 +20,7 @@ Package releases use npm trusted publishing from `.github/workflows/publish.yml`
|
|
|
18
20
|
- Never place credentials in `.ai-engineering-loop/`, workflow files, prompts, findings, or delivery reports.
|
|
19
21
|
- Do not pass the parent process environment to a child unless the host owns that boundary.
|
|
20
22
|
- Treat generated run artifacts as sensitive local files. The CLI writes state and context packs with mode `0600` where supported.
|
|
21
|
-
- Keep `runs/`, `usage/`, `worktrees/`, `locks/`, and task logs under the generated `.ai-engineering-loop/.gitignore`.
|
|
23
|
+
- Keep `runs/`, `usage/`, `worktrees/`, `locks/`, temporary Studio `drafts/`, and task logs under the generated `.ai-engineering-loop/.gitignore`.
|
|
22
24
|
- Use `budget pause` to stop new model boundaries if spend, behavior, or credentials are in doubt. Recording an already completed call remains possible while paused.
|
|
23
25
|
- Run a dedicated secret scanner such as `gitleaks` before delivery when available.
|
|
24
26
|
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
const fs = require('fs');
|
|
14
14
|
const path = require('path');
|
|
15
15
|
const crypto = require('crypto');
|
|
16
|
-
const { execSync } = require('child_process');
|
|
16
|
+
const { execSync, spawn } = require('child_process');
|
|
17
17
|
const {
|
|
18
18
|
homeDir,
|
|
19
19
|
applyHostSync,
|
|
@@ -98,6 +98,7 @@ const {
|
|
|
98
98
|
completeWorkflowNode,
|
|
99
99
|
createWorkflowBundle,
|
|
100
100
|
failWorkflowNode,
|
|
101
|
+
recordWorkflowActivity,
|
|
101
102
|
retryWorkflowNode,
|
|
102
103
|
startWorkflowNode,
|
|
103
104
|
workflowStatus
|
|
@@ -109,8 +110,15 @@ const {
|
|
|
109
110
|
installRecipe,
|
|
110
111
|
recipeCatalog
|
|
111
112
|
} = require('../lib/recipe-builder.js');
|
|
112
|
-
|
|
113
|
-
|
|
113
|
+
const {
|
|
114
|
+
createHandoff,
|
|
115
|
+
handoffBrief,
|
|
116
|
+
readHandoff,
|
|
117
|
+
verifyHandoff
|
|
118
|
+
} = require('../lib/handoff.js');
|
|
119
|
+
const { createStudioServer } = require('../lib/studio-server.js');
|
|
120
|
+
|
|
121
|
+
const VERSION = '1.6.0';
|
|
114
122
|
const CWD = process.cwd();
|
|
115
123
|
const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
|
|
116
124
|
|
|
@@ -364,7 +372,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
|
|
|
364
372
|
|
|
365
373
|
// 0. metadata.json (Baseline)
|
|
366
374
|
const metadataJson = {
|
|
367
|
-
contextVersion: '1.
|
|
375
|
+
contextVersion: '1.6.0',
|
|
368
376
|
generatedAt: new Date().toISOString(),
|
|
369
377
|
repositoryRevision: currentRevision,
|
|
370
378
|
projectProfile: discovery.profile,
|
|
@@ -1175,6 +1183,11 @@ function handleNode() {
|
|
|
1175
1183
|
runId,
|
|
1176
1184
|
reason: argValue('--reason') || 'node execution failed'
|
|
1177
1185
|
});
|
|
1186
|
+
} else if (action === 'activity') {
|
|
1187
|
+
workflow = recordWorkflowActivity(CWD, nodeId, {
|
|
1188
|
+
runId,
|
|
1189
|
+
message: argValue('--message')
|
|
1190
|
+
});
|
|
1178
1191
|
} else if (action === 'retry') {
|
|
1179
1192
|
workflow = retryWorkflowNode(CWD, nodeId, { runId });
|
|
1180
1193
|
} else if (action === 'approve') {
|
|
@@ -1450,6 +1463,106 @@ function handleRecipe() {
|
|
|
1450
1463
|
}
|
|
1451
1464
|
}
|
|
1452
1465
|
|
|
1466
|
+
function safeHandoffOutput(file) {
|
|
1467
|
+
const absolute = path.resolve(CWD, file);
|
|
1468
|
+
const relative = path.relative(CWD, absolute);
|
|
1469
|
+
if (relative === '..' || relative.startsWith(`..${path.sep}`)) {
|
|
1470
|
+
throw Object.assign(new Error('Handoff output must stay inside the repository'), { code: 'UNSAFE_HANDOFF_PATH' });
|
|
1471
|
+
}
|
|
1472
|
+
const parent = path.dirname(absolute);
|
|
1473
|
+
fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
|
|
1474
|
+
const realRoot = fs.realpathSync(CWD);
|
|
1475
|
+
const realParent = fs.realpathSync(parent);
|
|
1476
|
+
if (realParent !== realRoot && !realParent.startsWith(`${realRoot}${path.sep}`)) {
|
|
1477
|
+
throw Object.assign(new Error('Handoff output escapes the repository through a symlink'), { code: 'UNSAFE_HANDOFF_PATH' });
|
|
1478
|
+
}
|
|
1479
|
+
return absolute;
|
|
1480
|
+
}
|
|
1481
|
+
|
|
1482
|
+
function handleHandoff() {
|
|
1483
|
+
const action = process.argv[3] || 'create';
|
|
1484
|
+
const json = process.argv.includes('--json');
|
|
1485
|
+
try {
|
|
1486
|
+
if (action === 'create') {
|
|
1487
|
+
const bundle = createHandoff(CWD, {
|
|
1488
|
+
runId: argValue('--run'),
|
|
1489
|
+
audience: argValue('--audience') || 'developer'
|
|
1490
|
+
});
|
|
1491
|
+
const requested = argValue('--output');
|
|
1492
|
+
if (requested === '-') {
|
|
1493
|
+
console.log(JSON.stringify(bundle, null, json ? 0 : 2));
|
|
1494
|
+
return;
|
|
1495
|
+
}
|
|
1496
|
+
const output = safeHandoffOutput(requested || `${bundle.runId}.ael-handoff.json`);
|
|
1497
|
+
const descriptor = fs.openSync(output, 'wx', 0o600);
|
|
1498
|
+
try {
|
|
1499
|
+
fs.writeFileSync(descriptor, `${JSON.stringify(bundle, null, 2)}\n`);
|
|
1500
|
+
fs.fsyncSync(descriptor);
|
|
1501
|
+
} finally {
|
|
1502
|
+
fs.closeSync(descriptor);
|
|
1503
|
+
}
|
|
1504
|
+
const result = {
|
|
1505
|
+
ok: true,
|
|
1506
|
+
path: path.relative(CWD, output).split(path.sep).join('/'),
|
|
1507
|
+
runId: bundle.runId,
|
|
1508
|
+
audience: bundle.audience,
|
|
1509
|
+
bundleHash: bundle.bundleHash
|
|
1510
|
+
};
|
|
1511
|
+
console.log(json ? JSON.stringify(result) : `Created ${result.path}\nBundle hash: ${result.bundleHash}`);
|
|
1512
|
+
return;
|
|
1513
|
+
}
|
|
1514
|
+
const file = process.argv[4];
|
|
1515
|
+
if (!file || file.startsWith('-')) throw new Error(`handoff ${action} requires a file`);
|
|
1516
|
+
const bundle = readHandoff(CWD, file);
|
|
1517
|
+
const verification = verifyHandoff(bundle);
|
|
1518
|
+
if (action === 'inspect') {
|
|
1519
|
+
console.log(JSON.stringify({ ok: true, ...verification }, null, json ? 0 : 2));
|
|
1520
|
+
} else if (action === 'brief') {
|
|
1521
|
+
console.log(handoffBrief(bundle));
|
|
1522
|
+
} else {
|
|
1523
|
+
throw new Error('Unknown handoff action. Use create|inspect|brief');
|
|
1524
|
+
}
|
|
1525
|
+
} catch (err) {
|
|
1526
|
+
if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'HANDOFF_FAILED', error: err.message }));
|
|
1527
|
+
else log.error(err.message);
|
|
1528
|
+
process.exitCode = 1;
|
|
1529
|
+
}
|
|
1530
|
+
}
|
|
1531
|
+
|
|
1532
|
+
function openStudio(url) {
|
|
1533
|
+
const command = process.platform === 'darwin'
|
|
1534
|
+
? ['open', [url]]
|
|
1535
|
+
: process.platform === 'win32'
|
|
1536
|
+
? ['cmd', ['/c', 'start', '', url]]
|
|
1537
|
+
: ['xdg-open', [url]];
|
|
1538
|
+
const child = spawn(command[0], command[1], { detached: true, stdio: 'ignore' });
|
|
1539
|
+
child.on('error', () => {});
|
|
1540
|
+
child.unref();
|
|
1541
|
+
}
|
|
1542
|
+
|
|
1543
|
+
function handleStudio() {
|
|
1544
|
+
const requestedPort = argValue('--port');
|
|
1545
|
+
const port = requestedPort == null ? 4317 : Number(requestedPort);
|
|
1546
|
+
if (!Number.isSafeInteger(port) || port < 0 || port > 65535) {
|
|
1547
|
+
log.error('--port must be an integer from 0 to 65535');
|
|
1548
|
+
process.exitCode = 1;
|
|
1549
|
+
return;
|
|
1550
|
+
}
|
|
1551
|
+
const { server, token } = createStudioServer(CWD);
|
|
1552
|
+
server.on('error', (error) => {
|
|
1553
|
+
log.error(`Unable to start Studio: ${error.message}`);
|
|
1554
|
+
process.exitCode = 1;
|
|
1555
|
+
});
|
|
1556
|
+
server.listen(port, '127.0.0.1', () => {
|
|
1557
|
+
const address = server.address();
|
|
1558
|
+
const url = `http://127.0.0.1:${address.port}/?token=${token}`;
|
|
1559
|
+
log.success('✓ Workflow Studio is running locally');
|
|
1560
|
+
console.log(url);
|
|
1561
|
+
console.log('Press Ctrl+C to stop. The session token is valid only for this process.');
|
|
1562
|
+
if (!process.argv.includes('--no-open')) openStudio(url);
|
|
1563
|
+
});
|
|
1564
|
+
}
|
|
1565
|
+
|
|
1453
1566
|
// Help Menu
|
|
1454
1567
|
function printHelp() {
|
|
1455
1568
|
console.log(`
|
|
@@ -1479,6 +1592,7 @@ Commands:
|
|
|
1479
1592
|
start <id> [--run <id>] [--json]
|
|
1480
1593
|
complete <id> [--artifact <repository-relative-path>] [--json]
|
|
1481
1594
|
fail <id> [--reason <text>] [--json]
|
|
1595
|
+
activity <id> --message <safe progress text> [--json]
|
|
1482
1596
|
retry <id> [--json]
|
|
1483
1597
|
approve <id> --yes [--by <name>] [--json]
|
|
1484
1598
|
policy Inspect or update fail-closed runtime controls
|
|
@@ -1516,6 +1630,12 @@ Commands:
|
|
|
1516
1630
|
show <id> [--json]
|
|
1517
1631
|
validate <id> [--mode <mode>] [--json]
|
|
1518
1632
|
explain | graph | simulate <id> [--mode <mode>] [--json]
|
|
1633
|
+
studio Open the localhost-only visual workflow editor
|
|
1634
|
+
[--port <0-65535>] [--no-open]
|
|
1635
|
+
handoff Export or verify a redacted, integrity-bound knowledge transfer
|
|
1636
|
+
create [--run <id>] [--audience developer|agent|auditor]
|
|
1637
|
+
[--output <repository-relative-file>|-] [--json]
|
|
1638
|
+
inspect | brief <repository-relative-file> [--json]
|
|
1519
1639
|
sync-hosts Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
1520
1640
|
(only hosts that already exist; DOT skills only if already installed)
|
|
1521
1641
|
--dry-run print the plan without writing
|
|
@@ -1583,6 +1703,12 @@ switch (command) {
|
|
|
1583
1703
|
case 'recipe':
|
|
1584
1704
|
handleRecipe();
|
|
1585
1705
|
break;
|
|
1706
|
+
case 'studio':
|
|
1707
|
+
handleStudio();
|
|
1708
|
+
break;
|
|
1709
|
+
case 'handoff':
|
|
1710
|
+
handleHandoff();
|
|
1711
|
+
break;
|
|
1586
1712
|
case 'sync-hosts':
|
|
1587
1713
|
handleSyncHosts();
|
|
1588
1714
|
break;
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Local Workflow Studio
|
|
2
|
+
|
|
3
|
+
Workflow Studio is a localhost-only visual control plane for declarative recipes and recipe-bound runs. It does not execute models, shell commands, or arbitrary node code. The existing recipe compiler and controlled workflow runtime remain the source of truth.
|
|
4
|
+
|
|
5
|
+
## Start
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
ai-engineering-loop studio
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
The CLI binds only to `127.0.0.1`, creates a random process-local session token, and opens a tokenized bootstrap URL. The server exchanges that URL for an `HttpOnly; SameSite=Strict` cookie and removes the token from the address bar. Use `--no-open` when you want to copy the printed URL manually, or `--port 0` to let the operating system choose an available port.
|
|
12
|
+
|
|
13
|
+
The server rejects non-local `Host` headers. Static assets are bundled in the npm package; there are no CDNs, analytics, remote fonts, or browser-side model calls. Responses use a restrictive Content Security Policy and are not cached.
|
|
14
|
+
|
|
15
|
+
## Authoring model
|
|
16
|
+
|
|
17
|
+
The canvas loads built-in and project recipes through the same APIs as the CLI:
|
|
18
|
+
|
|
19
|
+
1. Select a recipe.
|
|
20
|
+
2. Fork a protected built-in by changing its ID.
|
|
21
|
+
3. Add or edit allowlisted node types.
|
|
22
|
+
4. Connect nodes with dependency IDs.
|
|
23
|
+
5. Review graph validation and hashes for every compatible mode.
|
|
24
|
+
6. Install only after explicit confirmation.
|
|
25
|
+
|
|
26
|
+
Installation writes a private temporary candidate, invokes the existing atomic installer, and removes the candidate. Built-ins cannot be overwritten. Replacing a project recipe still requires the version policy enforced by `recipe install --replace`.
|
|
27
|
+
|
|
28
|
+
## Live execution
|
|
29
|
+
|
|
30
|
+
For a recipe-bound current run, Studio polls a small live snapshot rather than reloading the recipe catalog. It displays:
|
|
31
|
+
|
|
32
|
+
- current node states and the append-only event stream;
|
|
33
|
+
- an animated connector leaving the running node;
|
|
34
|
+
- provider-recorded run token spend and configured limit;
|
|
35
|
+
- explicit approval and retry controls;
|
|
36
|
+
- a short redacted activity message reported by the host:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
ai-engineering-loop node activity <node-id> \
|
|
40
|
+
--message "Comparing the failing test with the implementation"
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Activity can only be attached to a `RUNNING` node. It is capped at 240 printable characters, secret-redacted before persistence, and added to the integrity-bound workflow event chain.
|
|
44
|
+
|
|
45
|
+
## Decision memory
|
|
46
|
+
|
|
47
|
+
Studio can record a concise decision and rationale against the current run. Decision memory is private runtime data under the run directory, is bounded to 100 entries, and is redacted before persistence. It becomes part of exported handoffs so the next developer or agent receives the “why,” not only the final state.
|
|
48
|
+
|
|
49
|
+
Do not use decision memory as a credential store or as a replacement for a repository ADR when a durable architectural decision belongs in version control.
|
|
50
|
+
|
|
51
|
+
## Knowledge handoff
|
|
52
|
+
|
|
53
|
+
The top bar provides two forms:
|
|
54
|
+
|
|
55
|
+
- **Copy Brief** creates a human-readable developer summary.
|
|
56
|
+
- **Export Handoff** downloads a machine-readable `.ael-handoff.json` bundle for another agent.
|
|
57
|
+
|
|
58
|
+
The bundle contains objective, workflow state, artifact descriptors, decisions, transitions, and ready next actions. It deliberately excludes source contents. Strings pass through secret and home-path redaction, and the complete canonical manifest is bound to `bundleHash`.
|
|
59
|
+
|
|
60
|
+
Verify a received bundle before trusting it:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
ai-engineering-loop handoff inspect run-id.ael-handoff.json
|
|
64
|
+
ai-engineering-loop handoff brief run-id.ael-handoff.json
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Inspection accepts only regular files smaller than 1 MiB inside the repository, rejects symlinks and path escapes, and fails if any field no longer matches the bundle hash.
|
|
68
|
+
|
|
69
|
+
## Trust boundary
|
|
70
|
+
|
|
71
|
+
Studio improves authoring and observability; it does not weaken runtime gates:
|
|
72
|
+
|
|
73
|
+
- graph validation does not imply execution permission;
|
|
74
|
+
- command nodes remain disabled;
|
|
75
|
+
- approvals remain explicit state transitions;
|
|
76
|
+
- token data comes only from the provider-recorded usage ledger;
|
|
77
|
+
- handoff integrity proves the bundle has not changed after export, not that every original claim was true.
|
package/lib/doctor.js
CHANGED
|
@@ -30,7 +30,8 @@ const REQUIRED_SCHEMAS = [
|
|
|
30
30
|
'node-definition.schema.json',
|
|
31
31
|
'compiled-plan.schema.json',
|
|
32
32
|
'workflow-state.schema.json',
|
|
33
|
-
'workflow-event.schema.json'
|
|
33
|
+
'workflow-event.schema.json',
|
|
34
|
+
'handoff.schema.json'
|
|
34
35
|
];
|
|
35
36
|
|
|
36
37
|
function check(id, passed, detail) {
|
|
@@ -97,7 +98,7 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
|
|
|
97
98
|
}
|
|
98
99
|
|
|
99
100
|
const packageFiles = new Set(pkg.files || []);
|
|
100
|
-
const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/'];
|
|
101
|
+
const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/', 'studio/'];
|
|
101
102
|
const missingPackageEntries = requiredPackageEntries.filter((entry) => !packageFiles.has(entry));
|
|
102
103
|
checks.push(check(
|
|
103
104
|
'package-assets',
|
package/lib/handoff.js
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
const { canonicalJson, sha256 } = require('./recipe.js');
|
|
6
|
+
const { atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
|
|
7
|
+
const { redactSecrets } = require('./safe-context.js');
|
|
8
|
+
const { workflowStatus } = require('./workflow-runtime.js');
|
|
9
|
+
|
|
10
|
+
const AUDIENCES = new Set(['developer', 'agent', 'auditor']);
|
|
11
|
+
const MAX_BUNDLE_BYTES = 1024 * 1024;
|
|
12
|
+
|
|
13
|
+
function handoffError(message, code = 'HANDOFF_FAILED') {
|
|
14
|
+
const error = new Error(message);
|
|
15
|
+
error.code = code;
|
|
16
|
+
return error;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function resolveRun(rootDir, runId) {
|
|
20
|
+
const run = runId ? loadRun(rootDir, runId) : getCurrentRun(rootDir);
|
|
21
|
+
if (!run) throw handoffError('No current run. Pass --run <id>.', 'NO_CURRENT_RUN');
|
|
22
|
+
return run;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function redactValue(value, categories) {
|
|
26
|
+
if (typeof value === 'string') {
|
|
27
|
+
const result = redactSecrets(value);
|
|
28
|
+
result.categories.forEach((category) => categories.add(category));
|
|
29
|
+
const redacted = result.text
|
|
30
|
+
.replace(/(?:file:\/\/)?\/?Users\/[A-Za-z0-9._-]+/g, '[REDACTED HOME]')
|
|
31
|
+
.replace(/\b[A-Z]:\\Users\\[^\\\s]+/gi, '[REDACTED HOME]');
|
|
32
|
+
if (redacted !== result.text) categories.add('HOME_PATH');
|
|
33
|
+
return redacted;
|
|
34
|
+
}
|
|
35
|
+
if (Array.isArray(value)) return value.map((item) => redactValue(item, categories));
|
|
36
|
+
if (value && typeof value === 'object') {
|
|
37
|
+
return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactValue(item, categories)]));
|
|
38
|
+
}
|
|
39
|
+
return value;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function loadOptionalJson(filePath) {
|
|
43
|
+
if (!fs.existsSync(filePath)) return null;
|
|
44
|
+
const stat = fs.lstatSync(filePath);
|
|
45
|
+
if (stat.isSymbolicLink() || !stat.isFile()) throw handoffError('Optional handoff input must be a regular file');
|
|
46
|
+
try {
|
|
47
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
48
|
+
} catch (cause) {
|
|
49
|
+
throw handoffError(`Optional handoff input is invalid JSON: ${cause.message}`, 'INVALID_HANDOFF_INPUT');
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function recordDecision(rootDir, {
|
|
54
|
+
runId,
|
|
55
|
+
summary,
|
|
56
|
+
rationale,
|
|
57
|
+
consequences = [],
|
|
58
|
+
now = new Date()
|
|
59
|
+
} = {}) {
|
|
60
|
+
const run = resolveRun(rootDir, runId);
|
|
61
|
+
if (typeof summary !== 'string' || !summary.trim() || summary.trim().length > 160) {
|
|
62
|
+
throw handoffError('Decision summary must be 1-160 characters', 'INVALID_DECISION');
|
|
63
|
+
}
|
|
64
|
+
if (typeof rationale !== 'string' || !rationale.trim() || rationale.trim().length > 1000) {
|
|
65
|
+
throw handoffError('Decision rationale must be 1-1000 characters', 'INVALID_DECISION');
|
|
66
|
+
}
|
|
67
|
+
if (!Array.isArray(consequences) || consequences.length > 20 || consequences.some(
|
|
68
|
+
(item) => typeof item !== 'string' || !item.trim() || item.length > 240
|
|
69
|
+
)) {
|
|
70
|
+
throw handoffError('Decision consequences must contain at most 20 short strings', 'INVALID_DECISION');
|
|
71
|
+
}
|
|
72
|
+
const filePath = path.join(runsDir(rootDir), run.runId, 'decisions.json');
|
|
73
|
+
const decisions = loadOptionalJson(filePath) || [];
|
|
74
|
+
if (!Array.isArray(decisions) || decisions.length >= 100) {
|
|
75
|
+
throw handoffError('Decision memory must be an array with fewer than 100 entries', 'INVALID_DECISION');
|
|
76
|
+
}
|
|
77
|
+
const categories = new Set();
|
|
78
|
+
const entry = redactValue({
|
|
79
|
+
id: `decision-${String(decisions.length + 1).padStart(3, '0')}`,
|
|
80
|
+
summary: summary.trim(),
|
|
81
|
+
rationale: rationale.trim(),
|
|
82
|
+
consequences: consequences.map((item) => item.trim()),
|
|
83
|
+
recordedAt: now.toISOString()
|
|
84
|
+
}, categories);
|
|
85
|
+
atomicWriteJson(filePath, [...decisions, entry]);
|
|
86
|
+
return { runId: run.runId, decision: entry, redactionCategories: [...categories].sort() };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function createHandoff(rootDir, { runId, audience = 'developer', now = new Date() } = {}) {
|
|
90
|
+
if (!AUDIENCES.has(audience)) throw handoffError(`Invalid audience: ${audience}`);
|
|
91
|
+
const run = resolveRun(rootDir, runId);
|
|
92
|
+
const directory = path.join(runsDir(rootDir), run.runId);
|
|
93
|
+
const workflow = run.workflow ? workflowStatus(rootDir, { runId: run.runId }) : null;
|
|
94
|
+
const decisions = loadOptionalJson(path.join(directory, 'decisions.json')) || [];
|
|
95
|
+
if (!Array.isArray(decisions)) throw handoffError('Decision memory must be an array', 'INVALID_HANDOFF_INPUT');
|
|
96
|
+
const categories = new Set();
|
|
97
|
+
const content = redactValue({
|
|
98
|
+
objective: run.task,
|
|
99
|
+
state: run.state,
|
|
100
|
+
mode: run.mode,
|
|
101
|
+
iteration: run.iteration,
|
|
102
|
+
recipe: run.workflow || null,
|
|
103
|
+
nodes: workflow ? workflow.plan.nodes.map((node) => ({
|
|
104
|
+
id: node.id,
|
|
105
|
+
type: node.type,
|
|
106
|
+
status: workflow.state.nodes[node.id].status,
|
|
107
|
+
attempts: workflow.state.nodes[node.id].attempts,
|
|
108
|
+
reason: workflow.state.nodes[node.id].reason || null,
|
|
109
|
+
activity: workflow.state.nodes[node.id].activity || null
|
|
110
|
+
})) : [],
|
|
111
|
+
artifacts: run.artifacts,
|
|
112
|
+
decisions,
|
|
113
|
+
transitions: run.history,
|
|
114
|
+
nextActions: workflow
|
|
115
|
+
? workflow.plan.nodes.filter((node) => workflow.state.nodes[node.id].status === 'READY').map((node) => node.id)
|
|
116
|
+
: []
|
|
117
|
+
}, categories);
|
|
118
|
+
const material = {
|
|
119
|
+
schemaVersion: 1,
|
|
120
|
+
audience,
|
|
121
|
+
runId: run.runId,
|
|
122
|
+
generatedAt: now.toISOString(),
|
|
123
|
+
graphHash: run.workflow?.graphHash || null,
|
|
124
|
+
finalState: run.state,
|
|
125
|
+
redacted: true,
|
|
126
|
+
sourceIncluded: false,
|
|
127
|
+
redactionCategories: [...categories].sort(),
|
|
128
|
+
content
|
|
129
|
+
};
|
|
130
|
+
return { ...material, bundleHash: sha256(material) };
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
function handoffBrief(bundle) {
|
|
134
|
+
const lines = [
|
|
135
|
+
'# Engineering Handoff',
|
|
136
|
+
'',
|
|
137
|
+
`Run: ${bundle.runId}`,
|
|
138
|
+
`State: ${bundle.finalState}`,
|
|
139
|
+
`Mode: ${bundle.content.mode}`,
|
|
140
|
+
`Graph: ${bundle.graphHash || 'legacy'}`,
|
|
141
|
+
'',
|
|
142
|
+
'## Objective',
|
|
143
|
+
bundle.content.objective || 'Not recorded.',
|
|
144
|
+
'',
|
|
145
|
+
'## Workflow',
|
|
146
|
+
...bundle.content.nodes.map((node) => `- ${node.id}: ${node.status}${node.reason ? ` — ${node.reason}` : ''}`),
|
|
147
|
+
'',
|
|
148
|
+
'## Decisions',
|
|
149
|
+
...(bundle.content.decisions.length ? bundle.content.decisions.map((decision) => `- ${decision.decision || decision.summary || JSON.stringify(decision)}`) : ['- None recorded.']),
|
|
150
|
+
'',
|
|
151
|
+
'## Evidence',
|
|
152
|
+
...Object.entries(bundle.content.artifacts).map(([name, artifact]) => (
|
|
153
|
+
`- ${name}: ${artifact && typeof artifact === 'object' ? artifact.sha256 || 'recorded' : 'recorded'}`
|
|
154
|
+
)),
|
|
155
|
+
'',
|
|
156
|
+
'## Next actions',
|
|
157
|
+
...(bundle.content.nextActions.length ? bundle.content.nextActions.map((action) => `- ${action}`) : ['- No READY nodes.'])
|
|
158
|
+
];
|
|
159
|
+
return lines.join('\n');
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
function verifyHandoff(bundle) {
|
|
163
|
+
if (!bundle || bundle.schemaVersion !== 1 || !AUDIENCES.has(bundle.audience)) {
|
|
164
|
+
throw handoffError('Handoff manifest is invalid', 'INVALID_HANDOFF');
|
|
165
|
+
}
|
|
166
|
+
const { bundleHash, ...material } = bundle;
|
|
167
|
+
if (bundleHash !== sha256(material)) throw handoffError('Handoff bundle hash does not match', 'HANDOFF_TAMPERED');
|
|
168
|
+
return {
|
|
169
|
+
valid: true,
|
|
170
|
+
runId: bundle.runId,
|
|
171
|
+
audience: bundle.audience,
|
|
172
|
+
bundleHash,
|
|
173
|
+
canonicalBytes: Buffer.byteLength(canonicalJson(bundle))
|
|
174
|
+
};
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
function readHandoff(rootDir, file) {
|
|
178
|
+
const absolute = path.resolve(rootDir, file);
|
|
179
|
+
const relative = path.relative(rootDir, absolute);
|
|
180
|
+
if (relative === '..' || relative.startsWith(`..${path.sep}`)) throw handoffError('Handoff path escapes repository');
|
|
181
|
+
let stat;
|
|
182
|
+
try {
|
|
183
|
+
stat = fs.lstatSync(absolute);
|
|
184
|
+
} catch (cause) {
|
|
185
|
+
throw handoffError(`Unable to inspect handoff: ${cause.message}`, 'INVALID_HANDOFF');
|
|
186
|
+
}
|
|
187
|
+
if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_BUNDLE_BYTES) {
|
|
188
|
+
throw handoffError('Handoff must be a regular file under 1 MiB');
|
|
189
|
+
}
|
|
190
|
+
const realRoot = fs.realpathSync(rootDir);
|
|
191
|
+
const realFile = fs.realpathSync(absolute);
|
|
192
|
+
if (realFile !== realRoot && !realFile.startsWith(`${realRoot}${path.sep}`)) {
|
|
193
|
+
throw handoffError('Handoff path escapes repository through a symlink');
|
|
194
|
+
}
|
|
195
|
+
try {
|
|
196
|
+
return JSON.parse(fs.readFileSync(absolute, 'utf8'));
|
|
197
|
+
} catch (cause) {
|
|
198
|
+
throw handoffError(`Handoff is invalid JSON: ${cause.message}`, 'INVALID_HANDOFF');
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
module.exports = {
|
|
203
|
+
AUDIENCES,
|
|
204
|
+
createHandoff,
|
|
205
|
+
handoffBrief,
|
|
206
|
+
recordDecision,
|
|
207
|
+
verifyHandoff,
|
|
208
|
+
readHandoff
|
|
209
|
+
};
|