@wenathlan/saddle 1.8.17 → 2.0.2

package/docs/plans/36.computational.memory.md

@@ -1,340 +0,0 @@
-# Saddle Computational Memory System
-
-> Transform storage memory into computational memory (RAM, GPU).
-> Unlimited memory through repository buckets and external storage.
-
-## Overview
-
-The saddle robot implements a unique computational memory
-architecture that transforms storage memory (files, blobs,
-assets in repositories) into computational memory (RAM, GPU
-VRAM) for processing. This enables effectively unlimited
-memory for AI agent operations.
-
-## Memory Architecture
-
-### Layer Diagram
-
-```
-┌─────────────────────────────────────────────────────┐
-│                 Computation Layer                      │
-│                   (RAM / GPU)                        │
-│                                                      │
-│    Processing   │   Inference   │   Cache            │
-│                  │   (ML Models)  │                   │
-├─────────────────────────────────────────────────────┤
-│              Memory Engine (Bridge)                  │
-│                                                      │
-│    Load  │  Transform  │  Process  │  Persist       │
-├─────────────────────────────────────────────────────┤
-│                Storage Layer                        │
-│                                                      │
-│    Repositories │  HF Buckets │  Kaggle │  S3      │
-└─────────────────────────────────────────────────────┘
-```
-
-### Memory Transformation Flow
-
-```
-1. Storage Object (file/blob in repo)
-       │
-       ▼
-2. Memory Engine loads object
-       │
-       ▼
-3. Object parsed into memory buffer
-       │
-       ▼
-4. Memory buffer mapped to virtual RAM
-       │
-       ▼
-5. Computation performed on virtual RAM
-       │
-       ▼
-6. Results written back to storage
-       │
-       ▼
-7. Storage object updated
-```
-
-## Storage Targets
-
-### Repository Storage (Primary)
-
-GitHub/GitLab/Forgejo/Gitea repositories serve as the
-primary storage buckets. Files, assets, and releases are
-used as memory objects.
-
-```typescript
-interface RepoStorageTarget {
-  platform: 'github' | 'gitlab' | 'forgejo' | 'gitea'
-  owner: string
-  repo: string
-  branch: string
-  path: string
-  token: string
-}
-```
-
-### Hugging Face Storage
-
-Hugging Face Spaces and Repositories as memory backends.
-
-```typescript
-interface HFStorageTarget {
-  type: 'huggingface'
-  space: string
-  token: string
-  revision: string
-}
-```
-
-### Kaggle Storage
-
-Kaggle datasets and notebooks as memory storage targets.
-
-```typescript
-interface KaggleStorageTarget {
-  type: 'kaggle'
-  dataset: string
-  token: string
-  ssl_verification: boolean
-}
-```
-
-### ModelScope Storage
-
-ModelScope repositories for ML model memory storage.
-
-```typescript
-interface ModelScopeStorageTarget {
-  type: 'modelscope'
-  namespace: string
-  repo: string
-  token: string
-}
-```
-
-### Terabox and File Hostings
-
-Generic file hosting as storage backend for raw memory data.
-
-```typescript
-interface FileHostingStorageTarget {
-  type: 'filehosting'
-  host: string
-  path: string
-  token: string
-  method: 'upload' | 's3compatible' | 'webdav'
-}
-```
-
-## Memory Engine Implementation
-
-### Core Class
-
-```typescript
-class MemoryEngine {
-  private storage: Map<string, MemoryObject>
-  private backends: StorageBackend[]
-
-  constructor(config: MemoryEngineConfig) {
-    this.backends = config.backends.map(
-      (backend) => StorageBackendFactory.create(backend)
-    )
-  }
-
-  async load(key: string): Promise<MemoryObject | null> {
-    try {
-      for (const backend of this.backends) {
-        const object = await backend.load(key)
-        if (object !== null) {
-          return this.transformToCompute(object)
-        }
-      }
-      return null
-    } catch (error) {
-      throw new Error(
-        `MemoryEngine.load failed for key "${key}": ${error.message}`
-      )
-    }
-  }
-
-  async persist(
-    key: string,
-    data: ComputeResult
-  ): Promise<boolean> {
-    try {
-      const storageObject = this.transformToStorage(data)
-      for (const backend of this.backends) {
-        await backend.save(key, storageObject)
-      }
-      return true
-    } catch (error) {
-      throw new Error(
-        `MemoryEngine.persist failed for key "${key}": ${error.message}`
-      )
-    }
-  }
-
-  private transformToCompute(
-    object: StorageObject
-  ): MemoryObject {
-    const buffer = Buffer.from(object.data)
-
-    return {
-      id: object.key,
-      buffer: buffer,
-      size: buffer.byteLength,
-      type: object.mimeType,
-      createdAt: new Date(),
-    }
-  }
-
-  private transformToStorage(
-    result: ComputeResult
-  ): StorageObject {
-    return {
-      key: result.id,
-      data: result.payload,
-      mimeType: result.mimeType ?? 'application/octet-stream',
-      metadata: result.metadata,
-    }
-  }
-
-  release(key: string): Promise<void> {
-    this.storage.delete(key)
-    return Promise.resolve()
-  }
-}
-```
-
-### Memory Object Interface
-
-```typescript
-interface MemoryObject {
-  id: string
-  buffer: Buffer
-  size: number
-  type: string
-  createdAt: Date
-  metadata?: Record<string, unknown>
-}
-```
-
-### Compute Result Interface
-
-```typescript
-interface ComputeResult {
-  id: string
-  payload: string | Buffer | object
-  mimeType?: string
-  metadata?: Record<string, unknown>
-  processingTimeMs: number
-  memoryUsedBytes: number
-}
-```
-
-## Computational Memory Use Cases
-
-### Use Case 1: Large File Processing
-
-Load a large file from repository storage into virtual RAM,
-process it, and write results back.
-
-```
-repo://my-repo/large-file.bin
-    → Memory Engine loads into buffer (virtual RAM)
-    → Processing pipeline transforms buffer
-    → Results written back to repo
-```
-
-### Use Case 2: ML Model Inference
-
-Store ML model weights in repository storage, load into
-GPU VRAM for inference, persist results.
-
-```
-repo://models/my-model/weights.bin
-    → Memory Engine loads into GPU buffer
-    → Inference engine processes
-    → Results stored as repo artifacts
-```
-
-### Use Case 3: Browser Session Memory
-
-Capture browser sessions as JSON, store in repo, replay
-on another machine with full session memory.
-
-```
-repo://saddle/sessions/session-001.json
-    → Memory Engine loads session log
-    → Browser engine replays movements
-    → Execution results stored back
-```
-
-## Performance Characteristics
-
-| Aspect | Metric | Notes |
-|--------|--------|-------|
-| Load latency | Depends on storage backend | Local storage fastest |
-| Process throughput | Depends on compute layer | RAM fastest, storage limited |
-| Persist latency | Depends on storage backend | Batch writes preferred |
-| Memory overhead | ~2x storage size | Buffer + metadata |
-| Max capacity | Effectively unlimited | Bounded by storage targets |
-
-## Error Handling
-
-The memory engine implements try-catch around all storage
-operations with contextual error logging for later tracing.
-
-```typescript
-async safeLoad<T>(
-  key: string
-): Promise<{ success: boolean; data?: T; error?: string }> {
-  try {
-    const result = await this.load(key)
-    return { success: true, data: result as T }
-  } catch (error) {
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : 'Unknown error',
-    }
-  }
-}
-```
-
-## Storage Backend Factory
-
-```typescript
-class StorageBackendFactory {
-  static create(config: StorageConfig): StorageBackend {
-    switch (config.type) {
-      case 'github':
-        return new GitHubStorageBackend(config)
-      case 'gitlab':
-        return new GitLabStorageBackend(config)
-      case 'forgejo':
-        return new ForgejoStorageBackend(config)
-      case 'gitea':
-        return new GiteaStorageBackend(config)
-      case 'huggingface':
-        return new HFStorageBackend(config)
-      case 'kaggle':
-        return new KaggleStorageBackend(config)
-      case 'modelscope':
-        return new ModelScopeStorageBackend(config)
-      case 'filehosting':
-        return new FileHostingStorageBackend(config)
-      default:
-        throw new Error(
-          `Unknown storage type "${config.type}"`
-        )
-    }
-  }
-}
-```
-
-## License
-
-MIT

