Protocol Reference

Reflects the v0.6.0 implementation. architecture.md is the canonical contract; this file documents the on-wire JSON shapes the CLI and SDK actually emit. Coverage of the ten artifact tokens and 11 CLI commands matches src/shared/, src/sdk/, and src/host/.

All command outputs are single JSON objects on stdout unless otherwise stated. Artifact files are referenced by absolute *_file paths in those JSON envelopes.

Every failure envelope carries the standard fields below. afhttp fetch execution failures also include trace; parse/configuration failures from other commands may omit it.

Fetch Result

afhttp fetch returns one object when a URL acquisition attempt reaches an HTTP response or browser-rendered page state.

Example:

{
  "code": "fetch",
  "request_id": "req",
  "request_url": "https://example.com/",
  "status": 200,
  "final_url": "https://example.com/",
  "tab_id": "page-1",
  "body_file": "/tmp/afhttp-out/req/body.html",
  "content_file": "/tmp/afhttp-out/req/content.md",
  "content_json_file": "/tmp/afhttp-out/req/content.json",
  "rendered_html_file": "/tmp/afhttp-out/req/rendered.html",
  "text_file": "/tmp/afhttp-out/req/text.txt",
  "screenshot_file": "/tmp/afhttp-out/req/page.png",
  "network_file": "/tmp/afhttp-out/req/network.json",
  "console_file": "/tmp/afhttp-out/req/console.json",
  "observation_file": "/tmp/afhttp-out/req/observation.json",
  "storage_file": "/tmp/afhttp-out/req/storage.json",
  "trace": {
    "render_decision": "browser",
    "render_mode": "auto",
    "render_used": true,
    "main_request_observed": true,
    "current_stage": "complete",
    "duration_ms": 820,
    "timeout_ms": 30000,
    "navigation_duration_ms": 540,
    "wait_mode": "auto",
    "wait_satisfied_by": "network_quiet_dom_text_stable",
    "network_quiet": true,
    "dom_stable": true,
    "text_stable": true,
    "capture_reason": "wait_satisfied",
    "stages": [
      {"name": "navigate", "status": "ok", "duration_ms": 340},
      {"name": "wait_readiness", "status": "ok", "duration_ms": 180},
      {"name": "capture_rendered_html", "status": "ok", "duration_ms": 25}
    ]
  }
}

Warnings

Warnings do not fail the whole fetch.

Next action

afhttp fetch --takeover emits next_action only when the warmed profile did not reach the target and a human must drive the browser. When the profile already reaches the target, the result carries the usual artifacts and no next_action.

{
  "code": "fetch",
  "final_url": "https://example.com/login",
  "tab_id": "page-7",
  "next_action": {
    "kind": "human_takeover",
    "takeover_url": "http://host.mesh.internal:9222/takeover/panel?handoff=…",
    "takeover_url_expires_at_rfc3339": "2026-06-11T08:15:00Z",
    "takeover_url_ttl_s": 900,
    "takeover_url_scope": "takeover",
    "recommended_command": "afhttp fetch \"https://example.com/login\" --tab page-7 --endpoint-url ws://host.mesh.internal:9222 …"
  }
}

Trace

duration_ms, timeout_ms, current_stage, and stages are always present once fetch execution begins. Successful and failed fetch envelopes use the same trace shape.

Failure envelopes for afhttp fetch also include this trace:

{
  "code": "error",
  "error_code": "navigation_timeout",
  "error": "fetch timed out after 90000ms during capture_text",
  "retryable": true,
  "trace": {
    "render_decision": "browser",
    "render_mode": "always",
    "render_used": true,
    "current_stage": "capture_text",
    "duration_ms": 90001,
    "timeout_ms": 90000,
    "main_request_observed": true,
    "stages": [
      {"name": "navigate", "status": "ok", "duration_ms": 929},
      {"name": "wait_readiness", "status": "ok", "duration_ms": 5000},
      {"name": "capture_text", "status": "timeout", "duration_ms": 84072}
    ]
  }
}

Artifact Schemas

body_file

Raw main-resource response body. The file is not redacted or transformed except decompression when requested by the fetch path.

rendered_html_file

UTF-8 HTML serialization of the post-JS DOM. It is a browser artifact, not a readability or markdown conversion.

text_file

UTF-8 text from document.body.innerText. This is mechanical visible text extraction and does not include summarization.

screenshot_file

Full-page PNG. Missing screenshots produce a warning, usually backend_unsupported.

console_file

JSON array of console/runtime events:

[
  {
    "timestamp_ms": 123,
    "level": "warning",
    "type": "log",
    "text": "deprecated API",
    "url": "https://example.com/app.js",
    "line": 10,
    "column": 5
  }
]

