AI Safety — Familiar Chat

.claude/skills/endo/skill.md

@@ -0,0 +1,50 @@
+---
+name: endo
+description: Interact with the running Endo daemon — inspect agent inboxes, read/post to channels, list names, send messages to agents. Use when debugging agent behavior, checking channel state, or testing agent interactions.
+allowed-tools: Bash(node packages/fae/endo-skill.js *)
+argument-hint: <command> [args...]
+---
+
+# Endo Daemon Skill
+
+Connects to the running Endo daemon via CapTP to inspect and interact with agents, channels, and the inbox. The script lives at `packages/fae/endo-skill.js` — run from the monorepo root.
+
+## Commands
+
+```bash
+# Pet name directory
+node packages/fae/endo-skill.js names                     # List all HOST pet names
+node packages/fae/endo-skill.js names <agent-profile>      # List an agent's pet names
+node packages/fae/endo-skill.js lookup <name>              # Inspect a value (show methods)
+
+# Inbox
+node packages/fae/endo-skill.js inbox                     # List HOST inbox
+node packages/fae/endo-skill.js agent-inbox <profile> [N]  # List agent's last N inbox messages
+node packages/fae/endo-skill.js read-message <number>      # Full message JSON
+
+# Messaging
+node packages/fae/endo-skill.js send <to> <text>           # Send from HOST
+node packages/fae/endo-skill.js agent-send <agent> <text>  # Send to an agent
+
+# Channels
+node packages/fae/endo-skill.js channel-messages <name> [N]  # Last N channel messages
+node packages/fae/endo-skill.js channel-members <name>       # List channel members
+node packages/fae/endo-skill.js channel-post <name> <text> [--reply-to <n>]  # Post to channel
+```
+
+## Suppress CapTP teardown noise
+
+Add `2>/dev/null` to suppress stderr from the CapTP disconnect.
+
+## Common pet names
+
+- `profile-for-fae` — fae agent's profile (use with `agent-inbox` and `names`)
+- `fae-factory` — factory for creating fae agent instances
+- `fae` — the fae agent's handle
+
+## Notes
+
+- Run all commands from the monorepo root directory
+- Requires a running Endo daemon (`endo start`)
+- Channel message numbers are sequential integers
+- Agent profiles (e.g. `profile-for-fae`) give access to the agent's namespace

.github/workflows/familiar-release.yml

@@ -0,0 +1,147 @@
+name: Familiar Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version (e.g. 0.1.0)'
+        required: false
+        type: string
+  push:
+    tags:
+      - 'familiar-v*'
+
+permissions:
+  contents: write
+
+jobs:
+  build-artifacts:
+    name: Build bundles and chat dist
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - run: corepack enable
+
+      - name: Use Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
+        with:
+          node-version: 22.x
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Build chat dist
+        run: yarn workspace @endo/chat build
+
+      - name: Bundle CLI and gateway
+        run: yarn workspace @endo/familiar bundle
+
+      - name: Upload chat dist
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: chat-dist
+          path: packages/chat/dist/
+
+      - name: Upload bundles
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: bundles
+          path: packages/familiar/bundles/
+
+  make:
+    name: Make (${{ matrix.target-os }}-${{ matrix.target-arch }})
+    needs: build-artifacts
+    runs-on: ${{ matrix.runner }}
+
+    strategy:
+      matrix:
+        include:
+          - runner: macos-14
+            target-os: darwin
+            target-arch: arm64
+          - runner: macos-13
+            target-os: darwin
+            target-arch: x64
+          - runner: ubuntu-latest
+            target-os: linux
+            target-arch: x64
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - run: corepack enable
+
+      - name: Use Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
+        with:
+          node-version: 22.x
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Download chat dist
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: chat-dist
+          path: packages/chat/dist/
+
+      - name: Download bundles
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: bundles
+          path: packages/familiar/bundles/
+
+      - name: Download Node.js binary
+        run: |
+          cd packages/familiar
+          ./scripts/download-node.sh v20.18.1 ${{ matrix.target-os }} ${{ matrix.target-arch }}
+
+      - name: Prepare package
+        run: |
+          cd packages/familiar
+          ./scripts/prepare-package.sh ${{ matrix.target-os }} ${{ matrix.target-arch }}
+
+      - name: Make distributables
+        run: yarn workspace @endo/familiar make
+
+      - name: Upload make output
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: familiar-${{ matrix.target-os }}-${{ matrix.target-arch }}
+          path: packages/familiar/out/make/
+
+  release:
+    name: Create release
+    needs: make
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/familiar-v') || github.event.inputs.version != ''
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          path: artifacts/
+          pattern: familiar-*
+
+      - name: Determine version
+        id: version
+        run: |
+          if [ -n "${{ github.event.inputs.version }}" ]; then
+            echo "tag=familiar-v${{ github.event.inputs.version }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # v2
+        with:
+          tag_name: ${{ steps.version.outputs.tag }}
+          name: Familiar ${{ steps.version.outputs.tag }}
+          draft: true
+          files: artifacts/**/*

