@agent-foundry/replay-server 1.0.0

package/README.md

@@ -0,0 +1,628 @@
+# AgentFoundry Replay Renderer
+
+Video rendering service for AgentFoundry mini-game replays using Puppeteer and FFmpeg.
+
+## Architecture
+
+This renderer uses a **Puppeteer-based approach** where:
+
+1. The actual game is loaded in a headless browser
+2. A replay manifest is injected into the game
+3. The game enters "replay mode" and plays back the events
+4. Screenshots are captured at each frame
+5. FFmpeg combines screenshots into video
+
+This approach ensures the video looks **exactly like the gameplay** with zero code duplication.
+
+### Static Bundle Hosting
+
+The replay-server can host game bundles internally, eliminating the need for a separate game server:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     replay-server                             │
+│  ┌─────────────┐   ┌──────────────┐   ┌─────────────────┐   │
+│  │ Bundle Host │   │   Puppeteer  │   │   HTTP API      │   │
+│  │ /bundles/*  │◄──│   Renderer   │◄──│   POST /render  │   │
+│  └─────────────┘   └──────────────┘   └─────────────────┘   │
+│         │                                      ▲             │
+│         ▼                                      │             │
+│  bundles/game-life-restart/          manifest.json           │
+└──────────────────────────────────────────────────────────────┘
+```
+
+With `bundleId` in the manifest, the server:
+1. Serves the game from `/bundles/<bundleId>/`
+2. Puppeteer loads the game from the internal static server
+3. No external game server required
+
+## Prerequisites
+
+- Node.js 18+
+- pnpm 9.1.0+ (this is a pnpm monorepo)
+- FFmpeg installed and in PATH
+- **Option A**: Game running at `http://localhost:5173` (development mode)
+- **Option B**: Game bundle in `bundles/` directory (production mode)
+
+### Installing pnpm
+
+```bash
+npm install -g pnpm@9.1.0
+# or
+corepack enable
+corepack prepare pnpm@9.1.0 --activate
+```
+
+### Installing FFmpeg
+
+**macOS:**
+```bash
+brew install ffmpeg
+```
+
+**Windows:**
+```bash
+choco install ffmpeg
+# or download from https://ffmpeg.org/download.html
+```
+
+**Linux:**
+```bash
+sudo apt install ffmpeg
+```
+
+## Usage
+
+### Setup
+
+```bash
+# From project root - install all dependencies
+pnpm install
+
+# Or install only this package and its dependencies
+cd packages/replay-server
+pnpm install
+```
+
+### CLI Tool
+
+```bash
+# From project root (recommended)
+pnpm --filter replay-server render -- --manifest ./packages/replay-server/samples/replay.json --output ./packages/replay-server/output/output.mp4
+
+# From package directory
+cd packages/replay-server
+pnpm run render -- --manifest ./samples/replay.json --output ./output/output.mp4
+
+# Alternative: Use tsx directly
+cd packages/replay-server
+pnpm exec tsx src/cli/render.ts --manifest ./samples/replay.json --output ./output/output.mp4
+
+# Render with custom settings
+pnpm --filter replay-server render -- \
+  --manifest ./replay.json \
+  --output ./output.mp4 \
+  --game-url http://localhost:5173 \
+  --width 1080 \
+  --height 1920 \
+  --fps 30 \
+  --seconds-per-age 2
+```
+
+### HTTP Server
+
+```bash
+# From project root (recommended)
+pnpm dev:replay-server
+
+# Or from package directory
+cd packages/replay-server
+pnpm run dev
+
+# Production build and start
+# From project root
+pnpm build:replay-server
+cd packages/replay-server
+pnpm start
+
+# Or from package directory
+cd packages/replay-server
+pnpm run build
+pnpm start
+```
+
+#### API Endpoints
+
+**POST /render** - Start a render job
+
+With bundleId (recommended - no external game server needed):
+```bash
+curl -X POST http://localhost:3001/render \
+  -H "Content-Type: application/json" \
+  -d '{
+    "manifest": {
+      "schema": "lifeRestart.replay.v1",
+      "bundleId": "game-life-restart",
+      "gameId": "test-game",
+      "timeline": [...],
+      "highlights": []
+    },
+    "config": {
+      "width": 1080,
+      "height": 1920
+    }
+  }'
+```
+
+With external gameUrl (legacy mode):
+```bash
+curl -X POST http://localhost:3001/render \
+  -H "Content-Type: application/json" \
+  -d '{
+    "manifest": { ... },
+    "config": {
+      "gameUrl": "http://localhost:5173",
+      "width": 1080,
+      "height": 1920
+    }
+  }'
+```
+
+Response:
+```json
+{
+  "jobId": "5eaee18f-48a7-4193-b594-86756ac76ce2",
+  "status": "pending",
+  "message": "Render job started"
+}
+```
+
+**GET /bundles** - List available game bundles
+```bash
+curl http://localhost:3001/bundles
+```
+
+Response:
+```json
+{
+  "bundles": [
+    {
+      "bundleId": "game-life-restart",
+      "path": "/app/packages/replay-server/bundles/game-life-restart",
+      "url": "http://localhost:3001/bundles/game-life-restart/",
+      "ready": true
+    }
+  ],
+  "count": 1
+}
+```
+
+**GET /jobs** - List all jobs
+```bash
+curl http://localhost:3001/jobs
+```
+
+Response:
+```json
+{
+  "jobs": [
+    {
+      "jobId": "5eaee18f-48a7-4193-b594-86756ac76ce2",
+      "status": "completed",
+      "progress": { ... },
+      "error": null,
+      "createdAt": "2024-01-01T00:00:00.000Z",
+      "completedAt": "2024-01-01T00:05:00.000Z"
+    }
+  ],
+  "count": 1
+}
+```
+
+**GET /status/:jobId** - Check job status
+```bash
+curl http://localhost:3001/status/5eaee18f-48a7-4193-b594-86756ac76ce2
+```
+
+**GET /download/:jobId** - Download completed video
+```bash
+curl -o video.mp4 http://localhost:3001/download/5eaee18f-48a7-4193-b594-86756ac76ce2
+```
+
+## Game Integration
+
+For the renderer to work, the game must support replay mode:
+
+### 1. Listen for replay manifest
+
+```typescript
+// In your game's main component
+useEffect(() => {
+  // Check for manifest from URL or window
+  const urlParams = new URLSearchParams(window.location.search);
+  if (urlParams.get('mode') === 'replay') {
+    // Wait for manifest injection
+    const handleManifest = (e: CustomEvent) => {
+      const manifest = e.detail;
+      enterReplayMode(manifest);
+    };
+    
+    window.addEventListener('replay-manifest-loaded', handleManifest);
+    
+    // Also check if already injected
+    if ((window as any).__REPLAY_MANIFEST__) {
+      enterReplayMode((window as any).__REPLAY_MANIFEST__);
+    }
+  }
+}, []);
+```
+
+### 2. Handle replay-next-age event
+
+```typescript
+window.addEventListener('replay-next-age', () => {
+  // Advance to next age in replay
+  replayNextAge();
+});
+```
+
+### 3. Signal when ready
+
+```tsx
+// Add data attribute when ready for capture
+<div data-replay-ready="true">
+  {/* game content */}
+</div>
+```
+
+## Configuration
+
+Environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | 3001 | Server port |
+| `GAME_URL` | http://localhost:5173 | Fallback URL when no bundleId specified |
+| `BUNDLES_DIR` | ./bundles | Directory containing game bundles |
+| `OUTPUT_DIR` | ./output | Directory for rendered videos |
+
+### Game URL Resolution Order
+
+When rendering a video, the game URL is resolved in this order:
+1. `config.gameUrl` (explicit URL in render request)
+2. `manifest.bundleId` (serves from `/bundles/<bundleId>/`)
+3. `GAME_URL` environment variable (fallback)
+
+## Output
+
+Videos are rendered in:
+- Format: MP4 (H.264)
+- Resolution: 720x1080 (portrait, for mobile/Feed)
+- FPS: 16 (configurable)
+- Duration: ~1.2s per age (configurable)
+
+## Building Game Bundles
+
+Before deploying, you need to build game bundles that will be hosted by the replay-server.
+
+### Option A: Using the build script
+
+```bash
+# Build a specific game
+cd packages/replay-server
+./scripts/build-bundle.sh game-life-restart
+
+# This will:
+# 1. Build the game from repo/game-life-restart
+# 2. Copy dist/ to bundles/game-life-restart/
+```
+
+### Option B: Manual build
+
+```bash
+# Build the game
+cd repo/game-life-restart
+pnpm install
+pnpm build
+
+# Copy to bundles
+mkdir -p packages/replay-server/bundles/game-life-restart
+cp -r dist/* packages/replay-server/bundles/game-life-restart/
+```
+
+### Option C: Docker (automatic)
+
+The Dockerfile includes a multi-stage build that automatically builds and embeds the game bundle. No manual steps required.
+
+## Deployment Options
+
+### Local Development
+
+```bash
+# From project root (recommended)
+pnpm dev:replay-server
+
+# Or from package directory
+cd packages/replay-server
+pnpm run dev
+```
+
+### Docker with Embedded Bundle (Recommended)
+
+The Dockerfile uses multi-stage builds to:
+1. Build the game-life-restart bundle
+2. Build the replay-server
+3. Create a runtime image with both embedded
+
+```bash
+# Build from project root
+docker build -f packages/replay-server/Dockerfile -t replay-server:latest .
+
+# Or use docker-compose for local testing
+cd packages/replay-server
+docker-compose -f docker-compose.local.yml up --build
+```
+
+### Serverless (Aliyun FC)
+
+Build and deploy to Aliyun Function Compute:
+
+#### 1. Login to Aliyun Container Registry (ACR)
+
+```bash
+# Login using Aliyun CLI (recommended)
+aliyun cr GetAuthorizationToken --region cn-beijing --InstanceId xxx
+docker login --username=<your-username> --password=<token> registry.cn-beijing.aliyuncs.com
+
+# Or use temporary password from Aliyun console
+docker login registry.cn-beijing.aliyuncs.com
+```
+
+#### 2. Build Docker Image
+
+```bash
+# Build from project root (must be from root, as it needs access to multiple packages in monorepo)
+cd /path/to/agent-foundry
+docker build -f packages/replay-server/Dockerfile -t replay-server:latest .
+
+# Note:
+# - Dockerfile uses multi-stage builds
+# - Stage 1: Builds game-life-restart bundle
+# - Stage 2: Builds replay-server
+# - Stage 3: Creates runtime with embedded bundle
+# - Includes Chinese fonts (Noto CJK, WQY Zenhei) for proper text rendering
+```
+
+#### 3. Local Docker Testing
+
+Before pushing to ACR, test the Docker image locally:
+
+##### 3.1 Using Docker Compose (Recommended)
+
+```bash
+cd packages/replay-server
+docker-compose -f docker-compose.local.yml up --build
+
+# In another terminal:
+curl http://localhost:3001/health
+curl http://localhost:3001/bundles
+```
+
+##### 3.2 Using Docker Run
+
+```bash
+# Run container with embedded bundle
+docker run -d \
+  --name replay-server-test \
+  -p 3001:3001 \
+  --shm-size=2g \
+  -e PORT=3001 \
+  -v $(pwd)/packages/replay-server/output:/app/packages/replay-server/output \
+  replay-server:latest
+
+# View container logs
+docker logs -f replay-server-test
+```
+
+##### 3.3 Test Health Check
+
+```bash
+# Check if the service started normally
+curl http://localhost:3001/health
+
+# Expected response:
+# {
+#   "status": "ok",
+#   "gameUrl": "http://localhost:5173",
+#   "bundlesDir": "/app/packages/replay-server/bundles",
+#   "bundleCount": 1
+# }
+
+# List available bundles
+curl http://localhost:3001/bundles
+```
+
+##### 3.4 Test Render API with bundleId
+
+```bash
+# Submit a render task using embedded bundle (no external game server needed!)
+curl -X POST http://localhost:3001/render \
+  -H "Content-Type: application/json" \
+  -d '{
+    "manifest": {
+      "schema": "lifeRestart.replay.v1",
+      "bundleId": "game-life-restart",
+      "gameId": "test-game",
+      "timeline": [],
+      "highlights": []
+    },
+    "config": {
+      "width": 1080,
+      "height": 1920,
+      "fps": 30
+    }
+  }'
+
+# Or use local manifest file
+curl -X POST http://localhost:3001/render \
+  -H "Content-Type: application/json" \
+  -d "{\"manifest\": $(cat packages/replay-server/samples/life-replay-lr-mkcdfzc2-u8cqbs.json)}"
+
+# View task list
+curl http://localhost:3001/jobs
+
+# Check specific task status (replace <job-id> with actual task ID)
+curl http://localhost:3001/status/<job-id>
+
+# Download completed video (replace <job-id> with actual task ID)
+curl -o test-video.mp4 http://localhost:3001/download/<job-id>
+```
+
+##### 3.5 View Output Files
+
+```bash
+# View generated video files locally
+ls -lh packages/replay-server/output/
+
+# Or enter container to view
+docker exec -it replay-server-test ls -lh /app/packages/replay-server/output/
+```
+
+##### 3.6 Stop and Cleanup
+
+```bash
+# Stop container
+docker stop replay-server-test
+
+# Remove container
+docker rm replay-server-test
+
+# Or stop and remove in one command
+docker rm -f replay-server-test
+
+# Remove image (optional)
+docker rmi replay-server:latest
+```
+
+##### 3.7 Debugging Tips
+
+```bash
+# Enter container for debugging
+docker exec -it replay-server-test /bin/bash
+
+# Check processes inside container
+docker exec replay-server-test ps aux
+
+# Check environment variables
+docker exec replay-server-test env
+
+# View container resource usage
+docker stats replay-server-test
+```
+
+#### 4. Deploy to ACR
+
+Use the deploy script for easy deployment:
+
+```bash
+# Set your ACR namespace
+export ACR_NAMESPACE="your-namespace"
+
+# Deploy (builds and pushes to ACR)
+cd packages/replay-server
+./scripts/deploy-aliyun.sh
+
+# Or with a custom version tag
+./scripts/deploy-aliyun.sh v1.0.0
+```
+
+Or manually:
+
+```bash
+# Replace <your-namespace> with your namespace
+export ACR_REGISTRY="registry.cn-beijing.aliyuncs.com"
+export ACR_NAMESPACE="<your-namespace>"
+export IMAGE_NAME="replay-server"
+export IMAGE_TAG="latest"
+
+# Tag image
+docker tag replay-server:latest ${ACR_REGISTRY}/${ACR_NAMESPACE}/${IMAGE_NAME}:${IMAGE_TAG}
+
+# Push image
+docker push ${ACR_REGISTRY}/${ACR_NAMESPACE}/${IMAGE_NAME}:${IMAGE_TAG}
+```
+
+#### 5. Configure in Aliyun Function Compute
+
+** Rebuild to be compatible with Aliyun FC **
+```bash
+# make sure you are at root dir
+# build disabling attestation/provennace
+docker buildx build \
+  --platform linux/amd64 \
+  --provenance=false \
+  --sbom=false \
+  -t ${ACR_REGISTRY}/${ACR_NAMESPACE}/${IMAGE_NAME}:${IMAGE_TAG} \
+  -f packages/replay-server/Dockerfile \
+  --push \
+  . 
+
+# imagetools inspectation
+docker buildx imagetools inspect ${ACR_REGISTRY}/${ACR_NAMESPACE}/${IMAGE_NAME}:${IMAGE_TAG}
+```
+
+**Environment Variables:**
+- `PORT`: Server port (default: 9000, FC will set this automatically)
+- `BUNDLES_DIR`: `/app/packages/replay-server/bundles` (already set in Dockerfile)
+- `OUTPUT_DIR`: `/tmp/output` (use /tmp for FC writable directory)
+
+**Function Configuration Requirements:**
+- **Memory**: **Minimum 2048 MB (2GB)**, recommended 4GB
+  - Chromium requires significant memory to launch and render
+  - Less than 2GB may cause browser crashes or timeouts
+- **Timeout**: **Minimum 300 seconds (5 minutes)**, recommended 600 seconds (10 minutes)
+  - Cold start + browser launch can take 30-60 seconds
+  - Video rendering time depends on replay length
+- **Instance Concurrency**: **1** (required)
+  - Prevents resource contention between concurrent renders
+  - Each instance needs dedicated CPU/memory for Chromium
+- **CPU**: Auto-scaled with memory (FC default is fine)
+
+**Important Notes for FC Deployment:**
+- The image includes all Chromium dependencies pre-installed
+- Browser launch parameters are optimized for containerized environments
+- Cold starts may take longer on first invocation (expect 30-60s for browser initialization)
+
+#### 6. Verify Deployment
+
+```bash
+# Test if function started normally
+curl https://<your-function-url>/health
+
+# Check available bundles
+curl https://<your-function-url>/bundles
+
+# **NEW: Debug Chromium installation**
+curl https://<your-function-url>/debug/chrome
+# This endpoint verifies Chromium is properly installed and all dependencies are available
+# Expected response:
+# {
+#   "executablePath": "/usr/bin/chromium",
+#   "tests": {
+#     "version": { "ok": true, "output": "Chromium 120.0.6099.224" },
+#     "dependencies": { "ok": true, "summary": "All libraries found" },
+#     "chineseFonts": { "ok": true, "count": 15, "sample": ["Noto Sans CJK...", "..."] }
+#   }
+# }
+
+# Submit a render job
+curl -X POST https://<your-function-url>/render \
+  -H "Content-Type: application/json" \
+  -d '{
+    "manifest": {
+      "schema": "lifeRestart.replay.v1",
+      "bundleId": "game-life-restart",
+      ...
+    }
+  }'
+```

package/bundles/.gitkeep

@@ -0,0 +1,2 @@
+# This directory contains pre-built game bundles for replay rendering.
+# Bundle contents are git-ignored; only the directory structure is tracked.

package/dist/cli/render.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * CLI tool for offline video rendering
+ *
+ * Usage:
+ *   npx tsx src/cli/render.ts --manifest ./replay.json --output ./output.mp4
+ *   npx tsx src/cli/render.ts --manifest-url https://... --game-url http://localhost:5173
+ */
+export {};
+//# sourceMappingURL=render.d.ts.map

package/dist/cli/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/cli/render.ts"],"names":[],"mappings":";AACA;;;;;;GAMG"}