chore: import upstream snapshot with attribution

2026-07-13 12:03:20 +08:00
commit 0ef5fcb1c5
1951 changed files with 606278 additions and 0 deletions
@@ -0,0 +1,168 @@
+# macOS LaunchAgent Deployment
+
+This directory contains templates and scripts for running the headroom proxy server as a persistent background service on macOS using LaunchAgent.
+
+## Quick Start
+
+```bash
+# Install the proxy service
+./install.sh
+
+# Add shell integration to ~/.bashrc or ~/.zshrc
+export HEADROOM_PORT=8787
+source /path/to/shell-integration.sh
+```
+
+## Files
+
+- **com.headroom.proxy.plist.template**: LaunchAgent plist template
+- **install.sh**: Automated installation script
+- **uninstall.sh**: Automated removal script
+- **shell-integration.sh**: Shell integration for automatic ANTHROPIC_BASE_URL configuration
+
+## Features
+
+- **Automatic Startup**: Service starts on user login
+- **Crash Recovery**: Automatically restarts if the proxy crashes
+- **Configurable Port**: Default 8787, customizable during installation
+- **Standard Logging**: Logs to `~/Library/Logs/headroom/`
+- **Shell Integration**: Automatically sets `ANTHROPIC_BASE_URL` for Claude clients
+
+## Requirements
+
+- macOS 10.13+ (High Sierra or later)
+- headroom-ai installed with proxy support: `pip install headroom-ai[proxy]`
+- Anthropic API key configured in environment
+
+## Installation Options
+
+### Quick Install (Recommended)
+
+```bash
+./install.sh
+```
+
+### Custom Port
+
+```bash
+./install.sh --port 9000
+```
+
+### Unattended Install
+
+```bash
+./install.sh --port 8787 --unattended
+```
+
+## Verification
+
+Check if the service is running:
+
+```bash
+# Check LaunchAgent status
+launchctl print gui/$(id -u)/com.headroom.proxy
+
+# Check if port is listening
+lsof -iTCP:8787 -sTCP:LISTEN
+
+# Test health endpoint
+curl http://localhost:8787/health
+```
+
+## Logs
+
+View logs:
+
+```bash
+# Standard output
+tail -f ~/Library/Logs/headroom/proxy.log
+
+# Error output
+tail -f ~/Library/Logs/headroom/proxy-error.log
+```
+
+## Uninstallation
+
+```bash
+# Remove service only
+./uninstall.sh
+
+# Remove service and logs
+./uninstall.sh --remove-logs
+```
+
+## Troubleshooting
+
+### Service won't start
+
+Check logs for errors:
+
+```bash
+tail -n 50 ~/Library/Logs/headroom/proxy-error.log
+```
+
+Common causes:
+
+- Missing ANTHROPIC_API_KEY environment variable
+- Port already in use
+- headroom not installed with proxy support
+
+### Port already in use
+
+Find what's using the port:
+
+```bash
+lsof -iTCP:8787 -sTCP:LISTEN
+```
+
+Change to a different port:
+
+```bash
+./uninstall.sh
+./install.sh --port 9000
+```
+
+### Service not auto-starting
+
+Verify LaunchAgent is loaded:
+
+```bash
+launchctl list | grep headroom
+```
+
+If not loaded:
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plist
+```
+
+## Manual Installation
+
+If you prefer manual installation:
+
+1. Copy template and customize:
+
+   ```bash
+   cp com.headroom.proxy.plist.template ~/Library/LaunchAgents/com.headroom.proxy.plist
+   ```
+
+2. Edit the plist file:
+   - Replace `__HEADROOM_PATH__` with output of `command -v headroom`
+   - Replace `__PORT__` with your desired port
+   - Replace `__HOME__` with your home directory path
+
+3. Create log directory:
+
+   ```bash
+   mkdir -p ~/Library/Logs/headroom
+   ```
+
+4. Load the LaunchAgent:
+
+   ```bash
+   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.headroom.proxy.plist
+   ```
+
+## Documentation
+
+For complete documentation, see [wiki/macos-deployment.md](../../../wiki/macos-deployment.md)
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- Service Label: Must match the filename -->
+    <key>Label</key>
+    <string>com.headroom.proxy</string>
+
+    <!-- Program to run: REPLACE __HEADROOM_PATH__ with actual headroom location -->
+    <key>ProgramArguments</key>
+    <array>
+        <string>__HEADROOM_PATH__</string>
+        <string>proxy</string>
+        <string>--host</string>
+        <string>127.0.0.1</string>
+        <string>--port</string>
+        <string>__PORT__</string>
+    </array>
+
+    <!-- Environment Variables -->
+    <key>EnvironmentVariables</key>
+    <dict>
+        <!-- Default port: 8787 (can be overridden by install script) -->
+        <key>HEADROOM_PROXY_PORT</key>
+        <string>__PORT__</string>
+
+        <!-- ANTHROPIC_API_KEY should be set in your shell environment -->
+        <!-- or uncomment and set here: -->
+        <!-- <key>ANTHROPIC_API_KEY</key> -->
+        <!-- <string>your-api-key-here</string> -->
+
+        <!-- Optional: Enable LLMLingua compression (requires llmlingua extra) -->
+        <!-- <key>HEADROOM_COMPRESSION_PROVIDER</key> -->
+        <!-- <string>llmlingua</string> -->
+    </dict>
+
+    <!-- Working Directory: REPLACE __HOME__ with user's home directory -->
+    <key>WorkingDirectory</key>
+    <string>__HOME__</string>
+
+    <!-- Standard Output Log: REPLACE __HOME__ with user's home directory -->
+    <key>StandardOutPath</key>
+    <string>__HOME__/Library/Logs/headroom/proxy.log</string>
+
+    <!-- Standard Error Log: REPLACE __HOME__ with user's home directory -->
+    <key>StandardErrorPath</key>
+    <string>__HOME__/Library/Logs/headroom/proxy-error.log</string>
+
+    <!-- Keep the service running (restart on crash) -->
+    <key>KeepAlive</key>
+    <true/>
+
+    <!-- Start the service when the user logs in -->
+    <key>RunAtLoad</key>
+    <true/>
+
+    <!-- Process Type: Adaptive (allows for background processing) -->
+    <key>ProcessType</key>
+    <string>Adaptive</string>
+
+    <!-- Throttle Interval: Wait 10 seconds between restart attempts -->
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+</dict>
+</plist>
@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+#
+# Headroom Proxy LaunchAgent Installer for macOS
+#
+# This script installs the headroom proxy as a macOS LaunchAgent for automatic
+# startup and management. The service will start on login and restart on crash.
+#
+# Usage: ./install.sh [--port PORT] [--unattended]
+#
+# Options:
+#   --port PORT       Port for proxy server (default: 8787)
+#   --unattended      Skip interactive prompts (use defaults)
+#
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+PLIST_LABEL="com.headroom.proxy"
+PLIST_FILENAME="${PLIST_LABEL}.plist"
+PLIST_DEST="${HOME}/Library/LaunchAgents/${PLIST_FILENAME}"
+LOG_DIR="${HOME}/Library/Logs/headroom"
+DEFAULT_PORT=8787
+USER_UID=$(id -u)
+
+# Parse command line arguments
+CUSTOM_PORT=""
+UNATTENDED=false
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --port)
+      CUSTOM_PORT="$2"
+      shift 2
+      ;;
+    --unattended)
+      UNATTENDED=true
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1"
+      echo "Usage: $0 [--port PORT] [--unattended]"
+      exit 1
+      ;;
+  esac
+done
+
+# Helper functions
+info() {
+  echo -e "${BLUE}==>${NC} $*"
+}
+
+success() {
+  echo -e "${GREEN}✓${NC} $*"
+}
+
+warning() {
+  echo -e "${YELLOW}⚠${NC} $*"
+}
+
+error() {
+  echo -e "${RED}✗${NC} $*" >&2
+}
+
+fatal() {
+  error "$*"
+  exit 1
+}
+
+# Check if we're on macOS
+OS_NAME=$(uname -s)
+if [[ "${OS_NAME}" != "Darwin" ]]; then
+  fatal "This script is only for macOS. Use systemd on Linux."
+fi
+
+# Check if headroom is installed
+info "Checking for headroom installation..."
+HEADROOM_PATH=$(command -v headroom || true)
+if [[ -z "${HEADROOM_PATH}" ]]; then
+  fatal "headroom not found in PATH. Please install it first: pip install headroom-ai[proxy]"
+fi
+success "Found headroom at: ${HEADROOM_PATH}"
+
+# Verify proxy support
+info "Verifying proxy support..."
+if ! "${HEADROOM_PATH}" proxy --help >/dev/null 2>&1; then
+  fatal "headroom proxy command not available. Install with: pip install headroom-ai[proxy]"
+fi
+success "Proxy support verified"
+
+# Check if service is already installed
+if [[ -f "${PLIST_DEST}" ]]; then
+  warning "LaunchAgent already installed at: ${PLIST_DEST}"
+
+  # Check if service is running
+  if launchctl print "gui/${USER_UID}/${PLIST_LABEL}" >/dev/null 2>&1; then
+    info "Stopping existing service..."
+    launchctl bootout "gui/${USER_UID}/${PLIST_LABEL}" 2>/dev/null || true
+  fi
+
+  if [[ "${UNATTENDED}" == false ]]; then
+    read -rp "Reinstall? [y/N] " response
+    if [[ ! "${response}" =~ ^[Yy]$ ]]; then
+      echo "Installation cancelled."
+      exit 0
+    fi
+  fi
+fi
+
+# Get port configuration
+if [[ -n "${CUSTOM_PORT}" ]]; then
+  PORT="${CUSTOM_PORT}"
+elif [[ "${UNATTENDED}" == true ]]; then
+  PORT="${DEFAULT_PORT}"
+else
+  read -rp "Port for proxy server (default: ${DEFAULT_PORT}): " PORT
+  PORT="${PORT:-${DEFAULT_PORT}}"
+fi
+
+# Validate port number
+if ! [[ "${PORT}" =~ ^[0-9]+$ ]] || [[ "${PORT}" -lt 1024 ]] || [[ "${PORT}" -gt 65535 ]]; then
+  fatal "Invalid port number: ${PORT} (must be 1024-65535)"
+fi
+
+# Check if port is in use
+if lsof -iTCP:"${PORT}" -sTCP:LISTEN -t >/dev/null 2>&1; then
+  warning "Port ${PORT} is already in use"
+  if [[ "${UNATTENDED}" == false ]]; then
+    read -rp "Continue anyway? [y/N] " response
+    if [[ ! "${response}" =~ ^[Yy]$ ]]; then
+      echo "Installation cancelled."
+      exit 0
+    fi
+  fi
+fi
+
+# Create log directory
+info "Creating log directory..."
+mkdir -p "${LOG_DIR}"
+success "Log directory: ${LOG_DIR}"
+
+# Find template file
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATE_FILE="${SCRIPT_DIR}/${PLIST_FILENAME}.template"
+
+if [[ ! -f "${TEMPLATE_FILE}" ]]; then
+  fatal "Template file not found: ${TEMPLATE_FILE}"
+fi
+
+# Generate plist from template
+info "Generating LaunchAgent plist..."
+sed -e "s|__HEADROOM_PATH__|${HEADROOM_PATH}|g" \
+  -e "s|__PORT__|${PORT}|g" \
+  -e "s|__HOME__|${HOME}|g" \
+  "${TEMPLATE_FILE}" >"${PLIST_DEST}"
+
+success "Created: ${PLIST_DEST}"
+
+# Set correct permissions
+chmod 644 "${PLIST_DEST}"
+
+# Load the LaunchAgent
+info "Loading LaunchAgent..."
+if launchctl bootstrap "gui/${USER_UID}" "${PLIST_DEST}" 2>/dev/null; then
+  success "LaunchAgent loaded successfully"
+else
+  # If bootstrap fails, try to bootout first in case it was already loaded
+  launchctl bootout "gui/${USER_UID}/${PLIST_LABEL}" 2>/dev/null || true
+  if launchctl bootstrap "gui/${USER_UID}" "${PLIST_DEST}"; then
+    success "LaunchAgent loaded successfully"
+  else
+    fatal "Failed to load LaunchAgent. Check logs at: ${LOG_DIR}"
+  fi
+fi
+
+# Wait a moment for service to start
+sleep 2
+
+# Verify the service is running
+info "Verifying service status..."
+if launchctl print "gui/${USER_UID}/${PLIST_LABEL}" >/dev/null 2>&1; then
+  success "Service is running"
+
+  # Check if port is listening
+  if lsof -iTCP:"${PORT}" -sTCP:LISTEN -t >/dev/null 2>&1; then
+    success "Port ${PORT} is listening"
+  else
+    warning "Service is running but port ${PORT} is not listening yet"
+    warning "Check logs: tail -f ${LOG_DIR}/proxy-error.log"
+  fi
+else
+  fatal "Service failed to start. Check logs at: ${LOG_DIR}"
+fi
+
+# Display success message
+echo ""
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN}✓ Headroom proxy installed successfully!${NC}"
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo "Service details:"
+echo "  • Port: ${PORT}"
+echo "  • Logs: ${LOG_DIR}"
+echo "  • Label: ${PLIST_LABEL}"
+echo ""
+echo "Shell integration:"
+echo "  Add to ~/.bashrc or ~/.zshrc:"
+echo ""
+echo "    export HEADROOM_PROXY_PORT=${PORT}"
+echo "    source <path-to>/shell-integration.sh"
+echo ""
+echo "  Or manually set:"
+echo ""
+echo "    export ANTHROPIC_BASE_URL=http://localhost:${PORT}"
+echo ""
+echo "Useful commands:"
+echo "  • Check status:  launchctl print gui/\${USER_UID}/${PLIST_LABEL}"
+echo "  • View logs:     tail -f ${LOG_DIR}/proxy.log"
+echo "  • View errors:   tail -f ${LOG_DIR}/proxy-error.log"
+echo "  • Restart:       launchctl kickstart -k gui/\${USER_UID}/${PLIST_LABEL}"
+echo "  • Uninstall:     ./uninstall.sh"
+echo ""
@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+#
+# Headroom Proxy Shell Integration
+#
+# Automatically sets ANTHROPIC_BASE_URL if the headroom proxy is running.
+# Supports both bash and zsh.
+#
+# Usage:
+#   Add to ~/.bashrc or ~/.zshrc:
+#
+#     export HEADROOM_PROXY_PORT=8787  # Optional: customize port (default: 8787)
+#     source /path/to/shell-integration.sh
+#
+# This script will:
+#   1. Check if the proxy is running on the configured port
+#   2. If running, set ANTHROPIC_BASE_URL
+#   3. If not running, try to start the LaunchAgent
+#   4. Provide helpful status messages (only on first load)
+#
+
+# Configuration: Port can be customized via environment variable
+HEADROOM_PROXY_PORT="${HEADROOM_PROXY_PORT:-8787}"
+HEADROOM_PLIST_LABEL="com.headroom.proxy"
+USER_UID=$(id -u)
+
+# Prevent duplicate loading (bash and zsh compatible)
+if [[ -n "${HEADROOM_SHELL_INTEGRATION_LOADED:-}" ]]; then
+  return 0
+fi
+export HEADROOM_SHELL_INTEGRATION_LOADED=1
+
+# Check if proxy is running (fast path using lsof)
+_headroom_proxy_running() {
+  lsof -iTCP:"${HEADROOM_PROXY_PORT}" -sTCP:LISTEN -t >/dev/null 2>&1
+}
+
+# Try to start the LaunchAgent if not running
+_headroom_start_proxy() {
+  local plist_path="${HOME}/Library/LaunchAgents/${HEADROOM_PLIST_LABEL}.plist"
+
+  # Check if LaunchAgent is installed
+  if [[ ! -f "${plist_path}" ]]; then
+    return 1
+  fi
+
+  # Try to bootstrap the LaunchAgent (idempotent - won't fail if already loaded)
+  if launchctl bootstrap "gui/${USER_UID}" "${plist_path}" 2>/dev/null; then
+    # Wait a moment for service to start
+    sleep 1
+    return 0
+  fi
+
+  return 1
+}
+
+# Main logic
+if _headroom_proxy_running; then
+  # Proxy is running - set ANTHROPIC_BASE_URL
+  export ANTHROPIC_BASE_URL="http://localhost:${HEADROOM_PROXY_PORT}"
+else
+  # Proxy not running - try to start it
+  if _headroom_start_proxy && _headroom_proxy_running; then
+    # Successfully started - set ANTHROPIC_BASE_URL
+    export ANTHROPIC_BASE_URL="http://localhost:${HEADROOM_PROXY_PORT}"
+    echo "✓ Headroom proxy started on port ${HEADROOM_PROXY_PORT}"
+  else
+    # Could not start - provide helpful message
+    echo "⚠ Headroom proxy not running on port ${HEADROOM_PROXY_PORT}"
+    echo "  Install with: cd /path/to/headroom/examples/deployment/macos-launchagent && ./install.sh"
+  fi
+fi
+
+# Cleanup helper functions (don't pollute shell namespace)
+unset -f _headroom_proxy_running _headroom_start_proxy
@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+#
+# Headroom Proxy LaunchAgent Uninstaller for macOS
+#
+# This script removes the headroom proxy LaunchAgent and optionally cleans up logs.
+#
+# Usage: ./uninstall.sh [--remove-logs]
+#
+# Options:
+#   --remove-logs     Remove log directory (prompts if not specified)
+#
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+PLIST_LABEL="com.headroom.proxy"
+PLIST_FILENAME="${PLIST_LABEL}.plist"
+PLIST_PATH="${HOME}/Library/LaunchAgents/${PLIST_FILENAME}"
+LOG_DIR="${HOME}/Library/Logs/headroom"
+USER_UID=$(id -u)
+
+# Parse command line arguments
+REMOVE_LOGS=false
+UNATTENDED=false
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --remove-logs)
+      REMOVE_LOGS=true
+      shift
+      ;;
+    --unattended)
+      UNATTENDED=true
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1"
+      echo "Usage: $0 [--remove-logs] [--unattended]"
+      exit 1
+      ;;
+  esac
+done
+
+# Helper functions
+info() {
+  echo -e "${BLUE}==>${NC} $*"
+}
+
+success() {
+  echo -e "${GREEN}✓${NC} $*"
+}
+
+warning() {
+  echo -e "${YELLOW}⚠${NC} $*"
+}
+
+error() {
+  echo -e "${RED}✗${NC} $*" >&2
+}
+
+# Check if we're on macOS
+OS_NAME=$(uname -s)
+if [[ "${OS_NAME}" != "Darwin" ]]; then
+  error "This script is only for macOS."
+  exit 1
+fi
+
+# Check if LaunchAgent is installed
+if [[ ! -f "${PLIST_PATH}" ]]; then
+  warning "LaunchAgent not found at: ${PLIST_PATH}"
+  warning "Nothing to uninstall"
+  exit 0
+fi
+
+# Check if service is running and stop it
+info "Checking service status..."
+if launchctl print "gui/${USER_UID}/${PLIST_LABEL}" >/dev/null 2>&1; then
+  info "Stopping service..."
+  if launchctl bootout "gui/${USER_UID}/${PLIST_LABEL}" 2>/dev/null; then
+    success "Service stopped"
+  else
+    warning "Could not stop service (it may not be running)"
+  fi
+else
+  info "Service is not running"
+fi
+
+# Remove plist file
+info "Removing LaunchAgent plist..."
+if rm -f "${PLIST_PATH}"; then
+  success "Removed: ${PLIST_PATH}"
+else
+  error "Failed to remove: ${PLIST_PATH}"
+  exit 1
+fi
+
+# Handle log directory
+if [[ -d "${LOG_DIR}" ]]; then
+  if [[ "${REMOVE_LOGS}" == true ]]; then
+    info "Removing log directory..."
+    if rm -rf "${LOG_DIR}"; then
+      success "Removed: ${LOG_DIR}"
+    else
+      warning "Failed to remove: ${LOG_DIR}"
+    fi
+  elif [[ "${UNATTENDED}" == false ]]; then
+    read -rp "Remove log directory at ${LOG_DIR}? [y/N] " response
+    if [[ "${response}" =~ ^[Yy]$ ]]; then
+      if rm -rf "${LOG_DIR}"; then
+        success "Removed: ${LOG_DIR}"
+      else
+        warning "Failed to remove: ${LOG_DIR}"
+      fi
+    else
+      info "Log directory preserved at: ${LOG_DIR}"
+    fi
+  else
+    info "Log directory preserved at: ${LOG_DIR}"
+  fi
+else
+  info "No log directory found"
+fi
+
+# Display success message
+echo ""
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN}✓ Headroom proxy uninstalled successfully!${NC}"
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo "Next steps:"
+echo "  • Remove shell integration from ~/.bashrc or ~/.zshrc"
+echo "  • Remove or comment out: export ANTHROPIC_BASE_URL=..."
+echo "  • Remove or comment out: source <path-to>/shell-integration.sh"
+echo ""
+if [[ "${REMOVE_LOGS}" == false ]] && [[ -d "${LOG_DIR}" ]]; then
+  echo "Log directory still exists at: ${LOG_DIR}"
+  echo "  • Remove manually with: rm -rf ${LOG_DIR}"
+  echo ""
+fi