js-sdk/AGENTS.md

AGENTS.md

Project

Wrenn JavaScript SDK — a client library for the Wrenn microVM platform. e2b drop-in replacement. Package name: @wrenn/sdk. Node.js 18+, TypeScript 5.5+, managed with pnpm.

Commands

pnpm install                          # install deps
make lint                             # biome check + format check (no auto-fix)
make test                             # unit tests only (vitest)
make test-integration                 # all tests including integration (needs live server)
make generate                         # regenerate types from OpenAPI spec (openapi-typescript)
make check                            # lint + unit test
make build                            # tsup build (CJS + ESM + DTS)

• make test runs all non-integration tests. To run a specific test file: pnpm vitest run tests/commands.test.ts
• No separate typecheck step — vitest and tsup handle type checking during test/build. tsc --noEmit is available but not wired up in CI.

Architecture

• src/ — the library package
  • capsule.ts — high-level Capsule class (main user-facing class)
  • client.ts — low-level WrennClient with CapsulesResource and SnapshotsResource
  • commands.ts — command execution, streaming, and background process management
  • files.ts — filesystem operations
  • pty.ts — interactive terminal (PTY) over WebSocket
  • exceptions.ts — typed error hierarchy (WrennError base)
  • models/generated.ts — auto-generated from OpenAPI spec via openapi-typescript (never edit directly; run make generate)
  • git/ — git operations inside capsules (clone, push, pull, status, branches, etc.)
  • code-interpreter/ — specialized capsule for stateful Jupyter kernel execution
  • _shared/http.ts — thin fetch wrapper with auth headers, base URL, and error mapping
  • _shared/websocket.ts — WebSocket helper wrapping ws
  • config.ts — constants (DEFAULT_BASE_URL, env var names)
• tests/ — unit tests use msw to mock HTTP; integration tests are in tests/integration/
• api/openapi.yaml — OpenAPI spec used for type generation

Key Conventions

• Generated types live in src/models/generated.ts. Never edit them. Run make generate to update.
• No sync/async split — JS is naturally async. One Capsule class, all methods return Promise.
• Sandbox is a deprecated alias for Capsule. New code should use Capsule.
• Uses native fetch for HTTP (Node 18+), ws for WebSockets, zod for runtime validation.
• Resource disposal via Symbol.asyncDispose (await using). Also supports manual .close().
• Streaming methods return AsyncGenerator (e.g. commands.stream(), files.downloadStream()).
• Static + instance method pattern: capsule.destroy() (instance) and Capsule.destroy(id, opts) (static).

Testing

• Unit tests mock HTTP via msw (Mock Service Worker for Node).
• Integration tests require env vars: WRENN_API_KEY (or WRENN_TOKEN), optionally WRENN_BASE_URL.
• Integration test fixtures in tests/integration/setup.ts create real capsules and clean them up.
• Tests use vitest — no @jest globals. Use import { describe, it, expect } from 'vitest'.

CI

Woodpecker CI (.woodpecker/check.yml) runs on push to main and dev:

1. make lint
2. make test
3. make test-integration

Dependencies

Runtime: ws (WebSocket), zod (validation). Everything else is dev-only.

MCP Tools: code-review-graph

IMPORTANT: This project has a knowledge graph. ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore the codebase. The graph is faster, cheaper (fewer tokens), and gives you structural context (callers, dependents, test coverage) that file scanning cannot.

When to use graph tools FIRST

• Exploring code: semantic_search_nodes or query_graph instead of Grep
• Understanding impact: get_impact_radius instead of manually tracing imports
• Code review: detect_changes + get_review_context instead of reading entire files
• Finding relationships: query_graph with callers_of/callees_of/imports_of/tests_for
• Architecture questions: get_architecture_overview + list_communities

Fall back to Grep/Glob/Read only when the graph doesn't cover what you need.

Key Tools

Tool	Use when
detect_changes	Reviewing code changes — gives risk-scored analysis
get_review_context	Need source snippets for review — token-efficient
get_impact_radius	Understanding blast radius of a change
get_affected_flows	Finding which execution paths are impacted
query_graph	Tracing callers, callees, imports, tests, dependencies
semantic_search_nodes	Finding functions/classes by name or keyword
get_architecture_overview	Understanding high-level codebase structure
refactor_tool	Planning renames, finding dead code

Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use detect_changes for code review.
3. Use get_affected_flows to understand impact.
4. Use query_graph pattern="tests_for" to check coverage.