This page is the architecture analysis for the hosted-agent-ops module. It complements the implementation pages by focusing on how diagnostics, telemetry, updates, and native helpers sit around the main runtime without entering its inner loop rather than re-listing each event name.
This module owns everything that observes or maintains the runtime without owning a model turn. It exists so the inner loop (lifecycle → context → tools → sessions) can stay focused while diagnostics, telemetry, updates, and binary support live behind narrow seams.
It deliberately does not own:
Tool execution (owned by the tools/security module).
Session persistence (owned by the sessions module).
Permission decisions (owned by the trust pipeline).
It only emits signals about them.
Architecture thesis
Ops is a passive periphery: it surfaces structured events, exposes user-facing maintenance commands, and provides binary helpers. Every ops surface is gated by a managed setting, an environment variable, or a CLI flag, so the runtime can be operated with strict observability or with no telemetry at all.
Source anchors
Semantic alias
Source
Approximate location
String or symbol
Architectural meaning
NativeUpdaterStartEvent
cli.js
line ~9355, byte 0xc257d7
tengu_native_auto_updater_start
Updater entry; runs out-of-band from the model loop.
NativeUpdaterLockEvent
cli.js
line ~9355, byte 0xc25b5c
tengu_native_auto_updater_lock_contention
Updater lock telemetry; multiple invocations are coordinated.
Capability/policy switches surfaced through ops UX.
Outputs
Output
Consumer
tengu_* event stream
Telemetry sink (when enabled).
Debug log files
Support tooling.
Doctor render
Terminal UX.
Updater state transitions
Settings/state file + telemetry.
Crash/error reports
Error sink (when enabled).
Status-line strings
Terminal UX.
Image/audio buffers
Attachment paths in the context/model loop.
Internal collaborators
Collaborator
Contract
Runtime lifecycle
Calls into ops in TopLevelMain (event-loop stall detector, profiling marks) and in preAction (sinks/logs/managed settings refresh).
Settings/policy
Provides the gates ops checks before emitting or persisting.
Sessions
Receives session_state_changed, transcript-mirror, and bridge-state frames that ops surfaces or logs.
Tools/security
Emits tool decision telemetry; ops aggregates and persists.
Updater backend
External binary fetch + checksum verification; result is recorded in settings/state.
Hosted review backend
/v1/ultrareview/preflight and related routes.
Native helpers
Bun resolves require("/$bunfs/root/...node") for image/audio addons.
Design decisions
Ops is observation, not control. The shutdown coordinator can flush analytics and disarm orphan handlers, but it does not interrupt model turns. Hard control still belongs to the lifecycle module.
All telemetry is gated. Managed settings, env vars, and CLI flags all participate; this is intentional so deployments can be strictly observable or strictly silent.
The updater runs out-of-band. Lock-contention telemetry shows the updater is designed for multi-invocation safety; it never blocks a running model turn.
Doctor is the canonical diagnostics surface. Other diagnostic frames (status line, debug logs) are complementary; doctor is the place to converge for support.
Native helpers are isolated. They are loaded by tiny JS shims (image-processor.js, audio-capture.js) and never participate in the trust pipeline or session state directly; they only produce buffers consumed by the context plane.
Error reporting is opt-in / opt-out at a coarse grain.DISABLE_ERROR_REPORTING short-circuits the reporter rather than reshaping individual call sites.
Profiling marks are part of the lifecycle, not a separate framework.import_time, cli_entry, main_function_start, run_function_start, preAction_* marks all flow through the same logger so support can read a single timeline.
Doctor preflight reports the fix-up message instead of silently failing.
Telemetry sink unreachable
Events buffer in-memory; shutdown flush still attempts delivery.
Native helper missing or fails to load
Attachment paths degrade; non-media flows are unaffected.
Status-line command errors
Status line is suppressed; loop continues.
Event-loop stall detector triggers
Diagnostic events emitted; runtime continues.
Hosted review preflight rejects
UX surfaces the result; local workflow is not blocked.
Extension points
Extension
How it plugs in
Additional telemetry sink
Register through the analytics-sink interface and rely on flushAnalyticsSinks.
Additional debug log channel
Use existing logger; do not invent a new file format.
New diagnostic check
Add to the doctor command rather than scattering checks across the runtime.
Status line customization
Use the statusLine / subagentStatusLine settings; treat as commands, not inline code.
Custom updater channel
Add to the auto-update settings enum; updater logic should not branch on out-of-band sources.
Native attachment type
Add a JS shim and a .node addon; attach via the existing attachment surface in the context module.
Caveats
The .node modules are stripped Linux x86-64 ELF shared objects; their internal symbols were not reverse-engineered here. They are part of the shipped payload but their concrete behavior is treated as a research opportunity.
Many tengu_* strings are runtime evidence; the precise sink schema is implementation-defined.
This module touches many other modules but owns no model-turn behavior; if a question is about what the model could do or see, it belongs to the context, tools, or sessions modules instead.
