Merge branch 'main' into sirtimid/remote-comms-resource-limits

Author: sirtimid

.claude/commands/check.md

@@ -0,0 +1,28 @@
+---
+name: check
+description: Lints, builds, and tests the code.
+argument-hint: [package-name]
+allowed-tools:
+  - Bash(yarn lint*)
+  - Bash(yarn build*)
+  - Bash(yarn test*)
+  - Bash(yarn workspace *)
+model: claude-haiku-4-5
+---
+
+Run the following commands to check the current state of the code:
+
+If `$ARGUMENTS` is provided (e.g. `@metamask/ocap-kernel`), run the commands in
+that workspace using `yarn workspace $ARGUMENTS`:
+
+1. `yarn workspace $ARGUMENTS lint:fix`
+2. `yarn workspace $ARGUMENTS build`
+3. `yarn workspace $ARGUMENTS test:dev`
+
+If `$ARGUMENTS` is empty, run the commands at the monorepo root:
+
+1. `yarn lint:fix`
+2. `yarn build`
+3. `yarn test:dev`
+
+Return the results of the commands.

.claude/commands/commit-push-pr.md

@@ -0,0 +1,10 @@
+---
+name: commit-push-pr
+description: Optionally checks, then commits and pushes code to the remote repository, and creates a pull request.
+argument-hint: check | force
+allowed-tools:
+  - Skill
+model: claude-haiku-4-5
+---
+
+Run `/commit-push $ARGUMENTS` then `/pr`.

.claude/commands/commit-push.md

@@ -0,0 +1,56 @@
+---
+name: commit-push
+description: Optionally checks, then commits and pushes code to the remote repository.
+argument-hint: check | force
+allowed-tools:
+  - Bash(git branch*)
+  - Bash(git checkout*)
+  - Bash(git add*)
+  - Bash(git status*)
+  - Bash(git commit*)
+  - Bash(git push*)
+  - Bash(git diff*)
+  - Bash(git log*)
+  - Skill
+model: claude-haiku-4-5
+---
+
+Arguments: $ARGUMENTS
+
+If the argument is "force", skip the check step. Otherwise (default), run the `/check` command first to lint, build, and test the code. If any of the checks fail, stop and report the errors.
+
+Once ready, commit and push the code by following these steps:
+
+1. Run these bash commands in parallel to understand the current state:
+
+   - `git status` to see all untracked files
+   - `git diff HEAD` to see both staged and unstaged changes
+   - `git log --oneline -10` to see recent commit messages for style consistency
+
+2. If you are on the `main` branch, create a new feature branch using `git branch` and switch to it.
+
+3. Analyze all changes and draft a commit message:
+
+   - Summarize the nature of the changes (new feature, enhancement, bug fix, refactoring, test, docs, etc.)
+   - Use the conventional commit format: `type(scope): description`
+   - Keep the first line under 72 characters
+   - Do not commit files that likely contain secrets (.env, credentials.json, etc.)
+
+4. Stage and commit the changes:
+
+   - Add relevant files using `git add`
+   - Create the commit with a message ending with:
+     ```
+     Co-Authored-By: Claude <[email protected]>
+     ```
+   - Use a HEREDOC for the commit message to ensure proper formatting
+
+5. Push to the remote repository:
+
+   - Run `git push` to push the commit
+   - If the branch has no upstream, use `git push -u origin <branch-name>`
+
+6. Report the results including:
+   - The commit hash
+   - The commit message
+   - The push status

.claude/commands/pr.md

@@ -0,0 +1,20 @@
+---
+name: pr
+description: Creates a pull request for the current branch.
+allowed-tools:
+  - Bash(git status*)
+  - Bash(git log*)
+  - Bash(git show*)
+  - Bash(git diff*)
+  - Bash(gh pr create*)
+model: claude-haiku-4-5
+---
+
+1. Run `git status`. If any of the following conditions apply, stop and report the errors:
+   - There are unstaged changes
+   - There are untracked files
+   - The current branch is the default branch (`main`)
+2. Run `git log main..HEAD --oneline` to see the commit history.
+3. Run `git diff` and/or `git show` as necessary to understand the changes.
+4. Run `gh pr create` to create a pull request.
+5. Return the results of the commands.

.claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "permissions": {
+    "allow": ["Skill(code-review)", "Skill(glossary)"],
+    "deny": ["Read(**/.env)", "Read(**/.env.*)"]
+  }
+}

.claude/skills/code-review/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: code-review
+description: How to review code; a pull request, feature branch, local changes etc.
+---
+
+When asked to review code, whether a PR on GitHub or some local changes, provide feedback on:
+
+- Code quality and best practices
+- Potential bugs or issues
+- Performance considerations
+- Security concerns
+- Test coverage
+
+Use the repository's CLAUDE.md for guidance on style and conventions.
+If you encounter terms that should be added to the glossary, invoke the glossary
+skill using: Skill tool with skill="glossary"
+Be constructive and helpful in your feedback.

