---
description: Build and package the AgentLens agent for macOS, Windows, and Linux
---

# Build & Package Agent (Cross-Platform)

This workflow builds the `@agentlens/agent` package into standalone binaries for all three platforms using Node.js SEA (Single Executable Applications) or `pkg`.

## Prerequisites

- Node.js 22+ (for SEA support)
- All tests passing (`npm run test` from monorepo root)

## Steps

### 1. Run full test suite first

```bash
cd /Users/sd9235/code/mygh/learning_agent_monitoring_fx
npm run test
```

### 2. Build the TypeScript

// turbo
```bash
cd /Users/sd9235/code/mygh/learning_agent_monitoring_fx/apps/agent
npx tsc
```

### 3. Bundle into single JS file (for SEA)

// turbo
```bash
cd /Users/sd9235/code/mygh/learning_agent_monitoring_fx/apps/agent
npx esbuild dist/main.js --bundle --platform=node --outfile=dist/agent-bundle.js --external:sharp --external:better-sqlite3
```

### 4. macOS — Create SEA binary

```bash
cd /Users/sd9235/code/mygh/learning_agent_monitoring_fx/apps/agent

# Generate SEA blob
echo '{"main":"dist/agent-bundle.js","output":"dist/sea-prep.blob"}' > sea-config.json
node --experimental-sea-config sea-config.json

# Copy node binary and inject
cp $(which node) dist/agentlens-macos
codesign --remove-signature dist/agentlens-macos
npx postject dist/agentlens-macos NODE_SEA_BLOB dist/sea-prep.blob \
  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
codesign --sign - dist/agentlens-macos

echo "✅ macOS binary: dist/agentlens-macos"
ls -lh dist/agentlens-macos
```

### 5. Windows — Create SEA binary (run on Windows machine or CI)

```powershell
cd apps/agent

# Generate SEA blob
node --experimental-sea-config sea-config.json

# Copy node.exe and inject
copy (Get-Command node).Source dist\agentlens-windows.exe
npx postject dist\agentlens-windows.exe NODE_SEA_BLOB dist\sea-prep.blob `
  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2

Write-Host "✅ Windows binary: dist\agentlens-windows.exe"
```

### 6. Linux — Create SEA binary (run on Linux machine or CI)

```bash
cd apps/agent

# Generate SEA blob
node --experimental-sea-config sea-config.json

# Copy node binary and inject
cp $(which node) dist/agentlens-linux
npx postject dist/agentlens-linux NODE_SEA_BLOB dist/sea-prep.blob \
  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2

echo "✅ Linux binary: dist/agentlens-linux"
ls -lh dist/agentlens-linux
```

### 7. GitHub Actions CI (all 3 platforms)

Create `.github/workflows/build-agent.yml` with this matrix:

```yaml
name: Build Agent
on:
  push:
    tags: ['v*']
  workflow_dispatch:

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: macos-latest
            name: agentlens-macos
          - os: windows-latest
            name: agentlens-windows.exe
          - os: ubuntu-latest
            name: agentlens-linux
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run test --workspace=apps/agent
      - run: npx tsc
        working-directory: apps/agent
      - run: npx esbuild dist/main.js --bundle --platform=node --outfile=dist/agent-bundle.js --external:sharp --external:better-sqlite3
        working-directory: apps/agent
      - run: |
          echo '{"main":"dist/agent-bundle.js","output":"dist/sea-prep.blob"}' > sea-config.json
          node --experimental-sea-config sea-config.json
        working-directory: apps/agent
      - name: Create binary (Unix)
        if: runner.os != 'Windows'
        working-directory: apps/agent
        run: |
          cp $(which node) dist/${{ matrix.name }}
          npx postject dist/${{ matrix.name }} NODE_SEA_BLOB dist/sea-prep.blob \
            --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
      - name: Create binary (Windows)
        if: runner.os == 'Windows'
        working-directory: apps/agent
        shell: pwsh
        run: |
          copy (Get-Command node).Source dist/${{ matrix.name }}
          npx postject dist/${{ matrix.name }} NODE_SEA_BLOB dist/sea-prep.blob --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.name }}
          path: apps/agent/dist/${{ matrix.name }}
```

### 8. Verify the binary

// turbo
```bash
cd /Users/sd9235/code/mygh/learning_agent_monitoring_fx/apps/agent
./dist/agentlens-macos --server http://localhost:3001 --help 2>&1 || echo "(expected: agent starts or shows usage)"
```

## Notes

- Binary size is ~40-60MB (includes Node.js runtime)
- `sharp` and `better-sqlite3` are excluded from bundle (native addons — need separate handling or prebuilds)
- For production: sign macOS binary with Developer ID, sign Windows with Authenticode
- Linux: create systemd unit file at `/etc/systemd/system/agentlens-agent.service`
- Consider `pkg` as alternative if SEA has issues with native modules