package/docs/plans/37.deploystrategy.md

@@ -1,394 +0,0 @@
-# Saddle Deploy Strategy
-
-> Deploy strategies for the saddle robot across Netlify, Vercel,
-> GitHub Actions, GitLab CI, Forgejo, and self-hosted infrastructure.
-
-## Overview
-
-Saddle robot supports multiple deployment strategies to make the bot
-available across platforms. Each strategy uses HTTPS communication
-between deployed sites for coordination and data transfer.
-
-## Strategy 1: Netlify
-
-Netlify provides serverless functions and static hosting for the
-saddle robot web interface.
-
-### Configuration
-
-```toml
-# netlify.toml
-[build]
-  publish = "dist"
-  command = "npm run build"
-
-[[redirects]]
-  from = "/api/*"
-  to = "/.netlify/functions/:splat"
-  status = 200
-
-[[headers]]
-  for = "/*"
-  [headers.values]
-    X-Frame-Options = "DENY"
-    X-Content-Type-Options = "nosniff"
-```
-
-### Environment Variables
-
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `SBOT_TOKEN` | GitHub/GitLab bot token | Yes |
-| `SBOT_PLATFORM` | Target platform (github, gitlab, forgejo, gitea) | Yes |
-| `SBOT_MEMORY_BUCKET` | Storage bucket for memory persistence | Yes |
-| `SBOT_WEBHOOK_SECRET` | Webhook signature secret | Yes |
-| `SBOT_CDN_URL` | SCDN endpoint for static assets | No |
-
-### Deploy Command
-
-```bash
-# Deploy to Netlify
-netlify deploy --prod
-# Deploy to Netlify staging
-netlify deploy --context deploy-preview
-```
-
-## Strategy 2: Vercel
-
-Vercel provides edge functions and instant deployment for the
-saddle robot backend.
-
-### Configuration
-
-```json
-// vercel.json
-{
-  "version": 2,
-  "builds": [
-    {
-      "src": "web/index.js",
-      "use": "@vercel/node"
-    },
-    {
-      "src": "web/api/*.js",
-      "use": "@vercel/node"
-    }
-  ],
-  "routes": [
-    {
-      "src": "/api/(.*)",
-      "dest": "/web/api/$1"
-    }
-  ]
-}
-```
-
-### Environment Variables
-
-Same as Netlify strategy. Add Vercel-specific:
-
-| Variable | Description |
-|----------|-------------|
-| `VERCEL_REGION` | Edge region for deployment |
-| `SBOT_MEMORY_ENGINE` | Memory engine type (ram, storage, bucket) |
-
-## Strategy 3: GitHub Actions Pipeline
-
-Use GitHub Actions to deploy and run the saddle robot as a
-scheduled or triggered workflow.
-
-### Workflow File
-
-```yaml
-# .github/workflows/saddle-robot.yml
-name: Saddle Robot Automation
-
-on:
-  schedule:
-    - cron: '*/15 * * * *'
-  workflow_dispatch:
-  push:
-    paths:
-      - 'saddle-robot/**'
-      - '.saddle/config.yml'
-
-permissions:
-  contents: read
-  pull-requests: write
-  issues: write
-  actions: write
-
-env:
-  SBOT_PLATFORM: github
-  SBOT_MEMORY_BUCKET: ${{ secrets.MEMORY_BUCKET }}
-  SBOT_WEBHOOK_SECRET: ${{ secrets.WEBHOOK_SECRET }}
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci --production
-
-      - name: Run saddle robot
-        run: node saddle-robot/index.js
-        env:
-          SBOT_API_TOKEN: ${{ secrets.SBOT_TOKEN }}
-          SBOT_MEMORY_ENGINE: storage
-
-      - name: Upload memory artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: memory-logs
-          path: |
-            .saddle/logs/*.json
-          retention-days: 30
-
-  deploy-to-netlify:
-    needs: [deploy]
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main'
-    steps:
-      - uses: jsmrcaga/action-netlify-deploy@v2.5.1
-        with:
-          netlify_auth_token: ${{ secrets.NETLIFY_TOKEN }}
-          netlify_site_id: ${{ secrets.NETLIFY_SITE_ID }}
-          deploy_message: 'Saddle robot auto-deploy'
-```
-
-### GitHub App Configuration
-
-Create a GitHub App for the saddle robot with these permissions:
-
-| Permission | Access |
-|------------|--------|
-| Contents | Read/Write |
-| Pull Requests | Read/Write |
-| Issues | Read/Write |
-| Actions | Read/Write |
-| Metadata | Read |
-| Webhooks | Manage |
-
-## Strategy 4: GitLab CI/CD
-
-Use GitLab CI/CD pipelines for the saddle robot on GitLab
-instances (self-hosted or GitLab.com).
-
-### GitLab CI Configuration
-
-```yaml
-# .gitlab-ci.yml
-stages:
-  - deploy
-  - execute
-  - store
-
-deploy-saddle:
-  stage: deploy
-  script:
-    - npm ci --production
-    - npm run build
-  artifacts:
-    paths:
-      - dist/
-    expire_in: 1 hour
-
-execute-saddle-robot:
-  stage: execute
-  script:
-    - node saddle-robot/index.js
-    - cat .saddle/logs/*.json
-  artifacts:
-    paths:
-      - .saddle/logs/
-    expire_in: 7 days
-  variables:
-    SBOT_PLATFORM: gitlab
-    SBOT_MEMORY_ENGINE: storage
-
-store-memory-results:
-  stage: store
-  script:
-    - |
-      # Upload results to storage backend
-      curl -X POST "${SBOT_MEMORY_BUCKET_URL}/upload" \
-        -H "Authorization: Bearer ${MEMORY_BUCKET_TOKEN}" \
-        -F "file=@.saddle/logs/results.json"
-  when: always
-```
-
-## Strategy 5: Forgejo Actions
-
-Forgejo supports GitHub-compatible workflows. Use the same
-configuration as GitHub Actions with Forgejo-specific adjustments.
-
-### Forgejo Workflow
-
-```yaml
-# .forgejo/workflows/saddle.yaml
-name: Saddle Robot
-
-on:
-  schedule:
-    - cron: '*/15 * * * *'
-  push:
-    branches: [main]
-
-jobs:
-  run-saddle:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: forgejo/actions/checkout@v1
-      - uses: forgejo/actions/setup-node@v1
-        with:
-          node-version: '20'
-      - run: npm ci --production
-      - run: node saddle-robot/index.js
-```
-
-## Strategy 6: Gitea Actions
-
-Gitea supports webhook-based workflows. Configure Gitea Actions
-for the saddle robot.
-
-### Gitea Configuration
-
-```yaml
-# .gitea/workflows/saddle.yml
-name: saddle-robot
-
-on:
-  schedule:
-    - cron: '*/15 * * * *'
-  push:
-    branches: ['main']
-
-jobs:
-  execute:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: gitea/actions/setup-node@v1
-        with:
-          node-version: '20'
-      - run: npm ci --production
-      - run: node saddle-robot/index.js
-```
-
-## Strategy 7: Docker/VM Self-Hosted
-
-Full containerized deployment for maximum control and resource access.
-
-### Docker Compose
-
-```yaml
-# docker-compose.yml
-version: '3.8'
-
-services:
-  saddle-robot:
-    build:
-      context: .
-      dockerfile: Dockerfile.saddle
-    container_name: saddle-robot
-    ports:
-      - "3000:3000"
-    environment:
-      - SBOT_PLATFORM=auto
-      - SBOT_MEMORY_ENGINE=storage
-      - SBOT_MEMORY_BUCKET_URL=${MEMORY_BUCKET_URL}
-      - SBOT_API_TOKEN=${SBOT_TOKEN}
-      - SBOT_WEBHOOK_SECRET=${WEBHOOK_SECRET}
-    volumes:
-      - ./saddle-data:/app/data
-      - ./saddle-logs:/app/logs
-    restart: unless-stopped
-    depends_on:
-      - saddle-db
-
-  saddle-db:
-    image: mysql:8.0
-    container_name: saddle-db
-    environment:
-      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
-      MYSQL_DATABASE: saddle
-      MYSQL_USER: saddle_user
-      MYSQL_PASSWORD: ${DB_USER_PASSWORD}
-    volumes:
-      - saddle-db-data:/var/lib/mysql
-    ports:
-      - "3306:3306"
-
-volumes:
-  saddle-db-data:
-```
-
-### Dockerfile
-
-```dockerfile
-FROM node:20-slim
-
-RUN apt-get update && apt-get install -y \
-    chromium \
-    && rm -rf /var/lib/apt/lists/*
-
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm ci --production
-
-COPY . .
-
-EXPOSE 3000
-
-HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
-  CMD curl -f http://localhost:3000/health || exit 1
-
-CMD ["node", "saddle-robot/index.js"]
-```
-
-## HTTPS Communication Between Sites
-
-All cross-site communication uses HTTPS with proper certificate
-validation. The saddle robot uses HTTPS for:
-
-1. Webhook endpoints between deployed sites
-2. API calls to GitHub/GitLab/Forgejo/Gitea
-3. Storage bucket communication (HF/Kaggle/ModelScope/Terabox)
-4. SCDN asset delivery
-5. Internal service mesh communication
-
-### Certificate Management
-
-```typescript
-interface SSLOptions {
-  cert: string
-  key: string
-  ca?: string
-  rejectUnauthorized: boolean
-  minVersion: 'TLSv1.2' | 'TLSv1.3'
-}
-```
-
-## Decision Matrix
-
-| Strategy | Use Case | Pros | Cons |
-|----------|----------|------|------|
-| Netlify | Static web + edge functions | Fast, free tier | Limited runtime |
-| Vercel | Serverless edge runtime | Global edge | Vendor lock-in |
-| GitHub Actions | CI/CD integrated bot | Native GitHub | Time limits |
-| GitLab CI | Self-hosted or cloud CI | Full control | Self-hosted needs infra |
-| Forgejo | Self-hosted lightweight | Minimal footprint | Smaller ecosystem |
-| Gitea | Self-hosted minimal | Very lightweight | Limited integrations |
-| Docker/VM | Full control deployment | All resources | Requires infra management |
-
-## License
-
-MIT