browser39 watch — Real-Time Agent IPC

browser39 watch monitors a JSONL commands file for new appended lines, processes each command through the browser engine, and writes results to an output file. This enables real-time, file-based communication between any agent process and browser39.

Usage

# Create the commands file (must exist before starting)
touch commands.jsonl

# Start watching
browser39 watch commands.jsonl --output results.jsonl

The watcher runs until it receives a quit action or the process is killed.

How it works

1. On startup, processes any existing lines in the commands file
2. Watches the file's parent directory for modifications (FSEvents on macOS, inotify on Linux)
3. On each modification, reads only new complete lines appended since the last read
4. Dispatches each command through the browser engine
5. Writes results atomically (single write() + fsync() per line) to the output file
6. Rotates the output file at 10MB

Partial lines (no trailing newline) are held until the next write completes them.

Appending commands

From another process (Python, shell, Node, etc.), append JSONL commands:

# Fetch a page
echo '{"id":"1","action":"fetch","v":1,"seq":1,"url":"https://example.com"}' >> commands.jsonl

# List links
echo '{"id":"2","action":"links","v":1,"seq":2}' >> commands.jsonl

# Follow a link by index
echo '{"id":"3","action":"fetch","v":1,"seq":3,"index":0}' >> commands.jsonl

# Navigate back
echo '{"id":"4","action":"back","v":1,"seq":4}' >> commands.jsonl

# Session info / heartbeat
echo '{"id":"5","action":"info","v":1,"seq":5}' >> commands.jsonl

# Shut down
echo '{"id":"6","action":"quit","v":1,"seq":6}' >> commands.jsonl

Command envelope

Every command line must be valid JSON with these fields:

{"id": "unique-id", "action": "fetch", "v": 1, "seq": 1, ...action fields}

The seq must be strictly greater than the previous command's seq. Out-of-order commands are rejected with INVALID_COMMAND.

Result envelope

Each result is one JSON line in the output file:

{"id": "unique-id", "ok": true, "seq": 1, ...result fields}

On error:

{"id": "unique-id", "ok": false, "seq": 1, "code": "NO_PAGE", "error": "no page loaded"}

Available actions

See jsonl-protocol.md for the full protocol specification including all action fields and options.

Config action

Set run-level options at any point (typically first command):

{"id":"cfg","action":"config","v":1,"seq":0,"step_delay":0.5}

step_delay adds a pause between commands — either a fixed number of seconds or a [min, max] range for random delays:

{"step_delay": [0.5, 2.0]}

Python example

import json
import time

COMMANDS = "commands.jsonl"
RESULTS = "results.jsonl"

def send(action, seq, **fields):
    cmd = {"id": f"cmd-{seq}", "action": action, "v": 1, "seq": seq, **fields}
    with open(COMMANDS, "a") as f:
        f.write(json.dumps(cmd) + "\n")
        f.flush()

def read_results():
    with open(RESULTS) as f:
        return [json.loads(line) for line in f if line.strip()]

# Fetch a page
send("fetch", 1, url="https://example.com")
time.sleep(1)

# Get links
send("links", 2)
time.sleep(0.5)

# Done
send("quit", 3)
time.sleep(0.5)

for r in read_results():
    print(f"seq={r['seq']} ok={r['ok']}")

Differences from batch mode