.claude/skills/glossary/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: glossary
+description: How to add entries to the glossary
+---
+
+The [glossary](../../docs/glossary.md) explains terms with specific meanings in this
+project. When a new term is introduced—or an old term without a glossary entry discovered—
+consider adding the term to the glossary.
+
+When doing so:
+
+- Include links to relevant implementation files using `[term](../path/to/file.ts)` syntax
+- Use cross-references with `[term](#term)` syntax to link related concepts
+- Consider how new terms relate to existing architectural concepts

AGENTS.md

@@ -1,148 +1,76 @@
-Code style and structure:
-
-- Write concise, accurate JavaScript/TypeScript with modern ES Module syntax.
-- Always use TypeScript unless otherwise specified.
-- Use a class-based structure where applicable.
-- Use `harden()` from `@endo/ses` for object security.
-- Use object capability (ocap) design patterns.
-- Use `@metamask/superstruct` for validation.
-- Use TypeDoc for documentation.
-- Use the following naming conventions:
-  - camelCase for functions and variables.
-  - PascalCase for classes, types, interfaces, and enums.
-  - kebab-case for package and file names (`@ocap/test-utils`, `kernel-worker.js`, `vat.js`).
-  - Nouns for variable names (e.g. `isKernelActive`, `hasVatAccess`, `unresolvedMessages`)
-  - Verbs for function names (e.g. `startVat`, `stopKernel`)
-- Use explicit return types for all functions.
-
-Testing and debugging:
-
-- Use `vitest` for testing.
-- Prefer `toStrictEqual()` for deep object comparisons in tests.
-- Use `it.each()` for parameterized tests.
-- Use descriptive test blocks with proper nesting.
-- Test titles should use concise verb forms without "should" (e.g., `it('creates and starts libp2p node', ...)` not `it('should create and start libp2p node', ...)`).
-- For negative cases, use "does not" instead of "should not" (e.g., `it('does not duplicate relays', ...)`).
-- Mock functions with `vi.fn()` and explicit return types.
-- Aim for high test coverage, including unit and integration tests.
-- Mock external dependencies using vitest's `vi.mock()`.
-
-TypeScript usage:
+Documentation:
 
-- Use types for defining message structures and data contracts. Do not use `interface` declarations.
-- Leverage union types and type guards for robust runtime checks.
-- Use `Readonly<T>` for immutable data structures.
-- Follow strict mode settings for TypeScript.
-- Never use the `any` type.
-- Prefer `#` private fields over `private` class fields.
+- Check the [glossary](./docs/glossary.md) for definitions of unclear terms.
 
-File and directory structure:
+Development workflows:
 
-- Maintain a monorepo structure using Yarn workspaces.
-- Place package source files under `<package-root>/src/`.
-- Co-locate a package's unit tests with their covered source files in the `<package-root>/src/` directory (e.g. `ocap-kernel/src/kernel-worker.ts` should be tested in `ocap-kernel/src/kernel-worker.test.ts`).
-- Test utilities used by a single package should be separated into that package's `<package-root>/test/` directory.
-  - If the utility is small, it can be in-lined in the test file.
-- Test utilities used by multiple packages should be relocated into the dedicated `test-utils` package.
+- Use `yarn` and `yarn workspace` to run package scripts:
+  - `lint:fix` for linting
+  - `test:dev` for unit tests, `test` to include coverage
+  - e2e tests invoked separately via `test:e2e`, if available
+  - `build` from root is cached using Turborepo
 
-Kernel architecture:
+General conventions:
 
