Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
a5312c2
checkpoint A fixes
iRuSu67 Oct 28, 2026
b88ec30
fix(ci): enforce explicit build order, sync package-lock, pin runner …
iRuSu67 Oct 29, 2026
dddc844
feat(eval): harden offline rate limiting, staged evaluation, and prov…
iRuSu67 Oct 29, 2026
3f1a8f5
fix(eval): offline harness hardening, typed provider errors, structur…
iRuSu67 Oct 30, 2026
18256e7
feat(eval): switch to lightweight model gemini-3.5-flash-lite, isolat…
iRuSu67 Oct 30, 2026
f7a9817
feat(release): complete live evaluation on gemini-3.5-flash-lite, fin…
iRuSu67 Oct 30, 2026
65a83f2
feat(release): finalize v0.1.0 release prep, AST loop exit fix, live …
iRuSu67 Oct 30, 2026
b6d5815
docs: honest reporting pass, cache accounting caveats, task 2a analys…
iRuSu67 Oct 30, 2026
c1bfd1f
fix(web): pin @aether-flow/core dependency to 0.1.0
iRuSu67 Oct 30, 2026
89a7862
fix(examples): update @aether-flow/core dependency to 0.1.0 across al…
iRuSu67 Oct 30, 2026
aa0a121
fix(ci): align example dependencies and lockfile to 0.1.0
iRuSu67 Oct 30, 2026
99dca42
build: untrack compiled artifacts from src trees and ignore pycache
iRuSu67 Oct 30, 2026
a23fd1d
docs: archive internal review files outside repository
iRuSu67 Oct 30, 2026
afdbacb
refactor(examples): isolate unverified showcases to experimental/exam…
iRuSu67 Oct 30, 2026
f9305f3
docs: add experimental banners to speculative docs and update README …
iRuSu67 Oct 30, 2026
6471293
fix(pkg): align web, example 02, and lockfile to 0.1.0
iRuSu67 Oct 30, 2026
15d3d27
test: record verified raw output from clean clone test and mutation runs
iRuSu67 Oct 30, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 41 additions & 14 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,36 +2,63 @@ name: AetherFlow CI

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
workflow_dispatch:

jobs:
build-and-test:
runs-on: ubuntu-latest
verify:
name: Verify & Test (Node ${{ matrix.node-version }})
runs-on: ubuntu-24.04

strategy:
fail-fast: false
matrix:
node-version: [ 20.x, 22.x ]
node-version: [ 22.x, 24.x ]

env:
NODE_OPTIONS: "--unhandled-rejections=strict --trace-warnings"

steps:
- name: Checkout repository
uses: actions/checkout@v4
uses: actions/checkout@v7

- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
- name: Setup Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v7
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'

- name: Install Monorepo Dependencies
run: npm install
- name: Install dependencies
run: npm ci

- name: Build Core Microkernel & CLI
- name: Build Core & CLI Packages
run: npm run build

- name: Execute Test Suite
- name: Typecheck
run: npm run typecheck

- name: Lint
run: npm run lint

- name: Security Audit (Fail on High/Critical)
run: npm audit --audit-level=high

- name: Pre-pull Pinned Docker Image
run: docker pull node:lts-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53

- name: Run Test Suite (Subprocess & Docker Modes)
run: npm test

- name: Run End-to-End Quickstart Demo
run: npm run demo
- name: Run Mutation Defense Verification (Subprocess & Docker)
run: |
node scripts/verify_mutations.js --mode=docker
node scripts/verify_mutations.js --mode=subprocess

- name: Upload Mutation Defense Verification Logs
if: always()
uses: actions/upload-artifact@v4
with:
name: mutation-logs-node-${{ matrix.node-version }}
path: |
mutation-verification-*.log
*.log
29 changes: 25 additions & 4 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,25 @@ node_modules/

# Build Outputs
dist/
**/dist/
build/
out/
.next/

# Compiled files in source trees
packages/*/src/**/*.js
packages/*/src/**/*.js.map
packages/*/src/**/*.d.ts
packages/*/src/**/*.d.ts.map

# Python Cache
__pycache__/
*.py[cod]
*$py.class

# Review & Work Files
REVIEW*.md

# Logs & Debugging
npm-debug.log*
yarn-debug.log*
Expand All @@ -17,10 +32,14 @@ yarn-error.log*

# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
.env.*
*.env
gemini.env
.eval_cache/
.eval_cache*/
.eval_daily_budget*.json
eval_checkpoint.json
*eval_last_provider_error.json

# OS & Editor
.DS_Store
Expand All @@ -40,3 +59,5 @@ coverage/
# Turbopack / Cache
.turbo
.cache
.eval_cache/
eval_checkpoint.json
31 changes: 31 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Changelog

All notable changes to the AetherFlow project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.0] - 2026-10-30

### Scope
Initial verified sandbox and dynamic tool-synthesis release for Large Language Model (LLM) agents.