.gitignore

@@ -38,6 +38,7 @@ build/Release
 # Dependency directories
 node_modules
 jspm_packages/
+.yarn-global/
 
 # TypeScript v1 declaration files
 typings/

.prettierignore

@@ -2,6 +2,7 @@
 bundles
 dist
 fixtures
+out
 tmp
 /packages/ses-integration-test/transform-tests/output
 /packages/test262-runner/prelude

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/13/989b67c01d8d5d078ccd5c3d8ed55cea2a1fdc3b9284db54cc357a86ad86335f639df0d7331154e5dc9e72a5452b0c6866dd50fb318bd8de6ae5c61ebdbcd3.json

@@ -0,0 +1 @@
+{"type":"worker"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/2e/d3975e4fba4919efcac7b3d6feec26f33ecb32818314269517788cb6989e82a3280bb15ad1072474e2037483ff7f17bd0cb7aea7490933174a3e9066cf91f0.json

@@ -0,0 +1 @@
+{"type":"known-peers-store"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/32/4203a771fbca70b84f28f28f2a27b11b4d214102b66d60c6fb6cb1c62adcbae8f2f81748bdd6fe83c1ff81be72c903a5821676c80152f7b52bca1db146ec7a.json

@@ -0,0 +1 @@
+{"type":"least-authority"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/39/6e9de1d7bab905eed1c45813f05065d8b0805e57ac244263a8952c9296033cad5fafa34fc2d00ea246f17bfe0da88768587657896a22a79852350355b38361.json

@@ -0,0 +1 @@
+{"host":"46e41fbcad5f1a8b9f744821bd19c31cccaa232c7c7a7f32613434167ead86c56a62c4254f5be59c75ce5d993e83035a18e7c1b4175f25da0a5c216a88df1ddf:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","leastAuthority":"324203a771fbca70b84f28f28f2a27b11b4d214102b66d60c6fb6cb1c62adcbae8f2f81748bdd6fe83c1ff81be72c903a5821676c80152f7b52bca1db146ec7a:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","networks":"cd00815a6cfd845bba25619a6e58919aa6aa5f52d0c845fa4f85cbfb72bae69be74712c6c91f4e89964e67658996d5a2be8392f97e1c5b227aa787d93db5bda3:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","peers":"2ed3975e4fba4919efcac7b3d6feec26f33ecb32818314269517788cb6989e82a3280bb15ad1072474e2037483ff7f17bd0cb7aea7490933174a3e9066cf91f0:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","pins":"857391ff6ac0b0cd0c7c4a33cc8b9b69b2066faa0a6c234e2ba074086db03e4e729c2ac21257af2fb0b4ef321fcbff20908e01b11b39e8b623b56066d7f537a7:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","type":"endo"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/3a/479fb255db6de74e9ac8202c07c1434e4e1a8dab1f9b38ea77e56616077185a7cf41432db5eb783e5cf7de0fe78ad06981191f940737b572e1a746c5639be1.json

@@ -0,0 +1 @@
+{"body":"#\"+0\"","slots":[],"type":"marshal"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/40/36e0244e9f356a4ab87f9dc0ba1c78725f4c933801bb181d557d5dfd24e2a06b38e30b780624bf2ebdb9629ce7f97395e333c8d80e7e140d62af4ab87639ea.json

@@ -0,0 +1 @@
+{"type":"loopback-network"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/46/e41fbcad5f1a8b9f744821bd19c31cccaa232c7c7a7f32613434167ead86c56a62c4254f5be59c75ce5d993e83035a18e7c1b4175f25da0a5c216a88df1ddf.json

@@ -0,0 +1 @@
+{"endo":"396e9de1d7bab905eed1c45813f05065d8b0805e57ac244263a8952c9296033cad5fafa34fc2d00ea246f17bfe0da88768587657896a22a79852350355b38361:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","handle":"d8a8c3f598297de30986965e9ad031e95b6b9d37f1c627ea0067f4fe8be33cdcb42205a49fbc44d6d234d9334f9d82aeee3cba02d789dba999fdeaecaea79d62:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","hostHandle":"d8a8c3f598297de30986965e9ad031e95b6b9d37f1c627ea0067f4fe8be33cdcb42205a49fbc44d6d234d9334f9d82aeee3cba02d789dba999fdeaecaea79d62:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","inspector":"c0c9fff2a2ccf7c6e210a2ddae37919fa066049501baeaff9d9d5543d0d8553c9765bb1b754377d305ead9a09eb40496f8a1e2fd52cd62b8b78a6e8bfbcec65d:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","mailHub":"f73b284e0cf2c5697e34393773e91e2e308198fa2a24cfdd805f41f0c26903cfdc8144124468df7e9f01dd9de2aa8ad1034eeb7bec8fa0e29af2a7365b429c3a:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","mailboxStore":"7a168b2b6d39db43fe40ca7e809d8c816f7b868a24a742d1ad214253c540fa1c37020c6f9d85f5d945ac46a1da8683074408516c0a374caa8532192db490e3fc:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","networks":"cd00815a6cfd845bba25619a6e58919aa6aa5f52d0c845fa4f85cbfb72bae69be74712c6c91f4e89964e67658996d5a2be8392f97e1c5b227aa787d93db5bda3:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","petStore":"f0ce92ec88e084428eba5c936efa1385f3b0250aa738f2af0ff5d56b4bedf7eca122c2dc24068c6936191ab014f481751ce67b87f667371d60fb51412c044d2f:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","pins":"857391ff6ac0b0cd0c7c4a33cc8b9b69b2066faa0a6c234e2ba074086db03e4e729c2ac21257af2fb0b4ef321fcbff20908e01b11b39e8b623b56066d7f537a7:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","type":"host","worker":"96ca74dd31179666a0352fa5a20963ee01fb6ec3220a423339c5f412872f6f8ea17111065f664864c76b94c2c3ee90904d2a25509a2bb6a0c15674ebe8cf6768:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/7a/168b2b6d39db43fe40ca7e809d8c816f7b868a24a742d1ad214253c540fa1c37020c6f9d85f5d945ac46a1da8683074408516c0a374caa8532192db490e3fc.json

@@ -0,0 +1 @@
+{"type":"mailbox-store"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/85/7391ff6ac0b0cd0c7c4a33cc8b9b69b2066faa0a6c234e2ba074086db03e4e729c2ac21257af2fb0b4ef321fcbff20908e01b11b39e8b623b56066d7f537a7.json

@@ -0,0 +1 @@
+{"petStore":"bf469d3516307f729d8891c44ab390195ae5ac13807d0c0b2d2573954c1a96418e216f85d971fe3bea4153149bde57daf8f9a0cf1e7b0f3b54a9339830398a50:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","type":"directory"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/96/ca74dd31179666a0352fa5a20963ee01fb6ec3220a423339c5f412872f6f8ea17111065f664864c76b94c2c3ee90904d2a25509a2bb6a0c15674ebe8cf6768.json

@@ -0,0 +1 @@
+{"type":"worker"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/98/579e9c92669c123a80af54bb506d028db3c9808a4bd32965964a814d61d4bf26ede90c567a6b03039e351429e97fca4fa85875a1f67d40dce4714f0eb76828.json

@@ -0,0 +1 @@
+{"type":"pet-store"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/bf/469d3516307f729d8891c44ab390195ae5ac13807d0c0b2d2573954c1a96418e216f85d971fe3bea4153149bde57daf8f9a0cf1e7b0f3b54a9339830398a50.json

@@ -0,0 +1 @@
+{"type":"pet-store"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/c0/c9fff2a2ccf7c6e210a2ddae37919fa066049501baeaff9d9d5543d0d8553c9765bb1b754377d305ead9a09eb40496f8a1e2fd52cd62b8b78a6e8bfbcec65d.json

@@ -0,0 +1 @@
+{"petStore":"f0ce92ec88e084428eba5c936efa1385f3b0250aa738f2af0ff5d56b4bedf7eca122c2dc24068c6936191ab014f481751ce67b87f667371d60fb51412c044d2f:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","type":"pet-inspector"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/cd/00815a6cfd845bba25619a6e58919aa6aa5f52d0c845fa4f85cbfb72bae69be74712c6c91f4e89964e67658996d5a2be8392f97e1c5b227aa787d93db5bda3.json

@@ -0,0 +1 @@
+{"petStore":"98579e9c92669c123a80af54bb506d028db3c9808a4bd32965964a814d61d4bf26ede90c567a6b03039e351429e97fca4fa85875a1f67d40dce4714f0eb76828:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","type":"directory"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/d2/b6c8e6f4ff1920a1aca9ec44f28377fa93c2b73a0c0be25dd701d1f81e30a2734fdbd9844bb60a27cdfe7e171bdca1237312767aa188bab38116130394fc5f.json

@@ -0,0 +1 @@
+{"env":{"ENDO_ADDR":"127.0.0.1:8920","ENDO_WEB_PAGE_BUNDLE_PATH":""},"powers":"396e9de1d7bab905eed1c45813f05065d8b0805e57ac244263a8952c9296033cad5fafa34fc2d00ea246f17bfe0da88768587657896a22a79852350355b38361:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","specifier":"file:///Users/kris/endo-llm/packages/daemon/src/web-server-node.js","type":"make-unconfined","worker":"13989b67c01d8d5d078ccd5c3d8ed55cea2a1fdc3b9284db54cc357a86ad86335f639df0d7331154e5dc9e72a5452b0c6866dd50fb318bd8de6ae5c61ebdbcd3:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/d8/a8c3f598297de30986965e9ad031e95b6b9d37f1c627ea0067f4fe8be33cdcb42205a49fbc44d6d234d9334f9d82aeee3cba02d789dba999fdeaecaea79d62.json

@@ -0,0 +1 @@
+{"agent":"46e41fbcad5f1a8b9f744821bd19c31cccaa232c7c7a7f32613434167ead86c56a62c4254f5be59c75ce5d993e83035a18e7c1b4175f25da0a5c216a88df1ddf:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","type":"handle"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/f0/ce92ec88e084428eba5c936efa1385f3b0250aa738f2af0ff5d56b4bedf7eca122c2dc24068c6936191ab014f481751ce67b87f667371d60fb51412c044d2f.json

@@ -0,0 +1 @@
+{"type":"pet-store"}

.tmp/endo-cli-test-TIAvKd/state/endo/formulas/f7/3b284e0cf2c5697e34393773e91e2e308198fa2a24cfdd805f41f0c26903cfdc8144124468df7e9f01dd9de2aa8ad1034eeb7bec8fa0e29af2a7365b429c3a.json

@@ -0,0 +1 @@
+{"store":"7a168b2b6d39db43fe40ca7e809d8c816f7b868a24a742d1ad214253c540fa1c37020c6f9d85f5d945ac46a1da8683074408516c0a374caa8532192db490e3fc:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d","type":"mail-hub"}

.tmp/endo-cli-test-TIAvKd/state/endo/mailbox-store/7a/168b2b6d39db43fe40ca7e809d8c816f7b868a24a742d1ad214253c540fa1c37020c6f9d85f5d945ac46a1da8683074408516c0a374caa8532192db490e3fc/next-number

@@ -0,0 +1 @@
+3a479fb255db6de74e9ac8202c07c1434e4e1a8dab1f9b38ea77e56616077185a7cf41432db5eb783e5cf7de0fe78ad06981191f940737b572e1a746c5639be1:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d

.tmp/endo-cli-test-TIAvKd/state/endo/nonce

@@ -0,0 +1 @@
+396e9de1d7bab905eed1c45813f05065d8b0805e57ac244263a8952c9296033cad5fafa34fc2d00ea246f17bfe0da88768587657896a22a79852350355b38361

.tmp/endo-cli-test-TIAvKd/state/endo/pet-store/98/579e9c92669c123a80af54bb506d028db3c9808a4bd32965964a814d61d4bf26ede90c567a6b03039e351429e97fca4fa85875a1f67d40dce4714f0eb76828/loop

@@ -0,0 +1 @@
+4036e0244e9f356a4ab87f9dc0ba1c78725f4c933801bb181d557d5dfd24e2a06b38e30b780624bf2ebdb9629ce7f97395e333c8d80e7e140d62af4ab87639ea:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d

.tmp/endo-cli-test-TIAvKd/state/endo/root

@@ -0,0 +1 @@
+46e41fbcad5f1a8b9f744821bd19c31cccaa232c7c7a7f32613434167ead86c56a62c4254f5be59c75ce5d993e83035a18e7c1b4175f25da0a5c216a88df1ddf:d4e9d656e1a1095c7ea025ee485d7203c961818b8303d884d520c5d4861a0ac30db9251d3590c1132fad3cd15e66bc950e80abf073578bc5c3a3c4101901bd0d

CLAUDE.md

@@ -0,0 +1,111 @@
+# Endo Project Guidelines
+
+## Hardened JavaScript (SES) Conventions
+
+### harden() is mandatory
+
+- Every named export MUST have a corresponding `harden(exportName)` call immediately after the declaration. This is enforced by the `@endo/harden-exports` ESLint rule.
+- Objects returned from factory functions should be hardened: `return harden({ ... })`.
+- Module-level constant data structures (arrays, objects) should be hardened at declaration: `const foo = harden([...])`.
+
+### @ts-check and JSDoc types
+
+- Every `.js` source file must start with `// @ts-check`.
+- Use `@param`, `@returns`, `@typedef`, and `@type` annotations throughout.
+- Import types with the `@import` JSDoc tag: `/** @import { FarEndoGuest } from '@endo/daemon/src/types.js' */`
+- Prefer `@import` over dynamic `import()` in type positions. Use `/** @import { Foo } from './bar.js' */` at the top of the file instead of inline `/** @type {import('./bar.js').Foo} */`.
+- Cast `catch` error variables: `/** @type {Error} */ (e).message`
+- Cast untyped inputs from external APIs with inline `/** @type {T} */` assertions.
+
+### Error handling
+
+- Use `@endo/errors` for structured errors: `import { makeError, q, X } from '@endo/errors'`.
+- Use `q()` to safely quote values in error messages.
+- Use tagged template errors where appropriate: `throw makeError(X\`No formula for ${ref}\`)`.
+
+## Code Style
+
+### Imports
+
+- Group imports: external `@endo/*` packages first, then local imports, separated by a blank line.
+- Sort imports within each group.
+
+### Modules and exports
+
+- Unconfined guest modules export `make(powers)` as their entry point.
+- Prefer `makeExo()` with an `M.interface()` guard over `Far()` for
+  remotable objects.
+  `makeExo` automatically provides `__getMethodNames__()`, which CapTP
+  introspection relies on, and enforces method guards at the boundary.
+  `Far()` is still appropriate for lightweight one-off remotables that
+  do not need runtime type checking.
+- The `help()` method is conventional on capabilities and should return
+  a descriptive string.
+
+### Eventual send
+
+- Always use `E(ref).method()` for remote/eventual calls, never direct
+  invocation.
+- `E()` calls return promises; chain with `await` or further `E()` sends.
+
+### CapTP introspection
+
+- Use `E(ref).__getMethodNames__()` to discover a remote object's
+  interface rather than duck-typing by calling individual methods.
+  Duck-typing generates noisy failed CapTP calls for each method that
+  does not exist on the target.
+- `makeExo` objects provide `__getMethodNames__()` automatically.
+
+```js
+const methods = await E(ref).__getMethodNames__();
+if (methods.includes('followNameChanges')) {
+  // NameHub — live registry
+} else if (methods.includes('list')) {
+  // ReadableTree — immutable snapshot
+}
+```
+
+## ESLint
+
+- The project uses `plugin:@endo/internal` which extends `prettier`, `plugin:@jessie.js/recommended`, and `plugin:@endo/strict`.
+- This enforces harden-exports, restricts plus operands, and requires PascalCase for interfaces.
+
+## Build and Test
+
+- Yarn 4 via corepack: `npx corepack yarn install`
+- Package tests: `cd packages/<name> && npx ava`
+- Daemon integration tests: `cd packages/daemon && npx ava test/endo.test.js --timeout=120s`
+- Syntax check without SES runtime: `node --check <file.js>`
+- Full module loading requires the Endo daemon (SES lockdown provides `harden` as a global).
+
+## Familiar (Electron shell)
+
+### Testing
+
+- **Unit tests**: `npx ava packages/daemon/test/gateway.test.js packages/daemon/test/formula-identifier.test.js --timeout=90s`
+- **Build**: `cd packages/familiar && yarn bundle && yarn package`
+- **Lint**: `cd packages/familiar && yarn lint`
+- Gateway tests fork a full daemon per test. They must be `test.serial` to avoid resource contention.
+- Tests set `ENDO_ADDR=127.0.0.1:0` so the gateway binds to an OS-assigned port, avoiding conflicts with a running daemon on the default port 8920.
+- Kill leftover daemon processes between test runs: `pkill -f "daemon-node.*packages/daemon/tmp"` and `rm -rf packages/daemon/tmp/`.
+- Worker logs are in `packages/daemon/tmp/<test>/state/worker/<id>/worker.log` — check these when the APPS formula hangs silently.
+
+### Architecture constraints
+
+- The Electron main process must **never** import `@endo/init` or `ses`. SES lockdown freezes Electron internals.
+- Unconfined plugins (e.g., `web-server-node.js`) run inside an already-locked-down worker and must **not** import `ses` or `@endo/init` themselves; doing so causes double-lockdown errors.
+- Electron Forge requires `electron` in `devDependencies` to detect the version. If it's only in `dependencies`, packaging fails with "Could not find any Electron packages in devDependencies".
+- Port 0 (OS-assigned) is falsy in JavaScript. Use `port !== '' ? Number(port) : default` instead of `Number(port) || default`.
+
+## Markdown Style
+
+- Wrap lines at 80 to 100 columns.
+- Start each sentence on a new line so that diffs are per-sentence.
+- See `CONTRIBUTING.md` § "Markdown Style Guide" for full details.
+
+## Package Structure
+
+- Monorepo with `packages/` workspace layout.
+- Workspace dependencies use `"workspace:^"` version specifiers.
+- Each package has its own `tsconfig.json` and `tsconfig.build.json`.
+- No copyright headers in source files; license is declared in `package.json`.