-- Ensure clear separation of concerns between Kernel, Vat, and Supervisor components.
-- Use streams from the `streams` package for message passing / IPC.
+- Use `@metamask/superstruct` for runtime type checking and to define object types
+- Use TypeDoc for documentation
+- Naming conventions:
+  - Nouns for variable names (e.g. `isKernelActive`, `hasVatAccess`, `unresolvedMessages`)
+  - Verbs for function names (e.g. `startVat`, `stopKernel`)
+  - kebab-case for package and file names (`@ocap/test-utils`, `kernel-worker.js`, `vat.js`)
+  - Factory methods: `X.make()`
+  - Factory functions: `makeX()`
+- If a function has more than two arguments or could be expected to grow thereto,
+  give it an options bag (i.e. named parameters)
+
+Object capability (ocap) patterns:
+
+- Production code should run under "lockdown" from `@endo/lockdown`
+  - Lockdown must be the first thing that runs in the given JavaScript realm for it to work
+- Use `harden()` from `@endo/ses` for immutability where feasible
+  - Including object literals, class instances, class prototypes, etc.
+- Use `E()` from `@endo/eventual-send` to:
+  - Communicate with objects between vats or between processes with a CapTP connection
+  - Queue messages on a promise (that resolves to some object with methods)
+- If an object is to be made remotable, turn it into an exo using the internal `makeDefaultExo`
+  which builds on `@endo/exo`
+  - Do not use `Far` from `@endo/far`
+  - It's fine to use `E()` on local objects that aren't exos
+
+Testing:
+
+- Use `vitest` for testing
+- Always use `toStrictEqual()` for deep object comparisons
+- Use `it.each()` for parameterized tests
+- Use logically nested `describe()` blocks
+- Test titles should use concise verb forms without "should" (e.g., `it('creates and starts libp2p node', ...)` not `it('should create and start libp2p node', ...)`)
+- Avoid negative cases, but if you must, use "does not" instead of "should not" (e.g., `it('does not duplicate relays', ...)`)
+- Mock functions with `vi.fn()` and explicit return types
+- Mock external dependencies using vitest's `vi.mock()`
+- Aim for complete unit test coverage when writing tests
+
+TypeScript:
+
+- Prefer `type`; do not use `interface` declarations
+- Prefer `#` private fields over `private` class fields
+- Never use the `any` type
+- Never use `enum`:s; always use string literal unions instead
 
-Web extensions:
+File and directory structure:
 
-- Use the latest manifest version (v3) for Chrome.
-- Minimize permissions in `manifest.json`, using optional permissions where feasible.
-- Apply Content Security Policies (CSP) in `manifest.json`.
+- Maintain a monorepo structure using Yarn workspaces
+- Place package source files under `<package-root>/src/`
+- Co-locate a package's unit tests with their covered source files in the `<package-root>/src/` directory (e.g. `ocap-kernel/src/kernel-worker.ts` should be tested in `ocap-kernel/src/kernel-worker.test.ts`)
+- Test utilities used by a single package should be separated into that package's `<package-root>/test/` directory
+- Test utilities used by multiple packages should be relocated into the dedicated `test-utils` package
 
 UI and styling:
 
-- Create responsive designs for UI components like popups or settings.
-- Use Flexbox or CSS Grid for layout consistency.
-- Use plain CSS, HTML, and JavaScript for UI components. Do not use React or other frameworks.
-- For React UI components, prefer CSS classes (e.g., `className="bg-section p-4 rounded mb-4"`) over inline styles.
-- Use inline styles only for dynamic values or when CSS classes are not available.
-- Structure layouts with semantic containers and proper spacing.
-- Use design system components (BadgeStatus, TextComponent, etc.) consistently.
-- Group related UI elements in logical sections with descriptive comments.
-- Maintain consistent spacing patterns (e.g., `gap-12`, `mb-4`, `mt-2`).
-- Use responsive classes and proper flex layouts for different screen sizes.
+- For React UI components, prefer CSS classes (e.g., `className="bg-section p-4 rounded mb-4"`) over inline styles
+- Use design system components (BadgeStatus, TextComponent, etc.) consistently
+- Maintain consistent spacing patterns (e.g., `gap-12`, `mb-4`, `mt-2`)
 
 Cross-environment compatibility:
 
