feat(headless): expose negotiated native log observation

This commit is contained in:
2026-11-10 21:57:34 +00:00
parent 09d8778f04
commit c649e02816
17 changed files with 1830 additions and 11 deletions
@@ -30,7 +30,7 @@ and may terminate the process tree. There is no transport replay or durable queu
## Handshake and compatibility
The server first emits a `hello` object with `sessionId`, `protocolVersion`
(`major: 1, minor: 1`), real `runtimeVersion`, `capabilities` and `limits`.
(`major: 1, minor: 2`), real `runtimeVersion`, `capabilities` and `limits`.
Session identity is opaque and process-local, excluded from deterministic oracles.
Before work, the client sends `initialize` with `protocolVersion` and an array
@@ -81,6 +81,7 @@ operationId are a separate boundary, not part of this wire protocol.
| capture | empty object | PNG/base64 plus canonical frame metadata |
| get_state | empty object | pc, stackTop, logicalFrameIndex, tickIndex, appId, status |
| get_fault | empty object | fault object or null |
| get_logs | required afterSequence: null/uint64, limit: 1..1024 | native log page; requires negotiated 1.2 log_read |
| cancel | targetRequestId | acknowledgement that cancellation was requested for that active advance |
| shutdown | empty object | acknowledgement after the active operation stops and host is dropped |
@@ -177,6 +178,90 @@ structured faults, progress on partial failure and retained desktop run/debug.
Neither Studio UI nor an AI model is required. See `tests/automation_process.rs`
in prometeu-cli and the in-process deterministic-control tests in the headless crate.
## Native log observation
Protocol minor 1.2 adds capability `log_read`. Clients MUST negotiate minor >= 2
and include `log_read` in `requiredCapabilities` before using `get_logs`.
Requiring it with an older minor returns `incompatible_version`; using it without
negotiation returns `unsupported_capability`. Production clients negotiating 1.0
or 1.1 retain their existing command/result shapes and media behavior.
```json
{"requestId":"init","command":"initialize","params":{"protocolVersion":{"major":1,"minor":2},"requiredCapabilities":["log_read"]}}
{"requestId":"logs","command":"get_logs","params":{"afterSequence":null,"limit":128}}
```
Send each request after the preceding response. `afterSequence` is a required
nullable exclusive uint64 cursor. Null includes the first retained event, including
sequence zero. `limit` is required and MUST be an integer in 1..1024. Unknown fields,
missing parameters, strings/fractional/negative cursors and invalid limits return
`invalid_params`. A cursor greater than newest, or any non-null cursor on an empty
stream, returns `invalid_cursor`.
The result contains `sessionId`, `logEpoch`, `events`, `oldestSequence`,
`newestSequence`, `nextAfterSequence`, `gap` and `overflow`. Events include complete
`sequence`, `frame`, `timestampMs`, `level`, `source`, `appId`, `tag` and `message`.
Levels are `trace`, `debug`, `info`, `warn`, `error`; sources are `pos`, `hub`,
`vm`, `fs`, `app`. `appId` is uint32 for `app` and null for all other sources.
`tag` is uint16. Sequences, frames, timestamps and epochs are unsigned JSON uint64
integers; clients MUST decode them losslessly. Native elapsed-time timestamps
MUST NOT determine deterministic verdicts. Messages are native stored strings,
without assertion parsing, filtering, formatting or additional truncation.
Events are returned in increasing native sequence order across all sources.
Retained oldest/newest bounds are both null for an empty ring. The next cursor is
the final returned sequence, or the input cursor for an empty page. Requerying an
unchanged ring returns the same events; it never drains records. Reads MUST NOT
tick the firmware, execute guest code or change lifecycle, input, media or faults.
Existing single-operation admission applies: reading during an advance returns
`busy`. Complete envelope byte bounds apply: an oversized page or single event
returns `response_too_large`, without a partial result. Retry a smaller page if
appropriate; a single event that cannot fit remains an explicit error.
### Retention, cursors and reset
The ring retains at most 4096 native records. `overflow` reports whether retention
has ever evicted records in this log stream. It is historical information, not
proof of loss for this reader. `gap` reports missing history relative to the
requested cursor: null with retained oldest > 0, or a non-null cursor whose next
sequence is less than retained oldest. `overflow: true, gap: false` is a valid
page for a reader that consumed the evicted records already. Readers MUST use
cursor continuity and `gap` to detect unread retention loss, rather than reject
historical overflow alone. For example, oldest=100 and afterSequence=150 has no
gap; afterSequence=98 or null has a gap. No gap is hidden by source/tag filtering.
`logEpoch` is zero for the existing process-owned log stream. VM reset retains
the ring, native sequences and epoch; frame counters may reset independently.
It MUST NOT clear or renumber logs to simulate a new stream. A different process
has a different sessionId and its own sequence zero. Clients MUST bind cursors
and deduplication to sessionId/logEpoch; a numeric cursor alone is not a portable
identity between processes. A native sequence already applied MUST NOT be
applied again when inspecting overlapping pages.
### Producer limits and consumer responsibility
The unchanged guest logging path accepts at most 10 messages per application per
logical frame, with at most 256 UTF-8 bytes per message. Longer guest messages
are truncated before insertion; excess calls are dropped and produce one native
warning for that application/frame. Dropped calls receive no native sequence, and
truncation does not create a native gap. Consequently `gap: false` does not establish
that every attempted guest event was stored. Reading cannot recover those losses.
Structured-event consumers MUST bound their encoded messages and per-frame
emission, accounting for other logs from the same application. They MUST validate
their own producer event continuity and explicit completion (for example, ordinals
and final event counts), rejecting missing, malformed or incomplete reports.
The provider supplies generic native observations and does not interpret suites,
assertions or success. Do not enlarge guest budgets to transport test reports.
Consumers advancing the guest MUST read all pending pages before the next frame
block, including after boot and completion/failure when available. Choose
conservative blocks within actual retention headroom; `maxFrames` is an admission
ceiling, not a safe polling interval. At 10 app messages/frame, 600 frames can
already exceed the 4096-record ring, independently of system messages. Bounded
polling does not guarantee lossless delivery for arbitrary production rates or
unbounded work. Response loss MUST NOT trigger automatic advance replay.
## Memcard controls
Protocol minor 1.1 adds capability `memcard`. Initialize negotiates the lesser