Skip to content

skill_human.md

Latest commit

 

History

History
373 lines (278 loc) · 9.87 KB

skill_human.md

File metadata and controls

373 lines (278 loc) · 9.87 KB

ByeFast — Human Operator Guide

A practical reference for developers running, debugging, and building on ByeFast.

Quick Start

# Build (release — optimised, ~15 MB binary)
cargo build --release

# Run
./target/release/byefast
# → listening on http://0.0.0.0:8741

# Or with persistent storage
BYEFAST_STORAGE_PATH=./byefast.db ./target/release/byefast

Windows:

cargo build --release
.\target\release\byefast.exe

Environment Variables

Variable Default Description
BYEFAST_ADDR 0.0.0.0:8741 Bind address
BYEFAST_STORAGE_PATH (ephemeral) Path for sled DB. Omit = in-memory, no persistence
BYEFAST_MAX_PAGES 1000 Hard limit on concurrent pages
BYEFAST_LOG byefast=info,... Log level filter (tracing format)

Useful log levels:

# See every event on the bus (very verbose)
BYEFAST_LOG=byefast=debug,bye_api=debug,bye_js=debug ./byefast

# Quiet — errors only
BYEFAST_LOG=error ./byefast

# Default — info + debug kernel events
BYEFAST_LOG="byefast=info,bye_api=info,bye_kernel=debug,tower_http=warn" ./byefast

Measure Cold-Start Time

Linux/macOS:

time ./target/release/byefast &
sleep 0.1
curl -s http://localhost:8741/health

Windows (PowerShell):

$start = Get-Date
Start-Process -FilePath ".\byefast.exe" -WindowStyle Minimized
do {
    Start-Sleep -Milliseconds 5
    $elapsed = (Get-Date) - $start
    try { Invoke-WebRequest "http://localhost:8741/health" -UseBasicParsing -ErrorAction Stop | Out-Null; break } catch {}
} while ($elapsed.TotalSeconds -lt 10)
Write-Host "Ready in: $([math]::Round($elapsed.TotalMilliseconds, 1)) ms"

Expected results:

Environment Internal startup Wall-clock
Linux (warm kernel) ~1.5 ms ~4 ms
Windows ~2.3 ms ~22 ms¹

¹ Windows adds ~12 ms process-creation overhead before the first instruction runs — this is OS cost, not ByeFast cost.

Basic Usage via curl

BASE="http://localhost:8741"

# Spawn a page
PAGE=$(curl -s -X POST $BASE/pages \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq -r .page_id)

echo "Page: $PAGE"

# Inject HTML
curl -s -X POST $BASE/pages/$PAGE/load-html \
  -H "Content-Type: application/json" \
  -d '{"html":"<html><head><title>Test</title></head><body><h1>Hello</h1><a href=\"/about\">About</a><button>Click me</button></body></html>"}'

# Read semantic map
curl -s $BASE/pages/$PAGE/semantic-action-map | jq .

# Find element by intent
curl -s -X POST $BASE/pages/$PAGE/vision/reindex
curl -s -X POST $BASE/pages/$PAGE/vision/find \
  -H "Content-Type: application/json" \
  -d '{"intent": "click me button"}' | jq .

# Execute JS
curl -s -X POST $BASE/pages/$PAGE/eval \
  -H "Content-Type: application/json" \
  -d '{"script": "document.title()", "timeout_ms": 3000}' | jq .

# Save snapshot
SNAP=$(curl -s -X POST $BASE/pages/$PAGE/snapshots | jq -r .snapshot_id)

# Restore snapshot
curl -s -X POST $BASE/pages/$PAGE/snapshots/$SNAP | jq .

# Destroy page
curl -s -X DELETE $BASE/pages/$PAGE

PowerShell Usage

$BASE = "http://localhost:8741"

# Helper function
function Bye($method, $path, $body = $null) {
    $params = @{
        Method = $method
        Uri = "$BASE$path"
        UseBasicParsing = $true
    }
    if ($body) {
        $params.ContentType = "application/json"
        $params.Body = ($body | ConvertTo-Json -Depth 5)
    }
    (Invoke-WebRequest @params).Content | ConvertFrom-Json
}

# Spawn page
$page = Bye POST /pages @{ url = "https://example.com"; idle_timeout_ms = 600000 }
$PAGE = $page.page_id
Write-Host "Page: $PAGE"

# Inject HTML
Bye POST /pages/$PAGE/load-html @{
    html = "<html><head><title>My Page</title></head><body><button>Submit</button></body></html>"
}

# Read page
Bye GET /pages/$PAGE/semantic-action-map

# Find element
Bye POST /pages/$PAGE/vision/reindex
Bye POST /pages/$PAGE/vision/find @{ intent = "submit button" }

# Execute JavaScript
Bye POST /pages/$PAGE/eval @{ script = "document.title()"; timeout_ms = 3000 }

Debugging DOM Problems

Problem: elements: [] after navigate

The background HTTP fetch may have failed (bot protection, TLS issue, redirect). Check the trace:

curl -s http://localhost:8741/pages/$PAGE/trace | jq '[.[] | select(.event | contains("Failed") or contains("Error"))]'

Fix: inject HTML directly instead:

HTML=$(curl -s https://example.com)
curl -s -X POST http://localhost:8741/pages/$PAGE/load-html \
  -H "Content-Type: application/json" \
  -d "{\"html\": $(echo $HTML | jq -Rs .)}"

Problem: vision/find returns confidence: 0.0

Vision index is empty or stale. Always reindex after loading HTML:

curl -s -X POST http://localhost:8741/pages/$PAGE/vision/reindex
# Then find
curl -s -X POST http://localhost:8741/pages/$PAGE/vision/find \
  -H "Content-Type: application/json" \
  -d '{"intent": "your intent here"}'

Problem: JS eval returns TypeError: not a callable function

document.write requires document.open() first:

{"script": "document.open(); document.write('<h1>Hello</h1>'); document.close(); document.title()"}

Or just use load-html — it's simpler and faster.

Problem: Page keeps suspending

Increase idle_timeout_ms at spawn time:

curl -s -X POST http://localhost:8741/pages \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com", "idle_timeout_ms": 3600000}'

Or resume it manually:

curl -s -X POST http://localhost:8741/pages/$PAGE/resume

Flight Recorder (Event Trace)

Every event that fires on the EventBus for a page is recorded. Useful for understanding exactly what happened:

# Full trace
curl -s http://localhost:8741/pages/$PAGE/trace | jq .

# Filter for specific event types
curl -s http://localhost:8741/pages/$PAGE/trace | \
  jq '[.[] | select(.event | contains("ScriptEval"))]'

# Filter for failures
curl -s http://localhost:8741/pages/$PAGE/trace | \
  jq '[.[] | select(.event | contains("Failed") or contains("Crash"))]'

Capability System

Some features require explicit capability grants:

curl -s -X POST http://localhost:8741/pages/$PAGE/capabilities/request \
  -H "Content-Type: application/json" \
  -d '{"capabilities": ["SemanticActionMap", "IndexedDb", "Screenshot"]}'

Available capabilities: Clipboard Geolocation MediaDevices Notifications PersistentStorage PopupWindows WebAssembly WebGL WebAudio IndexedDb SemanticActionMap Screenshot

Audit Log (Compliance / Replay)

Record every agent action with a verifiable Merkle proof:

# Start audit session
SID=$(curl -s -X POST http://localhost:8741/pages/$PAGE/audit/session \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r .session_id)

# Record an action
AID=$(curl -s -X POST http://localhost:8741/pages/$PAGE/audit/session/$SID/record \
  -H "Content-Type: application/json" \
  -d '{"action_type":"click","origin":"https://example.com","element":"checkout button","success":true}' | jq -r .action_id)

# Get cryptographic proof
curl -s http://localhost:8741/pages/$PAGE/audit/session/$SID/prove/$AID | jq .

# Full log
curl -s http://localhost:8741/pages/$PAGE/audit/session/$SID/log | jq .

Ghost Mode

If you control the target server, serve this at /.well-known/semantic-map.json to skip all JS execution:

{
  "title": "My App",
  "elements": [
    { "role": "button", "label": "Checkout", "action": "/checkout", "interactable": true },
    { "role": "textbox", "label": "Search", "interactable": true }
  ],
  "navigation": [
    { "text": "Home", "href": "/" },
    { "text": "Cart", "href": "/cart" }
  ]
}

ByeFast will detect it automatically on navigate and return results instantly with zero JS cost.

Performance Tuning

Goal Setting
Minimum memory footprint Don't set BYEFAST_STORAGE_PATH (ephemeral)
Fastest cold-start (Windows) Ephemeral mode avoids 7.6 ms sled mmap
Persistent cookies/snapshots BYEFAST_STORAGE_PATH=./byefast.db
High page count BYEFAST_MAX_PAGES=5000 (watch RAM)
Debug startup timing BYEFAST_LOG=byefast=debug

Running Tests

# All tests (unit + integration)
cargo test --workspace

# Just a specific crate
cargo test -p bye-dom
cargo test -p bye-js

# Integration tests only
cargo test -p byefast-tests

# With output
cargo test --workspace -- --nocapture

Project Structure Reference

crates/
  bye-event/      EventBus + Event enum (foundation — no workspace deps)
  bye-kernel/     Page lifecycle, VirtualClock, scheduler
  bye-dom/        DOM arena + HTML parser + IntentEngine
  bye-net/        HTTP/2 + TLS + cache + dedup
  bye-loader/     Priority DAG + Ghost Mode
  bye-js/         boa_engine runtime + polyfills + document bindings
  bye-layout/     Box-model layout engine
  bye-render/     Semantic differ (typed DOM change events)
  bye-storage/    Cookie jar + IndexedDB + zstd snapshots
  bye-safe/       Sandbox + capability grants + HumanitySimulator
  bye-api/        axum server (32 routes, flight recorder)
  bye-vision/     64-dim visual-semantic element matching
  bye-compositor/ Cross-origin page synthesis
  bye-audit/      Merkle-tree action audit log
  bye-evolve/     Self-healing shims + selector evolution
bin/byefast/    Entry point — wires engines, starts server
tests/          Integration test suite

Health Check

curl http://localhost:8741/health
# → {"engine":"ByeFast","status":"ok","version":"0.1.0"}

curl http://localhost:8741/stats
# → {"active_pages":3,"storage_bytes":0,"bus_receivers":1}

If health check fails, check:

  1. Is port 8741 already in use? netstat -an | grep 8741
  2. Did the process crash? Check the terminal window where byefast is running
  3. Firewall blocking local connections?