-- Libraries should be platform-agnostic and run in any environment unless otherwise specified.
-- Packages like `extension` (browser) and `cli` (Node.js) are platform-specific.
-- Implement graceful degradation for environment-specific features.
-
-Type safety:
-
-- Prefer `@metamask/superstruct` when defining object types.
-- Use runtime type guards, not type assertions, when type narrowing is required.
-- Define object types for all data structures.
-- Avoid redundant type declarations.
-
-Error handling:
-
-- Use structured error classes with inheritance, error codes, and messages.
-- Implement error marshaling and unmarshaling.
-- Use type guards for error checking.
-
-Documentation:
-
-- Check the [glossary](./docs/glossary.md) for definitions of unclear terms.
-- Use JSDoc and TypeDoc for public APIs.
-- Include examples and document error cases.
-- When adding glossary entries:
-  - Include links to relevant implementation files using `[term](../path/to/file.ts)` syntax
-  - Use cross-references with `[term](#term)` syntax to link related concepts
-  - Consider how new terms relate to existing architectural concepts
-
-PR review:
-
-- Check if new terms, concepts, or architectural patterns are introduced that should be added to the glossary for AI agent accessibility.
-- Consider adding glossary entries for:
-  - New technical terms or abbreviations
-  - Core architectural components
-  - Important data structures or types
-  - Communication patterns or protocols
-  - System operations or processes
-- Include links to relevant implementation files when adding glossary entries.
-
-Changelog management:
-
-- Follow Keep a Changelog v1.0.0 format (https://keepachangelog.com/en/1.0.0/) for all CHANGELOG.md files.
-- For release PRs, categorize "### Uncategorized" entries into:
-  - "### Added" for new features and functionality (entries starting with "feat:")
-  - "### Changed" for changes to existing functionality (entries starting with "chore:" or breaking changes)
-  - "### Deprecated" for soon-to-be removed features
-  - "### Removed" for now removed features
-  - "### Fixed" for bug fixes and corrections (entries starting with "fix:" or "refactor:")
-  - "### Security" in case of vulnerabilities
-- Each changelog should describe changes specific to that package
-- Skip dependency updates unless they cause downstream changes; if so, describe the actual changes instead
-- Remove prefixes like "feat:", "chore:", "fix:", "refactor:" from changelog entries
-- Use clean, descriptive language without technical prefixes
-- When running in agent mode, fetch GitHub PR descriptions to better understand:
-  - The actual impact of each change on the specific package
-  - Whether dependency updates introduce breaking changes or new functionality
-  - More context for writing accurate, descriptive changelog entries
-- Use PR descriptions to determine if changes should be:
-  - Skipped entirely (pure dependency bumps with no package impact)
-  - Rewritten to focus on user-facing changes rather than implementation details
-  - Moved to different categories based on actual impact
-- Example transformations:
-  - "feat(ocap-kernel): Add kernel command 'revoke'" → "Add kernel command 'revoke'"
-  - "chore: bump endo dependencies" → Remove (unless it causes package-specific changes)
-  - "fix: make Revoke button refresh object registry" → "Make Revoke button refresh object registry"
-
-Context-aware development:
-
-- Align new code with existing project structure for consistency.
-- Prioritize modular, reusable components.
-
-Code output:
-
-- Provide complete, self-contained examples.
-- Include necessary imports and context for code snippets.
-- Document significant changes, especially for Endo-specific patterns or Chrome APIs.
+- Libraries should be platform-agnostic and run in any environment unless otherwise specified
+- Packages like `extension` (browser) and `cli` (Node.js) are platform-specific

package.json

@@ -20,18 +20,18 @@
     "clean": "rimraf --glob './*.tsbuildinfo' ./.eslintcache ./coverage ./.turbo && yarn workspaces foreach --all --parallel --interlaced --verbose run clean",
     "create-package": "tsx packages/create-package/src/index.ts",
     "lint": "yarn constraints && yarn lint:eslint && yarn lint:misc --check && yarn lint:dependencies",
-    "lint:dependencies": "yarn dedupe --check && yarn depcheck && yarn workspaces foreach --all --parallel --verbose run lint:dependencies",
-    "lint:dependencies:fix": "yarn dedupe && yarn depcheck && yarn workspaces foreach --all --parallel --verbose run lint:dependencies",
+    "lint:dependencies": "yarn dedupe --check >/dev/null && yarn depcheck --quiet && yarn workspaces foreach --all --parallel --verbose run lint:dependencies",
+    "lint:dependencies:fix": "yarn dedupe >/dev/null && yarn depcheck --quiet && yarn workspaces foreach --all --parallel --verbose run lint:dependencies",
     "lint:eslint": "yarn eslint . --cache",
     "lint:fix": "yarn constraints --fix && yarn lint:eslint --fix && yarn lint:misc --write && yarn lint:dependencies:fix",
-    "lint:misc": "prettier --no-error-on-unmatched-pattern '**/*.json' '**/*.md' '**/*.html'  '**/*.yml' '!**/CHANGELOG.old.md' '!.yarnrc.yml' '!CLAUDE.md' '!merged-packages/**' --ignore-path .gitignore",
+    "lint:misc": "prettier --no-error-on-unmatched-pattern '**/*.json' '**/*.md' '**/*.html'  '**/*.yml' '!**/CHANGELOG.old.md' '!.yarnrc.yml' '!CLAUDE.md' '!merged-packages/**' --ignore-path .gitignore  --log-level error",
     "postinstall": "simple-git-hooks && yarn rebuild:native",
     "prepack": "./scripts/prepack.sh",
     "pretest": "bash scripts/reset-coverage-thresholds.sh",
     "rebuild:native": "./scripts/rebuild-native.sh",
     "test": "yarn pretest && vitest run",
     "test:ci": "vitest run --coverage false",
-    "test:dev": "yarn test --mode development",
+    "test:dev": "yarn test --mode development --reporter dot",
     "test:e2e": "yarn workspaces foreach --all run test:e2e",
     "test:e2e:ci": "yarn workspaces foreach --all run test:e2e:ci",
     "test:verbose": "yarn test --reporter verbose",