feat: HyperAgent v0.1.0 — AI agent with sandboxed JS execution

Hyperlight micro-VM sandboxed JavaScript agent powered by the GitHub Copilot SDK.

- Sandboxed ES2023 runtime in Hyperlight micro-VMs (KVM/MSHV/WHP)
- Plugin system with security auditing (fs-read, fs-write, fetch)
- Builtin modules: PPTX generation, ZIP, HTML, Markdown, image processing
- Skills and patterns framework for task-specific guidance
- Native Rust code validator via NAPI addon
- CLI with profiles, skills, auto-approve, debug/transcript logging
- Docker support with KVM passthrough
- Standalone binary builds via pkg

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

.claude/CLAUDE.md

@@ -0,0 +1,69 @@
+# Hyperagent - Claude Code Instructions
+
+## Generated Files - DO NOT EDIT DIRECTLY
+
+These files are auto-generated. Editing them directly will cause test failures.
+
+### builtin-modules/*.js and *.d.ts
+
+Generated from `builtin-modules/src/*.ts` by TypeScript compiler.
+
+- **To modify**: Edit source in `builtin-modules/src/*.ts`
+- **To regenerate**: Run `npm run build:modules`
+- **Enforced by**: `tests/dts-sync.test.ts` compares compiled output to committed files
+
+### src/code-validator/guest/index.d.ts
+
+Generated from Rust source. Do not edit.
+
+## Plugins - TypeScript Only
+
+Plugins MUST be TypeScript files. The test suite enforces this.
+
+- **Plugin source**: `plugins/<name>/index.ts`
+- **Shared utilities**: `plugins/shared/*.ts`
+- **Test fixtures**: `tests/fixtures/<name>/index.ts`
+- **Enforced by**: `tests/plugin-source.test.ts` fails if `.js` files exist
+
+### Current plugins:
+- `plugins/fs-read/index.ts` - Read-only filesystem access
+- `plugins/fs-write/index.ts` - Write-only filesystem access
+- `plugins/fetch/index.ts` - Secure HTTPS fetching
+
+## Build & Test
+
+Use `just` commands for development (preferred) or npm scripts:
+
+```bash
+# ── Development ──
+just setup         # First-time setup: clone deps, build native addons, npm install
+just build         # Rebuild native addons and install deps
+just start         # Run agent (tsx src/agent/index.ts)
+
+# ── Testing ──
+just test          # Run TypeScript tests
+just test-rust     # Run Rust tests (analysis-guest)
+just test-all      # Run all tests (TS + Rust)
+
+# ── Formatting ──
+just fmt           # Format TypeScript/JavaScript
+just fmt-rust      # Format Rust (analysis-guest)
+just fmt-runtime   # Format Rust (sandbox/runtime)
+just fmt-all       # Format all code
+
+# ── Linting ──
+just lint          # TypeScript: fmt-check + typecheck
+just lint-rust     # Rust: clippy + fmt-check (analysis-guest)
+just lint-runtime  # Rust: clippy + fmt-check (runtime)
+just lint-all      # All lints
+
+# ── Quality Gate ──
+just check         # Full quality gate: lint-all + test-all
+
+# ── npm equivalents ──
+npm run start      # Run agent (tsx src/agent/index.ts)
+npm run test       # Run TypeScript tests
+npm run typecheck  # TypeScript type checking
+npm run fmt        # Format with Prettier
+npm run check      # fmt:check + typecheck + test
+```

.dockerignore

@@ -0,0 +1,21 @@
+# Root node_modules (dev deps, huge)
+node_modules/
+
+# Git
+.git/
+**/.git/
+
+# Logs and docs
+*.log
+working_docs/
+working-docs/
+tests/
+.claude/
+
+# Rust build artifacts (huge - 9GB+)
+deps/hyperlight-js/target/
+src/hyperlight-analysis-guest/target/
+**/target/
+
+# KEEP dist/lib/node_modules (bundled @github/copilot SDK)
+# Only exclude root node_modules

.github/copilot-instructions.md