observation_file

Agent-readable page snapshot. It is intentionally smaller and more action-oriented than rendered.html, but it remains a mechanical projection.

Nodes include native interactive elements, explicit interaction markers (role, tabindex, contenteditable=true), iframes, and a bounded set of non-semantic elements whose computed cursor is pointer. Observation traverses open shadow roots and same-origin iframes. Cross-origin iframes are represented only by their iframe node plus frame_ref/frames[] metadata because their contents are not readable from the embedding page.

Top-level fields:

Node fields:

Traversal caps are global across the main document, open shadow roots, and same-origin iframe documents. When truncated is present it reports the mechanical reason and the node/scan limits; no truncation is silent.

Forbidden fields: intent labels, importance scores, page-type guesses, recommended actions, or captcha/paywall/login classification.

network_file

Deep network artifact. Top-level shape:

{
  "schema_version": 1,
  "main_request_id": "req-1",
  "entries": [],
  "summary": {
    "requests_total": 12,
    "responses_total": 11,
    "finished_total": 10,
    "failed_total": 1,
    "incomplete_total": 1,
    "inflight_total_at_capture": 1,
    "pending_by_resource_type": {"XHR": 1},
    "captured_body_files": 2,
    "redacted": true
  }
}

Each entries[] item may include:

Sensitive request/response headers are redacted by default in network.json: cookie, authorization, proxy-authorization, set-cookie, and token/secret-like header names. --no-network-redact disables this for trusted local debugging and may write raw tokens, cookies, and PII into network.json; trace.sensitive_capture records that opt-in.

Network body capture modes:

Body capture failures become warnings, not fetch failures. --capture-ws and --capture-sse write WebSocket/SSE payloads to frame/event files and may expose bearer tokens, session identifiers, chat content, or other PII.

When --wait auto is used, XHR/fetch/EventSource body capture is enabled by default so the network artifact can explain pages whose visible DOM is only a shell. Pending requests are not hidden: network.summary.incomplete_total, network.summary.inflight_total_at_capture, and network.summary.pending_by_resource_type stay non-zero, and entries remain in state: "pending" or state: "responded".

CDP Result

afhttp cdp wraps the raw CDP method result under result so CDP fields cannot collide with the top-level command envelope:

{"code":"cdp","result":{"result":{"type":"number","value":42}}}

CDP method errors return the standard error envelope with error_code: "cdp_error" or error_code: "cdp_timeout".

Health Result

Authenticated /health and afhttp health return:

Unauthenticated public health, when enabled, returns only status.

Capabilities Result

/capabilities and afhttp capabilities return:

Capabilities describe support; they do not guarantee a later page-specific artifact capture will succeed.

External Runtime Dependencies

The distributed afhttp binary does not bundle browser engines or KasmVNC. It locates external tools on PATH (or explicit flags where available) and spawns them as separate processes:

Profile Results

Profile lifecycle commands are local-only.

profile list

{
  "code": "profile_list",
  "profile_root": "/Users/me/.local/share/afhttp/profiles",
  "profiles": [
    {
      "backend": "brave",
      "name": "work",
      "path": "/Users/me/.local/share/afhttp/profiles/brave/work",
      "locked": true,
      "metadata_present": true,
      "last_used_at_rfc3339": "2026-05-27T01:23:45Z",
      "size_bytes": 123456789
    }
  ]
}

profile info

Returns one profile object with backend, metadata, lock owner when known, approximate size, path, and browser-family hints. Pass --backend when multiple backend scopes contain the same logical profile name.

profile lock-status

Returns locked, and when available owner_pid, owner_started_at_rfc3339, and owner_command.

profile downloads

Read-only listing of files the browser captured in the profile download directory. Completed files report state:"completed"; Chromium partial files ending in .crdownload report state:"in_progress".

{
  "code": "profile_downloads",
  "backend": "brave",
  "name": "work",
  "download_dir": "/Users/me/.local/share/afhttp/profiles/brave/work/downloads",
  "downloads": [
    {
      "filename": "report.csv",
      "path": "/Users/me/.local/share/afhttp/profiles/brave/work/downloads/report.csv",
      "size_bytes": 12345,
      "state": "completed"
    }
  ]
}

profile delete / profile prune

profile delete returns the deleted profile name. profile prune returns the resolved profile_root, dry_run, and the matching profile entries. Locked profiles are skipped; missing profiles return profile_not_found.

Error Codes

Agents should branch on error_code, not the human-readable error. Examples below are representative error / Chromium errorText strings.