VIRTUAL ADMIN AGENT API REFERENCE

TARGETS IN A MULTI-SESSION VA LINK

An MCP agent sees operations only for sessions assigned to its own attachment. If it has
no target and exactly one active session is unassigned, VA Link assigns it automatically.
Otherwise use `link_request_target` and wait for the human to choose and confirm a target.
The optional `hint` is a current Computer ID or visible `Sitzung N` label, not an access
grant. The returned `target_ref` (`t1`, `t2`, ...) remains bound to that logical session
even if the visible list is renumbered. With one assigned target it may be omitted from
tool arguments; with several, include it in every target-specific call. VA Link strips
this local routing field before forwarding the call to Mobile or Companion. A session end
invalidates its reference; never reuse it to guess another target. The MCP tool list can
change as assigned targets change. `link_list_targets` lists only this agent's current
assignments. In the blocking non-MCP CLI path, each connected process
pipe owns one target and its connected response includes its own `target_ref`; keep calls
on that pipe. A one-shot local command must not guess among several sessions.

The authenticated discovery document is authoritative for this session. It contains:

- `api_version` and `registry_version`;
- endpoint, session expiry and grant version;
- granted `fast_start` operations with complete argument schemas;
- a compact catalog index and resource limits.

Use a `fast_start` operation without another catalog request when its supplied schema is
complete. Otherwise load only the operation's advertised catalog. Catalog presence describes
what can be discovered; the current authenticated grant remains authoritative for what can
be called.

Do not capture a screenshot automatically merely because a helper is advertised. When the user
asks for a current Mobile screenshot or the task requires visual evidence, prefer the
`local_fast_start.capture_to_file` helper supplied by VA Link's connected response. It writes and
verifies the JPEG directly at an absolute local path and returns only metadata and timings. Do not
retrieve screenshot Base64 through model context. This helper does not require loading this
reference or the artifact catalog first.

A canonical call is one JSON object:
  {"request_id":"UNIQUE","operation":"OPERATION","arguments":{}}

Use the discovered operation's `effect` to construct the envelope. `read_only` and `observation`
operations need neither field unless their schema says otherwise. Every other effect requires a
fresh 16-128 character `idempotency_key` and a `deadline` object. Normally use
`{"kind":"execute_by","unix_ms":NOW_PLUS_AT_MOST_300000}`. Use `accept_by` for
`mobile_companion_start` and `controller_wait_until` for a discovered wait operation. `unix_ms`
is the current UTC Unix epoch in milliseconds plus a short future interval, never more than five
minutes. Never add discovery fields such as `api_version`, `endpoint`, `session` or `catalogs` to
a call.

Every completed, accepted, failed or cancelled response includes `context_delta`. Retain the
highest observed `state_revision` and apply newer deltas before deciding the next action.
The small `state_revision`/`observed_at` cursor is always present; unchanged attributes are omitted.
Apply `cleared` first and then the other members of the same delta. In particular, a route or
endpoint handover clears stale `active_window`, `input`, `screen` and `windows` facts atomically.
Never let a delayed response with an older revision replace newer context. Local fast-start helpers
follow this same contract and return the relevant operation's delta with their compact result.
For Mobile, `screen` may report material camera facts such as `mode`, `calibrated`, `visible`,
`tracking` and `corners_inside_frame`; `input` reports current HID readiness. Surface a newly
returned loss of visibility/calibration or a display-mode change when it affects the user's test.
Use `context_snapshot` when a complete current view is needed and `context_events` only when
the authenticated schema requires recovery after a known revision.

Common bootstrap operations normally include session status/end, catalog list/get, context
snapshot, emergency input release, and endpoint-specific status or execution operations.
The exact `fast_start` array, not this prose, decides what is present in a particular session.

An accepted operation has not necessarily completed. Use its returned operation reference
with the discovered status/wait operation. Never repeat the original state-changing call.
Use artifact stat/read/release for bounded immutable data and verify advertised digest and
length. Call `session_end` only when maintenance is actually complete.

LARGE FILES AND COMMAND DATA

For an authorized direct Companion session, use `companion_transfer_upload` or
`companion_transfer_download` for large or binary files. Supply the local VA Link path and the
Companion path once: an explicit absolute target-user path such as `~/Downloads/video.mp4`, or
a relative path in the Companion workspace. VA Link performs encrypted framing, ordering,
progress, size and SHA-256 verification, cancellation and cleanup internally. Never split the
file into model-visible JSON/Base64 chunks. Upload creates a new destination and will not silently replace an existing
file. A completed download is returned as a verified absolute local file and, through MCP, a
resource link suitable for the host agent.

Use `companion_transfer_status` only when progress is useful and
`companion_transfer_cancel` to stop a known transfer. Ordinary session/context calls remain usable
while a transfer runs.

For normal commands prefer one `companion_exec_run`. It supports `shell` and `argv`, workspace
`cwd`, environment values, inline `stdin`, timeout and separate stdout/stderr. Upload large or
binary input first and pass its workspace path as `stdin_path`. Request
`stdout.overflow=artifact` when output may be large or binary; MCP then provides verified local
resources rather than putting their bytes in the model context.

For an execution result, `state=completed` means the API call finished; inspect the native
`result.exit_code`, `result.stderr`, timeout and truncation fields to judge the command. Text
stdout retains the target's line endings (typically LF on macOS/Linux, CRLF on Windows).
For a one-line success marker accept exactly one LF or CRLF; do not trim unrelated text or
turn a nonzero exit code into success. Use an artifact or file transfer with digest verification
when the exact bytes matter.

Use `companion_exec_open`, `write`, cursor-based `read`, `signal` and `close` only for genuinely
interactive or long-lived text processes. Live reads are long-polling and retain the newest
256 KiB. If `history_truncated` is true, older text was deliberately discarded; rerun a command
through `companion_exec_run` with artifact output when a complete result is required.