@@ -0,0 +1,97 @@
+# Hyperagent — Copilot Instructions
+
+## Project Overview
+
+HyperAgent is an AI agent with a sandboxed JavaScript executor, powered by Hyperlight micro-VMs and the GitHub Copilot SDK. It is a TypeScript + Rust project using ESM modules, strict TypeScript, Vitest for testing, Prettier for formatting, and `just` as the task runner.
+
+**Prerequisites**: Node.js 22+, Rust toolchain, Linux with KVM (hardware virtualisation required for Hyperlight micro-VMs).
+
+## Source Structure
+
+```
+src/
+├── agent/           # CLI agent — REPL, commands, UI (entry: index.ts)
+├── plugin-system/   # Plugin lifecycle (manager.ts, auditor.ts, types.ts, schema-types.ts)
+├── sandbox/         # Sandbox tool (tool.js, tool.d.ts) + Rust runtime
+└── code-validator/  # Rust NAPI addon for code validation
+```
+
+Runtime content at root (not compiled source):
+- `plugins/` — Plugin implementations (fs-read, fs-write, fetch)
+- `builtin-modules/` — Sandbox ES modules (generated from `builtin-modules/src/*.ts`)
+- `skills/` — AI skill definitions (SKILL.md files)
+- `patterns/` — Workflow patterns (PATTERN.md files)
+
+Key config files at root: `package.json`, `tsconfig.json`, `vitest.config.ts`, `Justfile`, `Dockerfile`.
+
+## Build, Test & Validate
+
+Always use these commands in this order for a clean build:
+
+```bash
+just setup         # First-time only: clone deps, build native addons, npm install
+just build         # Rebuild native addons and install deps (run after Rust changes)
+```
+
+Before committing changes, always run the full quality gate:
+
+```bash
+just check         # Runs: lint-all (fmt-check + typecheck + clippy) + test-all (TS + Rust)
+```
+
+Individual commands:
+
+| Command | What it does | When to use |
+|---------|-------------|-------------|
+| `just fmt` | Format TS/JS with Prettier | Before committing |
+| `just lint` | `fmt-check` + `tsc --noEmit` | Quick validation |
+| `just test` | Run Vitest suite (30 test files, ~1700 tests) | After TS changes |
+| `just test-rust` | Run Rust tests in code-validator | After Rust changes |
+| `just test-all` | Both TS + Rust tests | Full validation |
+| `just start` | Run agent with `tsx` (no build needed) | Dev/testing |
+| `just binary-release` | Build standalone binary to `dist/bin/hyperagent` | Release builds |
+
+npm equivalents: `npm run fmt`, `npm run typecheck`, `npm test`, `npm run check`.
+
+**Important**: Always run `just build` (or `just setup` on first run) before running tests — the native Rust addons must be compiled first.
+
+## Generated Files — DO NOT EDIT DIRECTLY
+
+These are auto-generated. Editing them directly causes test failures.
+
+- `builtin-modules/*.js` and `builtin-modules/*.d.ts` — Generated from `builtin-modules/src/*.ts`. Edit the source, then run `npm run build:modules`. Enforced by `tests/dts-sync.test.ts`.
+- `src/code-validator/guest/index.d.ts` — Generated from Rust source.
+- `plugins/*/index.d.ts` — Generated from plugin TypeScript source.
+- `plugins/host-modules.d.ts` — Generated by `scripts/generate-host-modules-dts.ts`.
+
+## Plugins — TypeScript Only
+
+Plugins MUST be TypeScript `.ts` files, not JavaScript. The test suite enforces this (`tests/plugin-source.test.ts`).
+
+- Plugin source: `plugins/<name>/index.ts`
+- Shared utilities: `plugins/shared/*.ts`
+- Test fixtures: `tests/fixtures/<name>/index.ts`
+
+Current plugins:
+- `plugins/fs-read/index.ts` — Read-only filesystem access
+- `plugins/fs-write/index.ts` — Write-only filesystem access
+- `plugins/fetch/index.ts` — Secure HTTPS fetching
+
+## Coding Conventions
+
+- **ESM only** — The project uses `"type": "module"`. All imports use `.js` extensions in specifiers (e.g. `import { foo } from "./bar.js"`).
+- **Strict TypeScript** — `strict: true` in tsconfig. Zero type errors enforced.
+- **No `expect`/`unwrap`/`assert` in production code** — Handle errors properly.
+- **Format with Prettier** before committing — `just fmt` or `npm run fmt`.
+- **All log files write to `~/.hyperagent/logs/`** — Debug, timing, code, tune, transcript, and crash reports all go there.
+- **Disk cache at `~/.hyperagent/fetch-cache/`** — The fetch plugin's persistent HTTP cache.
+- **User data at `~/.hyperagent/`** — Modules, profiles, history, approval store.
+
+## Validation Checklist
+
+Before considering a change complete:
+1. `just fmt` — all code formatted
+2. `just lint` — TypeScript compiles with zero errors
+3. `just test` — all ~1700 tests pass
+4. If Rust code was changed: `just test-rust` passes
+5. No new `expect`/`unwrap`/`assert` in production TS code

.github/instructions/builtin-modules.instructions.md

@@ -0,0 +1,49 @@
+---
+applyTo: "builtin-modules/**"
+---
+
+# Builtin Modules
+
+Modules that run inside the Hyperlight sandbox, available to guest JavaScript via `require("ha:<module>")`.
+
+## Rules
+
+- **Source files** — Edit only `src/*.ts` files
+- **Generated files** — `*.js` and `*.d.ts` in the root are auto-generated
+- **Regenerate** — Run `npm run build:modules` after editing source
+- **Enforced by** — `tests/dts-sync.test.ts` compares compiled output to committed files
+
+## Module Header Format
+
+Each module should have a standard header comment:
+
+```typescript
+// @module <name>
+// @description <description>
+// @created <ISO date>
+// @modified <ISO date>
+// @mutable false
+// @author system
+```
+
+## Current Modules
+
+| Module | Purpose |
+|--------|---------|
+| `base64` | Base64 encode/decode for Uint8Array |
+| `crc32` | CRC32 checksum calculation |
+| `xml-escape` | XML entity escaping |
+| `zip-format` | ZIP file creation |
+| `str-bytes` | String/bytes conversion |
+| `ooxml-core` | Core OOXML utilities |
+| `pptx` | PowerPoint generation |
+| `pptx-charts` | Chart support for PPTX |
+| `pptx-tables` | Table support for PPTX |
+| `shared-state` | Cross-handler state management |
+
+## Workflow
+
+1. Edit `src/<module>.ts`
+2. Run `npm run build:modules`
+3. Commit both source and generated files
+4. Test via `just test`

