agent_logging

How it works

get_log resolves the agent log path through a three-tier fallback — explicit agent.log_file config, then agent.data_dir/yuzu-agent.log, then platform default paths — and tails it line-by-line into a bounded deque, clamped to 500 lines. A log path that resolves to nothing is not an error: the action returns rc=0 with status|empty and line_count|0, while an out-of-range lines parameter returns rc=1 with status|error. Every fs::exists check in the path search deliberately uses the non-throwing error_code overload — the throwing form raised filesystem_error on EACCES and crashed the whole agent process on a macOS host with a restricted log directory.

get_key_files walks a fixed list of locations — the agent’s own executable path (via an OS-specific self-lookup), its log file, up to three config file names and two data-store file names under agent.data_dir, every regular file in agent.plugin_dir, and three TLS certificate/key config keys — emitting one file|<path>|<size>|<mtime> row per file actually found. A missing file, an unreadable size, or an unreadable mtime is skipped or zeroed rather than failing the whole action.

Neither action shells out or spawns a subprocess; both are native, in-process filesystem/config reads on every OS. This plugin is deliberately not a live log tail or a file-content reader: get_log re-reads the whole file on every call rather than streaming, and get_key_files reports paths, sizes and mtimes only — never file contents, including for the TLS private key it enumerates.

flowchart LR
  OP["Operator / workflow"] --> SRV["Server - authz: PluginSecret.Read get_log, Security.Read get_key_files"]
  SRV -->|"gRPC mTLS"| HOST["Agent plugin host"] --> EX["agent_logging.execute"]
  EX --> WIN["Windows leg - ifstream tail read / GetModuleFileNameA"]
  EX --> MAC["macOS leg - ifstream tail read / _NSGetExecutablePath + realpath"]
  EX --> LIN["Linux leg - ifstream tail read / proc self exe symlink"]
  WIN & MAC & LIN --> ROWS["key|value rows, no typed result status"] --> RS[("ResponseStore")] --> API["REST /api/responses"]

OS capability

Privileges and prerequisites

No external binaries, no subprocesses, no network access — both actions are native, in-process filesystem/config reads on every OS.

Data contract

Inputs

Outputs

Output is a stream of pipe-delimited key|value lines via write_output(), not typed row-per-record output. get_log emits log_file, line_count, then one line entry per tailed line — except when no log file resolves, where it emits only status|empty and line_count|0, or when lines is invalid, where it emits only status|error and returns non-zero; neither status value is a declared result column. get_key_files emits one file|<path>|<size>|<mtime> row per file found; a missing file is skipped outright rather than emitted as a placeholder row, so an empty result set here means literally nothing was found, not a signal of failure.

device.agent_logging.get_key_files — path|size|modified

device.agent_logging.get_log — log_file|line_count|line

Empty-result convention. get_log’s empty case is reported entirely through status|empty + line_count|0, never a placeholder log_file/line row. get_key_files simply emits zero file| rows when nothing is found — there is no placeholder row for this action.

Result status

This plugin does not set a typed result status; the agent records UNDECLARED and the sample shows UNDECLARED / UNKNOWN /.

Where the data goes

• Instruction result only. Rows travel over the agent’s response channel into the ResponseStore (default 90-day retention via reap_expired()), queryable at /api/responses/{id}.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX, or metrics. The plugin executes only when an operator or workflow dispatches device.agent_logging.get_log or device.agent_logging.get_key_files; outside agent_registry.cpp’s static action-description catalogue (a name/description list, not a data sink), no other server code references this plugin.
• Sensitivity. get_log’s line field is a verbatim tail of the agent’s log, which includes the line "Registered with server (session=..., ...)" — the agent’s live session credential — plus whatever other free text the agent logged, including file paths that may embed a username; get_key_files’s path rows can likewise embed a username or hostname in the file path. Neither action names installed third-party software.
• Siblings: none — no other plugin’s definition references agent_logging.
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("device.agent_logging.get_log"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}.

Sample output

Windows — captured: windows Microsoft Windows NT 10.0.26200.0 x64 · bare-metal · 2026-09-07 · SYSTEM · leg-hash 6e239e35ca05

== action=get_log
status|empty|agent log file not configured on this host
line_count|0
[result_status] UNDECLARED / UNKNOWN

== action=get_key_files
file|D:\yuzu-dev\Yuzu-worktrees\docs-plugin-readme-sweep\build-windows\tools\plugin-capture-tmp\plugin_capture.exe|64512|1788774930
[result_status] UNDECLARED / UNKNOWN

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-07 · euid 501 (jsmith) · leg-hash 6e239e35ca05

== action=get_log
status|empty|agent log file not configured on this host
line_count|0
[result_status] UNDECLARED / UNKNOWN

== action=get_key_files
file|/private/tmp/claude-501/-Users-jsmith-yuzu-dev/00000000-0000-0000-0000-000000000000/scratchpad/d2/plugin_capture|142208|1788774907
[result_status] UNDECLARED / UNKNOWN

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-06 · euid 0 · leg-hash 6e239e35ca05

== action=get_log
status|empty|agent log file not configured on this host
line_count|0
[result_status] UNDECLARED / UNKNOWN

== action=get_key_files
file|/src/builddir/tools/plugin-capture/plugin-capture|75168|1788720500
[result_status] UNDECLARED / UNKNOWN

Caveats and known gaps

1. get_log can expose the agent’s live session credential. The tailed log is the same file the agent writes "Registered with server (session={}, ...)" to (agents/core/src/agent.cpp:1928); get_log is classified under securable PluginSecret rather than plain Inventory for exactly this reason.
2. The declared result schema doesn’t name a status field. get_log’s empty path (status|empty, rc=0) and error path (status|error, rc=1) both emit a status key that the definition’s three columns (log_file, line_count, line) never declare.
3. No capture has ever resolved a log file. All three samples (Windows, macOS, Linux) returned status|empty — log_file and line have never been observed populated in a real run.
4. get_key_files reports the calling process’s own executable, not necessarily yuzu-agent’s. GetModuleFileNameA//proc/self/exe/_NSGetExecutablePath all resolve to whichever process is running the plugin; each sample here was captured through the plugin-capture harness, so its first file| row names the harness binary, not the production agent.
5. No typed result status is ever set. Every sample shows UNDECLARED / UNKNOWN / regardless of outcome — a caller must parse the status| output line itself to tell “no log configured” from “action failed”.

Source and tests

• Plugin: agents/plugins/agent_logging/src/agent_logging_plugin.cpp
• Definitions: content/definitions/agent_logging.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_b.hpp
• Tests: none found by name
• Privilege row: docs/agent-privilege-model.md (no row yet)