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 CHANGED
@@ -5,7 +5,7 @@
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
6
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
7
7
  [![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
8
- [![Release](https://img.shields.io/badge/release-v1.5.0-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
8
+ [![Release](https://img.shields.io/badge/release-v1.6.0-purple.svg)](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 exposes catalog/inspect/diff JSON for AI agents and a future UI. The host-neutral agent protocol is in [`agents/recipe-builder.md`](agents/recipe-builder.md).
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
- const VERSION = '1.5.0';
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.5.0',
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
+ };
@@ -8,6 +8,7 @@ const PRIVATE_RUNTIME_PATTERNS = Object.freeze([
8
8
  'usage/',
9
9
  'worktrees/',
10
10
  'locks/',
11
+ 'drafts/',
11
12
  'recipes/.history/',
12
13
  'tasks/current.diff',
13
14
  'tasks/*.log'