.github/instructions/patterns.instructions.md

@@ -0,0 +1,51 @@
+---
+applyTo: "patterns/**"
+---
+
+# Patterns
+
+Reusable implementation patterns for common sandbox workflows. Skills reference patterns via their `patterns:` frontmatter.
+
+## Pattern Structure
+
+```
+patterns/<pattern-name>/
+└── PATTERN.md          # Pattern definition with frontmatter + steps
+```
+
+## PATTERN.md Format
+
+```yaml
+---
+name: pattern-name
+description: One-line description
+modules: [module1, module2]    # ha:* modules needed
+plugins: [plugin1]             # host:* plugins needed (optional)
+profiles: [profile-name]       # Resource profiles to apply (optional)
+config:                        # Config overrides (optional)
+  heapMb: 64
+  cpuTimeoutMs: 30000
+---
+
+1. First implementation step
+2. Second implementation step
+3. ...
+```
+
+## Current Patterns
+
+| Pattern | Purpose |
+|---------|---------|
+| `two-handler-pipeline` | Research → Build using ha:shared-state |
+| `fetch-and-process` | Fetch external data and process it |
+| `file-generation` | Generate output files |
+| `image-embed` | Embed images in output |
+| `data-extraction` | Extract structured data |
+| `data-transformation` | Transform data between formats |
+
+## Adding a Pattern
+
+1. Create `patterns/<name>/PATTERN.md`
+2. Add YAML frontmatter with required modules/plugins
+3. Write numbered implementation steps in the body
+4. Reference from skills via `patterns: [<name>]`

.github/instructions/plugins.instructions.md

@@ -0,0 +1,40 @@
+---
+applyTo: "plugins/**"
+---
+
+# Plugins
+
+Plugins extend the Hyperlight sandbox with host functions that guest JavaScript imports via `require("host:<module>")`.
+
+## Rules
+
+- **TypeScript only** — All plugins must be `.ts` files. No `.js` files allowed.
+- **Enforced by** — `tests/plugin-source.test.ts` fails if `.js` files exist
+- Each plugin lives in its own directory with `index.ts` and `plugin.json`
+
+## Structure
+
+```
+plugins/
+├── fs-read/index.ts      # Read-only filesystem (jailed to base directory)
+├── fs-write/index.ts     # Write-only filesystem (jailed to base directory)
+├── fetch/index.ts        # Secure HTTPS fetching
+├── shared/               # Shared utilities (not a plugin)
+│   └── path-jail.ts      # Path validation for fs plugins
+└── plugin-schema-types.ts
+```
+
+## Security Model
+
+- Plugins are security boundaries — guest code cannot escape the sandbox
+- Path traversal attacks are blocked via `shared/path-jail.ts`
+- Symlinks are rejected outright
+- Dotfiles are always blocked
+- Error messages are sanitised (no raw OS paths leak to guest)
+
+## Adding a New Plugin
+
+1. Create `plugins/<name>/index.ts` with plugin implementation
+2. Create `plugins/<name>/plugin.json` with manifest
+3. Export functions that will be available to guest JS
+4. Run `just test` to verify TypeScript requirement is met

.github/instructions/skills.instructions.md

@@ -0,0 +1,55 @@
+---
+applyTo: "skills/**"
+---
+
+# Skills
+
+Skills are domain-specific expertise modules that the agent can invoke. Each skill is defined by a `SKILL.md` file with YAML frontmatter.
+
+## Skill Structure
+
+```
+skills/<skill-name>/
+└── SKILL.md          # Skill definition with frontmatter + instructions
+```
+
+## SKILL.md Format
+
+```yaml
+---
+name: skill-name
+description: One-line description
+triggers:
+  - keyword1
+  - keyword2
+patterns:
+  - pattern-name
+antiPatterns:
+  - "Don't do X"
+allowed-tools:
+  - tool_name
+---
+
+# Skill Title
+
+Detailed instructions for the LLM when this skill is active.
+```
+
+## Current Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `pptx-expert` | PowerPoint presentation building |
+| `research-synthesiser` | Research and synthesis |
+| `data-processor` | Data processing workflows |
+| `web-scraper` | Web scraping |
+| `report-builder` | Report generation |
+| `api-explorer` | API exploration |
+
+## Triggers
+
+Skills are activated when user input matches trigger keywords. Multiple skills can match — the agent decides which to use.
+
+## Allowed Tools
+
+The `allowed-tools` frontmatter restricts which tools the skill can use. This provides a security boundary for domain-specific operations.