### Added
- **Multi-Layer Sandbox Architecture**:
- Isolated Docker container runner (`docker` mode) with read-only root filesystems, dropped Linux capabilities (`CAP_DROP=ALL`), non-root execution (`uid=1000`), no network access (`--network none`), memory caps (64MB), and strict process limits (`pids-limit=64`).
- AST containment layer (`ASTVerifier`) blocking prototype constructor evasion, dynamic import, `eval`, `new Function`, template string constructor lookups, and static infinite loops.
- Fail-closed security contracts: refuses insecure subprocess execution unless explicitly opted into via `unsafeDevMode`.
- **Dynamic Tool-Synthesis Loop**:
- On-the-fly code synthesis for arbitrary user-specified computational goals.
- Verification loop with compile/runtime error feedback and self-healing retries.
- Persistent family-indexed and description-similarity tool library (`ToolLibrary`) for runtime tool reuse.
- **Evaluation Benchmark Suite (`@aether-flow/eval`)**:
- 15 deterministic benchmark tasks across 5 algorithmic families (Markdown Table parsing, Levenshtein sequence alignment, Dijkstra shortest path with turn penalties, CSV 2D aggregation pivot, and 0/1 Dual Knapsack optimization).
- 5 domain checker test harnesses validating solution optimality and constraint satisfaction.
- Evaluation across 5 experimental conditions: Condition A (zero-shot direct generation), Condition B (static 5-tool palette), Condition C0 (single-shot synthesis without feedback), Condition C (synthesis with sandbox/AST feedback loop), and Condition D (dynamic tool synthesis with runtime reuse).
- Multi-model profile registry with configurable rate limits, per-model daily quota tracking, and automatic request pacing.
- Quota isolation keyed to Pacific calendar day (America/Los_Angeles) and user-facing Casablanca timezone conversion.
- **Developer Experience & Tooling**:
- Monorepo structure with explicit build dependency ordering (`@aether-flow/core`, `@aether-flow/cli`, `@aether-flow/eval`).
- GitHub Actions CI pipeline running on Ubuntu 24.04 LTS matrix (Node 20 and Node 22).
- Interactive self-healing synthesis demonstration (`npm run demo`).
69 changes: 44 additions & 25 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,56 @@
# Contributing to AetherFlow

We welcome contributions from systems architects, AI engineers, and open-source enthusiasts!
We welcome contributions from systems architects, security researchers, and AI engineers!

## Architectural Principles

1. **Fail-Closed Security**: Default execution must always enforce the strongest isolation boundary (`mode: 'docker'`). Subprocess execution without Docker is strictly an insecure development mode requiring explicit opt-in (`unsafeDevMode: true`).
2. **Defense-in-Depth**: Never rely on a single layer of containment. Defenses must include static AST inspection, isolated VM realms with stripped host prototypes, and containerized OS kernel sandboxing (`--network none`, `--read-only`, non-root user, capability dropping, cgroups limits).
3. **No Unverified Claims**: Any performance, security, or benchmark claim must be backed by a deterministic test or reproducible benchmark script.
4. **Scope Integrity**: v0.1 scope is frozen to the verified sandbox and dynamic tool synthesis loop. Experimental subsystems remain quarantined in `packages/core/src/experimental/`.

---

## Development Setup

1. **Clone the repository**:
```bash
git clone https://github.com/iRuSu67/aether-flow.git
cd aether-flow
```
### 1. Prerequisites
- **Node.js**: $\ge$ 20.0.0
- **Docker**: Docker Engine or Docker Desktop (required for default sandbox execution)

### 2. Clean Installation & Build
```bash
git clone https://github.com/iRuSu67/aether-flow.git
cd aether-flow
npm ci
npm run build
```

### 3. Verification Commands
```bash
# Typecheck across monorepo
npm run typecheck

# Lint across monorepo
npm run lint

# Run the 57 automated unit and security tests
npm test

2. **Install dependencies**:
```bash
npm install
```
# Run Docker mutation defense verification (7 layers)
node scripts/verify_mutations.js --mode=docker

3. **Build all packages**:
```bash
npm run build
```
# Run Subprocess mutation defense verification (6 layers)
node scripts/verify_mutations.js --mode=subprocess

4. **Run the test suite**:
```bash
npm test
```
# Run the interactive quickstart demo
npm run demo
```

5. **Start the visual canvas**:
```bash
npm run start:canvas
```
---

## Pull Request Guidelines
- Follow TypeScript strict mode conventions.
- Ensure all unit tests pass with `npm test`.
- Add tests for new agent behaviors or sandbox extensions.
- Keep commits concise and meaningful (`feat:`, `fix:`, `docs:`, `perf:`).
- Ensure all unit tests pass cleanly with `npm test`.
- Add tests for new sandbox boundaries, attack vectors, or synthesizer behaviors.
- Ensure any modifications to sandbox containment are tested against `scripts/verify_mutations.js`.
- Keep commit messages concise, imperative, and structured (`feat:`, `fix:`, `test:`, `docs:`, `perf:`).
Loading
Loading