feat(headless): expose negotiated native log observation
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user