Agent attach (experimental)¶
The :agent module controls a running Compose Desktop JVM from another process.
The target does not need an HTTP listener, network port, or startup route registration.
Attach uses one API with two target setups:
- Preinstalled
spectre-coreis preferred. Bootstrap findsComposeAutomatoron the target classpath. Use this setup for a controlled target build. - Inject works without preinstalled core. The
spectre-agent-runtimejar containsMETA-INF/spectre/inject-runtime.jar. Bootstrap loads core from that payload when the target has Compose and Skiko. The call remainsAgentAttach.attach(pid). Use inject for occasional inspection, such as a stock IntelliJ attach. Preinstall core for sustained or frequent sessions. Details: Injection without preinstalled core.
Use agent attach when:
- The test JVM and UI JVM are separate processes, and the UI app's startup wiring must remain unchanged.
- A long-running Compose Desktop app needs interactive inspection through the
spectreCLI or an MCP client. - An IntelliJ-hosted Compose surface needs attach from a sister process (often via inject when the IDE build does not ship Spectre). See IntelliJ-hosted Compose for VM options and the stock-IDE recipe.
See Cross-JVM access for HTTP and IntelliJ-hosted Compose
for in-process automation through intellij-ide-starter.
The capability matrix records supported operations, unsupported
operations, and cases without CI execution. Each supported case needs executable CI evidence.
Experimental API
Everything under dev.sebastiano.spectre.agent.* is annotated
@ExperimentalSpectreAgentApi and requires explicit opt-in. The API may change in any
release until the UX stabilises. See Stability policy.
Trust boundary
The agent transport is local only and intended for trusted dev/test environments. Trust model:
- Communication is over a Unix Domain Socket under a short private directory (
/tmp/on Linux/macOS,%TEMP%on Windows). Filesystem permissions are the only access control: directory mode 0700 / socket mode 0600 on POSIX, or an owner-only ACL on Windows/NTFS. - The attaching JVM must run as the same OS user as the target JVM.
- There is no authentication and no encryption on the wire.
- The published
spectre-agentAPI jar is for the attaching JVM. Thespectre-agent-runtimejar gets loaded into the target JVM. See Artifact roles below.
See Security notes for the full risk register.
Requirements¶
- JDK 21+ on both the attaching and target JVMs.
- The attaching JVM must be a JDK with the
jdk.attachmodule on the module graph. - The target JVM needs a Compose Desktop host (so Spectre can find semantics owners).
Prefer a preinstalled
spectre-coredependency on the target for production-style attach. If core is absent, the agent runtime can inject a nestedMETA-INF/spectre/inject-runtime.jarpayload (experimental inspect path; see Injection without preinstalled core). - Linux, macOS, and Windows. The transport uses native Unix Domain Sockets (
AF_UNIX) on all three. It uses no named pipes or extra dependencies. Windows requires Windows 10 version 1803 / Windows Server 2019 or newer, when nativeAF_UNIXlanded; older Windows fails the attach preflight with a clear message. - The target JVM should be started with
-XX:+EnableDynamicAgentLoading. Without it, attach prints a stderr warning per JEP 451 and a future JDK will reject the attach entirely. Spectre's launch harness adds the flag for processes it starts; stock apps and IDEs need it in their own VM options (see IntelliJ-hosted Compose).
Artifact roles¶
Agent attach uses two JVMs:
- Target JVM — the Compose app under inspection or automation.
- Attacher JVM — the test, inspector, or tool process that calls
AgentAttach.attach(pid).
Preinstall Spectre core for a controlled target build. Bootstrap then uses the instrumented path without an inject classloader:
// build.gradle.kts of the target application
dependencies {
implementation("dev.sebastiano.spectre:spectre-core:<version>")
// No `spectre-agent` or `spectre-agent-runtime` dependency is needed in the target.
// The attacher supplies the runtime jar to the JDK Attach API.
}
For a stock IDE or third-party binary, attach can inject core when the target has Compose and the runtime jar contains the nested payload.
The attacher JVM normally needs these artefacts:
spectre-agent— the normal API jar used to compile test/inspector code.spectre-agent-runtime— the loadable Java-agent runtime jar that gets passed toVirtualMachine.loadAgent(...).
Declare the API dependency for compilation and the agent jar for runtime loading:
dependencies {
implementation("dev.sebastiano.spectre:spectre-agent:<version>")
runtimeOnly("dev.sebastiano.spectre:spectre-agent-runtime:<version>")
}
AgentAttach resolves the loadable runtime jar in this order:
AttachOptions.agentJarPath-Ddev.sebastiano.spectre.agent.runtimeJar=<path>- Classpath auto-discovery of a physical
spectre-agent-runtime-<version>.jar - In-repo fallback at
<spectre-checkout>/agent-runtime/build/libs/agent-runtime-*.jar, only when the attacher cwd is inside a Spectre source checkout (detected via monorepo markers). Published consumers should use options 1–3; the fallback is a Spectre-dev convenience.
With runtimeOnly(...), Gradle lists the runtime jar in the attacher's java.class.path.
Spectre passes that physical path to VirtualMachine.loadAgent(...).
Attacher code does not call runtime classes directly. The target does not declare
spectre-agent-runtime as a dependency.
The attacher also has an input coordination override:
-Ddev.sebastiano.spectre.agent.inputCoordination=disabled (or
AttachOptions.inputCoordination = AttachInputCoordination.Disabled) drops the attach path from
InputLeasePolicy.Required to Off in the target. It exists so a broken input coordinator is
recoverable. Disabling it removes the guarantee that no other Spectre process is
driving the same desktop. Read
When the coordinator cannot be reached first.
Classpath and directory discovery require exactly one runtime jar.
If multiple spectre-agent-runtime-*.jar or agent-runtime-*.jar files match,
AmbiguousAgentRuntimeJarException lists them. Set AttachOptions.agentJarPath or
-Ddev.sebastiano.spectre.agent.runtimeJar to choose one explicitly.
How attach works¶
AgentAttach.attach(pid) performs this sequence:
- Pick a fresh Unix Domain Socket path such as
/tmp/sp-a-<pid>-<8char-uuid>/agent.sock, and check that it fits the platform'ssun_pathlimit. - Resolve the loadable
spectre-agent-runtime-<version>.jar. - Run attach preflights, including the same-OS-user check.
- Call
VirtualMachine.attach(pid).loadAgent(runtimeJarPath, udsPath). - The target JVM loads the runtime jar and invokes
SpectreAgent.agentmain(...). - Inside the target JVM, bootstrap locates or injects
ComposeAutomator(see below), creates an in-process automator, and starts an IPC server on the UDS path. - The attacher connects an
IpcClientto that socket and returnsAttachedAutomator.
After attach, methods such as windows(), findByTestTag(...), click(...), and
screenshot() send CBOR requests through the socket. The target runs them against its
in-process automator and returns DTOs or bytes.
The attacher makes a best-effort attempt to start the experimental input coordinator.
Read-only attach still works if startup fails. Current core selects
InputLeasePolicy.Required on RobotDriver.synthetic().
Clipboard paste, and real OS input when enabled, then fail if coordination remains unavailable.
An older preinstalled core without InputLeasePolicy or synthetic() uses the legacy
no-argument RobotDriver without coordination.
Injection without preinstalled core¶
Bootstrap order inside the target:
- Prefer a preinstalled
ComposeAutomatoralready on the target classpath (instrumented attach). - Else extract the nested
META-INF/spectre/inject-runtime.jarfrom the agent runtime jar, open a child classloader parented at a Compose host loader, and load Spectre core from that payload (inject attach). Compose / Skiko stay on the target; only Spectre core and relocated kotlinx bits come from the inject jar.
Inject is an experimental inspection path for occasional attach, inspect, and detach sessions. Use preinstalled core for frequent CI attach loops. The injected runtime stays loaded after detach, and every later attach to the same JVM reuses it. The target JVM deletes the extracted jar when it exits.
An IntelliJ Platform IDE keeps Compose in a plugin classloader and loads it only when the
first Compose surface opens. An attach to such an IDE succeeds before that and reports no
Compose windows until Compose loads. Other JVMs without Compose still fail the attach with
ComposeNotOnClasspathException. See IntelliJ-hosted Compose.
Both paths use AgentAttach.attach(pid). The public API has no inject flag.
Custom runtime jar path¶
Normal Gradle runs use classpath discovery. AttachOptions.agentJarPath and
-Ddev.sebastiano.spectre.agent.runtimeJar=<path> take precedence over that scan.
Use an explicit path when a launcher, shaded tool, module-path launch, or script hides
the physical runtime jar from java.class.path.
import dev.sebastiano.spectre.agent.AgentAttach
import dev.sebastiano.spectre.agent.AttachOptions
import java.nio.file.Path
AgentAttach.attach(
pid = targetPid,
options =
AttachOptions(
agentJarPath = Path.of("/abs/path/to/spectre-agent-runtime-<version>.jar"),
),
)
Equivalent: set -Ddev.sebastiano.spectre.agent.runtimeJar=<path> on the attacher's JVM.
Inside a Spectre checkout, AgentAttach can find
<checkout>/agent-runtime/build/libs/agent-runtime-*.jar after
./gradlew :agent-runtime:jar. This fallback also works in checkout subdirectories.
Outside the checkout, put spectre-agent-runtime on the attacher classpath or supply
an explicit path or system property.
Consumers that cannot use the published Maven coordinate still have two supported paths:
-
As a project dependency (inside the Spectre repo or a Gradle composite build that includes it):
-
As an explicit path via
AttachOptions.agentJarPathordev.sebastiano.spectre.agent.runtimeJar, as shown above.
Start the target with the dynamic-agent flag (suppresses the JEP 451 stderr warning):
Attaching¶
In the attaching JVM (typically a test process), opt in to the experimental API and use
AgentAttach.attach:
@file:OptIn(ExperimentalSpectreAgentApi::class)
import dev.sebastiano.spectre.agent.AgentAttach
import dev.sebastiano.spectre.agent.AttachOptions
import dev.sebastiano.spectre.agent.ExperimentalSpectreAgentApi
import dev.sebastiano.spectre.agent.SpectreProcesses
// Find the target by name.
val target = SpectreProcesses.findByName("MyApp").single()
AgentAttach.attach(target.pid).use { automator ->
val windows = automator.windows()
val submitNodes = automator.findByTestTag("Submit")
if (submitNodes.isNotEmpty()) {
automator.click(submitNodes.first().key)
}
// Window/surface attach screenshots fail closed (#359); fullscreen is the only
// screen-pixel capture mode on this path.
val pngBytes = automator.screenshot(fullscreen = true)
} // detach + cleanup on close()
AttachedAutomator implements AutoCloseable. close() sends AgentRequest.Detach.
The agent stops accepting requests, closes its input coordinator session, releases
ComposeAutomator, removes the UDS path, and unregisters its shutdown hook.
A target-side shutdown hook handles crash cleanup.
AttachOptions¶
AttachOptions(
agentJarPath = null, // null = auto-locate (see "Artifact roles" above)
udsPath = null, // null = <base>/sp-a-<pid>-<8char-uuid>/agent.sock (see below)
attachTimeoutMs = 5_000, // how long to wait for the agent's IPC server to come up
)
The default <base> is /tmp on Linux and macOS. Windows uses %TEMP% or,
if that path is too deep, %LOCALAPPDATA%\Temp. The sockaddr_un.sun_path
limit is 102 usable bytes on macOS and 106 on Linux and Windows. Custom paths
must fit. attach throws UdsPathTooLongException before loading the agent
when a path exceeds the limit. The error names the path and limit.
When setting udsPath under an existing directory, secure that parent directory.
Spectre creates its default per-attach directory and socket for the owner only.
It uses mode 0700/0600 on POSIX. On Windows, it gives the owner full control and
drops inherited ACL entries. Spectre leaves existing parent permissions unchanged.
AgentAttach.attach runs a same-user preflight and throws
AttachPermissionDeniedException if the target JVM is owned by a different OS user (the
JDK Attach API only works across attach-compatible same-user processes on POSIX). On
Linux/macOS the preflight prefers numeric UID equality when both sides can be resolved, and
falls back to ProcessHandle usernames when UID lookup is unavailable (#166).
The JEP 451 -XX:+EnableDynamicAgentLoading flag is not verified by Spectre yet.
The JVM itself prints a stderr warning if it's missing, which is the source of truth. A follow-up
can add a reliable preflight via HotSpotDiagnosticMXBean.
Operation set¶
AttachedAutomator exposes the same operations as the HTTP transport, plus detach:
| Method | Wire op | Returns |
|---|---|---|
windows() |
AgentRequest.Windows |
List<WindowSummaryDto> (includes isShowing; delayed-show hosts may appear before they are visible so keys agree with allNodes() — #362) |
allNodes() |
AgentRequest.AllNodes |
List<NodeSnapshotDto> |
findByTestTag(tag) |
AgentRequest.FindByTestTag |
List<NodeSnapshotDto> |
click(nodeKey) |
AgentRequest.Click |
Unit |
doubleClick(nodeKey) |
AgentRequest.DoubleClick |
Unit |
longClick(nodeKey, holdForMs?) |
AgentRequest.LongClick |
Unit |
swipe(...) |
AgentRequest.Swipe |
Unit (node-to-node or screen coords) |
scrollWheel(nodeKey, wheelClicks) |
AgentRequest.ScrollWheel |
Unit |
pressKey(keyCode, modifiers?) |
AgentRequest.PressKey |
Unit |
focusWindow(nodeKey) |
AgentRequest.FocusWindow |
Unit (raise/activate window hosting node) |
typeText(text) |
AgentRequest.TypeText |
Unit |
screenshot(windowIndex?, surfaceId?, fullscreen?) |
AgentRequest.Screenshot |
ByteArray (PNG); only fullscreen=true succeeds on attach — window/surface fail closed (#359) |
capture(windowIndex) |
AgentRequest.Capture |
AtomicCaptureResult |
windowIdentities(windowIndex?) |
AgentRequest.WindowIdentity |
List<WindowIdentityDto> |
waitForNode(...) |
AgentRequest.WaitForNode |
NodeSnapshotDto |
waitUntilGone(...) |
AgentRequest.WaitUntilGone |
Unit (absence wait — #438; timeout error keeps the selector, timeout, and still-present count) |
waitForVisualIdle(...) |
AgentRequest.WaitForVisualIdle |
Unit |
waitForIdle(...) |
AgentRequest.WaitForIdle |
Unit (fingerprint wait; no idling-resource registration over attach — #362) |
printTree() |
AgentRequest.PrintTree |
String (human-readable dump — #362) |
screenshot(node) |
AgentRequest.Screenshot(nodeKey) |
ByteArray (PNG of node bounds — #362). Native window still only: needs spectre-recording in the target, otherwise fails closed (#597) |
click(node) |
AgentRequest.Click |
Unit (DTO overload uses [NodeSnapshotDto.key] — #362) |
close() (auto) |
AgentRequest.Detach |
tear-down |
windowIdentities returns a native handle or ID when it can resolve one.
It also returns window and Compose-surface bounds in AWT user-space screen coordinates.
These match windows(), locationOnScreen, and Robot coordinates.
Surface bounds relative to the window supply a crop rectangle.
The result includes scaleX, scaleY, translateX, translateY, and cropRequired.
cropRequired is true when the Compose surface occupies only part of the top-level window.
For device pixels, transform a point as
(x, y) → (x * scaleX + translateX, y * scaleY + translateY).
Scale widths and heights without translation. Daemon-owned recording uses this metadata
to capture on the daemon host.
waitForNode, waitForVisualIdle (#201), waitForIdle (#362), and waitUntilGone (#438)
are available over the agent transport. waitForIdle runs a fingerprint-only wait on the
agent's in-target automator (timeout / quiet / poll; absolute deadline on the wire like
waitForNode). It does not observe idling resources registered on a different automator
instance in the app. Idling-resource registration and withTracing remain in-process-only.
Each wait returns its timeout message verbatim with category timeout.
waitForIdle names busy idling resources. waitForVisualIdle reports frame sample counts.
waitUntilGone names the selector and the remaining match count.
The wire deadline is the wait budget plus one second.
The agent checks it with a scheduler and after the handler returns.
An identical deadline could replace the automator's timeout detail with
Deadline elapsed during op. The added second lets the automator report its cause.
The agent's timeout + 2s suspend-bridge limit still bounds a stalled operation.
Agent, HTTP, and daemon/CLI/MCP support doubleClick, longClick, swipe,
scrollWheel, and pressKey (#203). Over attach, focusWindow(nodeKey) raises
and focuses the node's AWT window (#364). The CLI and MCP expose it as focus-window and
focus_window, which take a window index instead of a node key.
typeText and pressKey check OS keyboard focus only for real OS input. With real OS
input, call focusWindow first when the attach client holds foreground focus. Synthetic
input, the attach default, dispatches key events inside the target JVM and does not need
OS focus. typeText still requires a focused node in either mode.
Wire format¶
Length-prefixed CBOR over the UDS:
DTOs live in dev.sebastiano.spectre.agent.transport.*. Both sides share the same
classes; CBOR's @SerialName discriminators pin each variant in the sealed-interface
hierarchy.
Protocol version handshake (#199)¶
After the UDS connects, the first exchange is always:
- Client →
hellowithprotocolVersion(currently3—ProtocolVersion.CURRENT) - Runtime →
helloAckwith the same version, orerrorwith categoryprotocolMismatch
The experimental agent protocol requires an exact version match.
A mismatch fails attach with IOException or SpectreAgentException.
A future additive compatibility range would change ProtocolVersion.CURRENT and this guide.
The protocol has three revisions. v1 uses bare request and response frames after
hello. v2 (#200) adds operation envelopes with op ids, cancellation, and deadline
budgets. v3 encodes bulk pngBytes and captureJsonUtf8 payloads as CBOR byte
strings. Earlier peers expect integer arrays; the type system cannot detect this
representation change. Peers therefore reject an incompatible version at hello,
before a screenshot frame arrives.
Unknown operations¶
If the runtime receives an unknown sealed @SerialName request, it returns an error
with category unsupportedOperation. This gives mixed-version peers a defined failure.
Error taxonomy¶
AgentResponse.Error carries a stable category string alongside message:
| Category | Meaning |
|---|---|
unsupportedOperation |
Runtime too old / op not implemented |
protocolMismatch |
Handshake or schema/framing mismatch |
invalidSelector |
Malformed node key or selector |
nodeNotFound |
Well-formed key, no matching node |
timeout |
Deadline exceeded |
cancelled |
Explicit cancel of an in-flight op (#200) |
payloadTooLarge |
Response/request exceeds the frame hard limit (#204) |
inputRejected |
Focus / Robot / permission rejection |
internalError |
Unexpected agent-side failure (default) |
Selectors (#202)¶
Beyond findByTestTag, the agent transport supports:
| Wire op | Notes |
|---|---|
findByText |
text, exact (default true) |
findByContentDescription |
description |
findByRole |
role string (e.g. Button); matches role.toString() |
NodeSnapshotDto includes contentDescriptions, isDisabled, isSelected (HTTP field-set
parity). On-screen bounds stay integer AWT units on the agent; HTTP keeps double
window+screen rects.
NodeSnapshotDto also carries node state and tree links:
| Field | Meaning |
|---|---|
isClickable |
true when the node has a click action. |
toggleableState |
"On", "Off", or "Indeterminate" for a checkbox or switch; null otherwise. |
progress |
ProgressRangeDto (current, min, max, steps) for a slider or progress bar; null otherwise. |
parentKey |
key of the parent node; null at a root. |
childKeys |
keys of the child nodes, in tree order. |
boundsInWindow |
Integer layout bounds within the Compose surface, in Compose (physical) pixels. |
boundsInWindow matches AutomatorNode.boundsInWindow, rounded to whole pixels. It is not
divided by the display scale, so use bounds for Robot input and screenshot regions.
These fields have defaults, so an attacher or runtime from an older Spectre release still exchanges nodes with a newer one. The older side ignores the fields. The newer side reads the defaults when the older side does not send them.
Payload limits (#204)¶
Each IPC frame is length-prefixed, with two separate bounds:
| Bound | Value | Applies to |
|---|---|---|
| Write budget | 64 MiB default (DEFAULT_MAX_FRAME_BYTES), configurable |
the payload a process will send |
| Read ceiling | 512 MiB fixed (MAX_FRAME_BYTES_CEILING) |
the length a process will accept from a header |
The read ceiling limits memory allocation from an invalid or desynchronised frame header.
readFrame allocates a buffer based on that header length.
The ceiling stays fixed above every allowed write budget, so a reader accepts any
legitimately configured writer's frame.
The default write budget covers screenshots. An incompressible 3840×2160 24-bit sRGB image approaches 25 MB. The 64 MiB budget leaves room for a dual-4K desktop.
pngBytes and captureJsonUtf8 use @ByteString, so CBOR encodes them as byte strings.
Without that annotation, kotlinx serialises each signed byte as an integer.
That can grow a frame to about 1.8× its payload and invalidate the stated budgets.
WirePayloadEncodingTest checks the encoding.
Raising the budget¶
Larger multi-monitor HiDPI rigs (dual-5K and up) can exceed the default. Raise it with either:
export SPECTRE_MAX_FRAME_BYTES=256MiB # bytes, or a binary suffix: 512, 128k, 64M, 64MiB, 1G
spectre --max-frame-bytes 256MiB capture <session-id>
The flag takes precedence over the environment variable. Both accept values up to the 512 MiB read ceiling.
Propagation matters, because three processes are involved:
- The CLI applies the value to itself.
- A daemon this invocation starts inherits it on its command line. A daemon that is already running keeps the budget it booted with and reports it in the handshake. Asking for a different one fails loudly. It cannot partially apply the request:
Cannot honour --max-frame-bytes=256MiB (268435456 bytes): the running Spectre daemon started
with 64MiB (67108864 bytes), and a daemon keeps the budget it booted with. Run
`spectre daemon kill` and retry so the new budget applies to the daemon and to the JVMs it
injects.
Only an explicit request is refused, and explicit means the option or the variable was
present, regardless of whether its value differs from the default. Asking for 64MiB
against a 128MiB daemon is a conflict like any other. Leaving the budget alone asks for nothing, so a daemon
running something larger is accepted silently: readers take frames up to the ceiling whatever
their own budget. A daemon too old to report its budget cannot have been started with the
requested one, so the request is refused because compatibility cannot be established.
- The injected agent cannot read the daemon's environment, and it is the process that writes
the bulky screenshot frames, so the daemon forwards its resolved budget in agentArgs (see
below). It applies before the agent's IPC server accepts a request.
Readers accept frames up to the ceiling. The mismatch error rejects a requested budget that the running daemon cannot apply.
Over-budget behaviour¶
Frames over the write budget fail closed:
- Responses that encode larger than the budget are not truncated or spilled to disk by the
agent transport. The runtime replies with
errorcategorypayloadTooLargeand a message that includes the sizes. - The connection stays open; subsequent ops on the same session continue normally.
- Parity CI can rely on deterministic taxonomy behaviour without size-threshold flakes.
The fullscreen still can first use logical resolution when its original size exceeds
the budget. It reports payloadTooLarge if that image still exceeds the limit. See
Atomic capture — Pixel scale.
Capture directories and a shared daemon filesystem can handle larger artefacts. The wire protocol has no separate spill-to-file path for oversized frames.
agentArgs format¶
-javaagent:spectre-agent-runtime.jar=<agentArgs> accepts two forms:
| Form | Example | Used by |
|---|---|---|
| Bare UDS path | /tmp/sp-a-123-abcd/agent.sock |
hand-written -javaagent: lines; still accepted |
| Structured | uds=/tmp/sp-a-123-abcd/agent.sock,maxFrameBytes=268435456 |
everything Spectre emits |
Spectre recognises the structured form when arguments start with uds= and include
another comma-separated field. It percent-escapes emitted values, preserving , and
= in UDS paths. A manually written bare path such as uds=agent,1.sock is
ambiguous and reads as structured. Spectre emits only structured arguments. Bare paths
remain accepted for manually written -javaagent: lines.
The runtime ignores unknown keys and values it cannot parse.
A runtime that predates structured arguments treats the entire string as a socket path,
so attach times out. This pairing requires an explicit runtime jar override through
AttachOptions.agentJarPath or the system property.
The bootstrap timeout identifies that possibility. Changes to payload representation bump
ProtocolVersion.CURRENT so mixed peers fail at the handshake.
Spectre always emits the frame budget, including its default. A target can also set
SPECTRE_MAX_FRAME_BYTES. Explicitly sending the budget keeps the daemon and injected
JVM aligned. For example, a 16 MiB target limit would reject captures that a
64 MiB daemon could otherwise carry.
HTTP maps payloadTooLarge → 413 Payload Too Large.
Long operations and cancel (#200)¶
After Hello, each request carries opId, an optional absolute deadlineEpochMs,
and its body. Responses use opId to match requests on a shared connection.
- Long work (future waits, heavy capture) runs on a worker thread so the accept loop remains responsive to cancel/detach.
- Cancel is an explicit wire op (
cancelwith the targetopId). Closing the socket has different lifecycle semantics. - Closing a CLI/MCP front-end during a long-poll cancels only that front-end connection's
in-flight work. The daemon session stays attached until an explicit
detach(or daemon kill / crash). Reconnect or use the CLI against the same session id. A disconnect leaves the daemon session attached and recoverable (see lifecycle below). The agent transport itself only detaches on an explicitdetachor handshake failure teardown.
Clients should use category from AgentErrorCategory or SpectreAgentException.
The free-text message explains the error. HTTP maps categories to status codes
(invalidSelector → 400, nodeNotFound → 404, unsupportedOperation → 501,
cancelled → 499 Client Closed Request, payloadTooLarge → 413, etc.) via
SpectreErrorCategory in :server.
Schema evolution rules¶
Additive-safe on DTOs:
- New optional fields with defaults on request/response data classes
- New sealed variants with new
@SerialNamevalues (old peers answerunsupportedOperationfor unknown request names)
Not additive-safe without a version bump:
- Renaming or removing fields
- Changing field types or making an optional field required
- Reusing an old
@SerialNamefor a different shape (seescreenshot_v2vs pre-#289screenshot)
Current limitations¶
- Windows needs 10 version 1803 / Server 2019 or newer. Earlier versions
lack native
AF_UNIXand fail attach preflight withAttachPlatformUnsupportedException. Hosted GitHubwindows-latestdoes not provide a reliable interactive desktop for the Robot-backed attach fixture. Run the full attach → exercise → detach UI test on a physical Windows desktop. It is opt-in. Non-UI transport and ACL tests still run on every Windows CI job:
# bash / zsh / cmd
./gradlew :agent:test -Pspectre.agent.attachE2e.allowWindows=true --tests '*AgentAttachIntegration*'
# PowerShell: quote -P… so the shell does not split on the property name
./gradlew :agent:test "-Pspectre.agent.attachE2e.allowWindows=true" --tests '*AgentAttachIntegration*'
waitForNode, waitUntilGone, waitForVisualIdle, and fingerprint
waitForIdle are supported over agent IPC with shared deadline budgets and cancel.
Idling-resource registration stays in-process only.
- IntelliJ-hosted Compose: the classloader-disambiguation rule (D-14 in the plan) was
designed to handle PluginClassLoader chains. Automatic tests do not cover it yet. If
attaching to an IntelliJ-hosted target fails, file a Spectre issue with the
agent-attach label.
- Runtime jar is separate from the API jar. The normal spectre-agent dependency is not the
jar loaded into the target JVM. Add spectre-agent-runtime, pass
AttachOptions.agentJarPath, or set -Ddev.sebastiano.spectre.agent.runtimeJar=....
Manual verification recipe¶
# Terminal A — start a Compose app that depends on spectre-core (preferred path)
./gradlew :sample-desktop:run
# Find its PID (cross-platform: jps ships with the JDK)
jps -l | grep "dev.sebastiano.spectre.sample.MainKt"
# POSIX alternative: ps -A | grep "…MainKt" | awk '{print $1}'
# Terminal B — attach the agent. The agent's stderr lands in Terminal A.
./gradlew :agent:attachSpike -Ppid=<pid>
attachSpike runs separately from :check for manual verification.
It is not compatible with Gradle's configuration cache.
CLI and MCP¶
The spectre executable starts a per-user local daemon when needed.
spectre mcp and ordinary CLI commands share its attached sessions.
MCP uses standard input and output for protocol frames.
Do not wrap it in a command that prints banners to standard output.
Start with the same target prerequisites described above, then find and attach it from a shell:
The attach response contains an id. Pass it to commands such as tree, find, click, and
screenshot. On the attach path, screenshot requires --fullscreen for screen-pixel
capture; default / --window / --surface fail closed (occlusion/privacy risk). Without
--output, a successful capture creates a temporary file and prints its path. Prefer a target
with preinstalled spectre-core; experimental inject also works for Compose-only hosts. See
Requirements. Full command and MCP reference: CLI.
Claude Code recipe¶
Install the spectre executable where Claude Code can invoke it, then add it to the project's
.mcp.json. Use an absolute path so Claude Code does not depend on the interactive shell's
PATH:
Restart Claude Code after changing the configuration. It can then use these tools in order:
list_processesto find the target PID.attachwith that PID and retain the returnedsessionId.tree,find, orfind_text/wait_for_nodefor keys, then input tools (click,double_click,long_click,swipe,scroll_wheel,press_key,type_text,focus_window), andwait_until_goneafter a dismissal before touching what it revealed.screenshotwithfullscreen=truefor an inline full-desktop PNG (window/surface targets fail closed on attach), orcapture/record_*for daemon-filesystem artefacts (paths only).- When the target runs under Compose Hot Reload: call
wait_for_reload_settledbefore triggering a code reload (it must observe the settle chain), then re-runtree/findbefore further input. detachwith the retainedsessionIdwhen finished — releases that session only and returns leftover capture cleanup summary (count/bytes/paths + prune command when any exist). Unknown or already-detached sessions fail closed (isError). Sibling sessions stay attached;detachis never “kill the daemon” or “release all.” Detach does not delete capture files; run the summary’spruneCommandfor cleanup. Preferdetachoverspectre daemon kill(which drops every session). The shared daemon stays up after a successful detach, allowing anotherlist_processes/attachcall.
Agent session lifecycle (multi-session + disconnect)¶
- Preferred cleanup order: stop any active recording (
record_stop) → finish or abandon longwait_for_*calls →detachthatsessionId. Concurrent ops while detach runs fail closed (actionable errors; no hang); do not rely on them succeeding mid-teardown. - Two sessions: attach A and B independently; detaching A leaves B usable. Post-detach
tree/click/screenshoton A fail with a session-not-found error. - Client disconnect ≠ detach. Killing or restarting the MCP front-end (stdio death, agent
process exit) cancels in-flight front-end work only. The daemon keeps the target session
until an explicit
detach, CLIspectre detach <session-id>, orspectre daemon kill. After reconnect, list sessions / reuse the samesessionId, or detach deliberately. Disconnect does not create undocumented zombies and does not silently detach. - Recovery after front-end death:
spectreCLI against the same user daemon (ps/ attach if needed /tree/detach), or a new MCP client talking to the same daemon.
Full MCP tool names, input/output schemas, filesystem implications, and capture-mode
distinctions: CLI — MCP. MCP detach success JSON is the daemon Detached shape
(sessionId; CLI --json uses id); see
Detach success body (MCP vs CLI).
Node keys can become invalid after a UI change. Run tree or find again after
an interaction. Reload-aware sessions also invalidate keys after a successful settle.
See Compose Hot Reload awareness.
When both MCP servers are available, use each for its supported operations:
Use Compose Hot Reload MCP to check recomposition during a live Hot Reload session. Use Spectre for other inspection and automation tasks.
Call MCP detach or spectre detach <session-id> to release one session.
spectre daemon kill stops the shared daemon and discards all sessions.