Skip to main content
Glama
README.md
# Seahawk
[![crates.io](https://img.shields.io/crates/v/seahawk.svg)](https://crates.io/crates/seahawk)

The estate's authenticated broker for Unreal Engine's built-in MCP
server (Epic's `ModelContextProtocol` plugin in UE 5.8). Named for
Rafael Sabatini's *The Sea Hawk* (Owner, D-171; renamed from conn).

Epic's editor MCP server is powerful and completely
unauthenticated: any local process that can reach its loopback
port gets the editor's full tool surface, including in-editor
Python execution. Seahawk exists so agents never touch that raw
server. It serves modern-era MCP (2026-07-28) over stdio to
agents, and downstream it speaks to Epic's legacy-era server as a
client, localhost only.

## Controls

- **Era guard + sequencer** (fleet template): legacy `initialize`
  is refused with the typed `-32022`; forwarded requests apply one
  settle at a time, in order, against the stateful editor session.
- **Agent authentication**: every `tools/call` must carry the agent
  token in `_meta["seahawk/agent_token"]`. The guard verifies it
  (SHA-256 digests, constant-time compare), strips it from the
  frame, and logs refusals. Missing/wrong token: typed `-32001`.
- **Class curation**: every downstream tool is classified
  read / write / execute from the verified S0 census of UE 5.8's
  surface (830 tools; see the build workspace's `SURFACE.md`).
  Unclassified tools are withheld from `tools/list` and refused
  on call.
- **Execute default-deny**: execute-class tools (in-editor Python,
  arbitrary file write, Blueprint compilation, plugin loading,
  PIE, UI input injection, settings persistence, skill authoring,
  …) are listed with destructive annotations but refused unless
  the operator enables the specific tool in policy **and** the
  call carries a distinct operator token in
  `_meta["seahawk/operator_token"]`.
- **Op log**: every brokered call and guard refusal appends one
  JSON line — tool, class, SHA-256 of the canonical arguments,
  outcome, downstream latency. Raw argument values are never
  logged. This is the non-idempotency record: exactly what was
  applied, in order.
- **Policy as data**: tokens, downstream URL (loopback enforced),
  execute enablements, and per-tool class overrides live in a
  TOML config — see `seahawk.example.toml`.

## Computer use (S4)

Beyond the Unreal broker, Seahawk drives GUI applications on
its own X11 display through a built-in provider. The class
lattice is `read < write < actuate < execute`; classification
follows reach, not mechanism (Epic's Slate UI-injection tools
stay execute for exactly that reason).

- **Registration is policy data only**: `[[gui.apps]]` entries
  in the config name an application and the window-match strings
  (WM_CLASS / instance equality, or title substring) that
  identify its windows. There is no agent-callable registration
  and no runtime re-registration; the config is read once at
  startup. The estate's media-GUI registrations ship in
  `seahawk.example.toml`: Blender, Unity (Editor + Hub),
  ComfyUI (browser-hosted; matched by window title), Aseprite.
- **Per app, two tools**: `gui.<app>.observe` (read class —
  screenshot, window list, focus state; screenshots return a PNG
  and are op-logged by digest + dimensions, never by content)
  and `gui.<app>.actuate` (actuate class — focus, click,
  double-click, key chords, text entry, scroll, drag).
- **Actuate is default-deny with the execute two-key rule**: the
  tool must be named in `policy.actuate_enabled` *and* each call
  must carry the operator token. Actuation is confined to the
  registered window's rectangle (coordinates are validated
  against it before anything is injected), and every actuation
  is bracketed by screenshots whose digests land in the op log
  alongside the target description — a click cannot be undone,
  so the record shows what the screen held on both sides of it.
- **Honest caution**: input into an application that hosts
  scripting (Blender's Python console, Unity's editor, Aseprite
  scripts, ComfyUI custom nodes) can compose into code execution
  through the UI. The actuate class records the mechanism; the
  two-key gate prices the risk. Treat enabling
  `gui.<app>.actuate` with the same gravity as enabling an
  execute-class tool for that application.

## Vision grounding (S5, hardened by the 1.0 curative round)

Three broker-level tools give the broker eyes, gated by the
same `decide()` lattice as everything else (grounding is
perception only — it grants no permission):

- **`gui.observe`** (read): a registered app's frame *with*
  display geometry, stored under its SHA-256; results carry the
  resolved `window_id` and a blank-frame content verdict
  (`content` | `suspect_blank`).
- **`gui.ground`** (read): a natural-language target → the
  element's **bbox** plus the point derived as its centre, via
  a local Ollama-served vision model or the calling agent
  answering the broker's ticket. The centre is derived, never
  estimated — the curative fix for the S5 benchmark's
  trailing-edge aim bias.
- **`gui.act_verified`** (actuate): act and verify against a
  fresh capture. The `changed` check can be anchored
  (`changed_around`) or full-frame (`full_frame`); point-less
  actions diff the full frame by default. Retries *change
  strategy* (refined description, then route/crop escalation)
  and stop early on an identical re-ground. Frames that stay
  suspect-blank through a bounded content poll refuse the act
  (`seahawk_gui_suspect_blank`), and a caller may pin
  `window_id` against silent retargeting
  (`seahawk_gui_window_mismatch`). Visual verdicts follow the
  frozen Visual Benchmark v1 (`BENCH-VISUAL.md`).

## Code feedback (D-230 wiring)

**`code.feedback`** (read) closes the loop between brokered
GUI work and the estate's language tooling: per file it returns
LSP diagnostics (theodolite headless route; GDScript via
periscope), lint verdicts and format `changed` flags
(periscope running diver's own pipelines — Seahawk consumes
the catalog live through periscope, never a second hardcoded
list), file hashes, and the catalog provenance. Calls are
bounded episodes (3 per workspace + file set per window; the
4th is refused with the last counts). A route that cannot
serve a check answers `seahawk_tooling_unavailable` — feedback
is never assumed clean, and it never writes: the tooling
client's dispatch table contains no apply/write call at all.
Wiring is opt-in policy data (`[[tooling]]` + `[feedback]` in
`seahawk.example.toml`).

## Honest limits

Seahawk cannot firewall Epic's port: a local process that bypasses
Seahawk and speaks to the editor directly is outside its
guarantees. The operating discipline is lab-only use — throwaway
projects, editor up only during brokered sessions, nonstandard
port. The full threat model is in `SURFACE.md`.

## Status

**1.0.0** — lab-only (Owner ruling, D-146/D-169). The safety
charter is unchanged and binding: token auth, execute- and
actuate-class default-deny via `decide()`, append-only op log,
lab-only. Publication to crates.io / the MCP registry is held
for the Owner's word (see `CHANGELOG.md` and the 1.0 gate
report). Repository: <https://github.com/qompassai/seahawk>.