48 lines
4.2 KiB
Markdown
48 lines
4.2 KiB
Markdown
# Session capture and Worker observation
|
||
|
||
Yoi uses one session-entry exploration domain for host-provided snapshots, Memory extraction evidence, and authorized observation of active Workers. The domain is implemented in `worker::session_capture` and has no Workspace or Memory mutation authority.
|
||
|
||
## Common capture contract
|
||
|
||
A host constructs an immutable ordered `SessionCapture` from committed session items. The capture:
|
||
|
||
- excludes reasoning before overview, search, read, or evidence projection;
|
||
- does not include the session system-prompt field;
|
||
- assigns an append-stable `SessionEntryRef` (`E...`) from the committed source position;
|
||
- uses the same reference in sparse overview anchors, search results, bounded reads, and Memory evidence conversion;
|
||
- pages sparse real user/assistant anchors and reports the number of non-reasoning entries between anchors;
|
||
- supports bounded range search and compact range listing when no filter is supplied;
|
||
- bounds read item count and bytes.
|
||
|
||
`SessionEntryRef` is local to the selected session subject. Runtime peers use the canonical `{ kind: "runtime_worker", runtime_id, worker_id }` reference; parent-owned children use `{ kind: "sub_worker", name }`. A model must first select a host-projected session and must reuse both the structured subject and entry references returned for that session.
|
||
|
||
## Independent features
|
||
|
||
The three feature modules share only the capture domain:
|
||
|
||
- `session-explore` installs `ShowOverview`, `SearchEntries`, and `ReadEntry` for one immutable host snapshot. It has no Workspace client or Memory state.
|
||
- `memory-extract` installs `StageMemoryCandidate` and `FinishMemoryExtraction`. It validates every staged `entry_ref` against its co-installed capture before converting it to typed Memory evidence.
|
||
- `worker-observation` installs `ListWorkerSessions`, `ViewSessionOverview`, `SearchSessionEntries`, and `ReadSessionEntry`. It captures the selected Worker again on every operation, so newly committed entries become visible while existing append-only references remain stable.
|
||
|
||
The features do not enable or mutate each other. Feature-registry collision checks remain authoritative for tool names.
|
||
|
||
## Observation authority
|
||
|
||
`WorkerObservationProvider` is a host-injected authority boundary. The Worker receives only an `Arc<dyn WorkerObservationProvider>`; model input never supplies grants, Workspace credentials, Runtime URLs, session handles, repository paths, or provider clients.
|
||
|
||
The provider must:
|
||
|
||
1. list only active subjects already granted to the current Worker;
|
||
2. reauthorize every capture instead of trusting a previous list result;
|
||
3. return the same not-found result for missing and unauthorized subjects;
|
||
4. return only committed session items;
|
||
5. keep subject identifiers opaque and bounded.
|
||
|
||
Runtime/Backend integrations enable the feature through the Backend-only `WorkerSpawnRequest.resolved_worker_observation_enabled` field, forwarded as `CreateWorkerRequest.worker_observation_enabled`. Canonical same-Runtime peers may also be supplied through `resolved_worker_observation_grants`; Runtime revalidates those against live weak handles and Workspace scope. For cross-Runtime peers and dynamically added Workers, `WorkspaceClientWorkerObservationProvider` calls the Workspace-scoped Server projection on every list/capture. Server authorizes that route against the current Workspace Orchestrator identity, recomputes the active Workspace Worker set, and reads the selected Worker’s committed protocol snapshot. Runtime binds these providers through `Worker::bind_worker_observation_provider` on spawn and restore. Parent-owned SubWorkers use the same provider contract through `SpawnedSubWorkerObservationProvider`; their subjects use the tagged `sub_worker` variant.
|
||
|
||
Observation is read-only evidence access. It does not authorize Ticket, Memory, Worker, or Workdir mutations and is not completion or approval authority.
|
||
|
||
## SubWorker output
|
||
|
||
SubWorkers no longer expose a separate output cursor tool. `SubWorkerList`, `SubWorkerSend`, and `SubWorkerStop` retain parent-owned lifecycle control, while committed child output is read through `worker-observation`. Turn-completion notifications carry no transcript and only tell the parent to inspect the authoritative committed session at a natural boundary.
|