Skip to content

copilot-instructions.md

Latest commit

 

History

History
97 lines (70 loc) · 4.46 KB

copilot-instructions.md

File metadata and controls

97 lines (70 loc) · 4.46 KB

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:

just setup         # First-time only: 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:

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-analysis-guest 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-analysis-guest passes
  5. No new expect/unwrap/assert in production TS code