app_usage

How it works

app_usage answers “which executables ran on this machine, how often and for how long” without watching anything itself. The echo plugin’s process source records starts and stops; Echo’s usage fold pairs them into runs and keeps one row per executable per UTC day in echo.db. app_usage opens that file read-only, once per dispatch, and reports from it.

• summary totals the trailing days (default 30, 1-365) per executable, ranks them by run_time or run_count (by), returns the top top (default 25, 1-500) and adds a distinct-user count per executable. It leads with one meta row carrying the fold’s own health counters: coverage start, open runs, unmatched stops, clock anomalies, capture gaps and whether the feeder is running.
• last_used returns, per executable, first and last seen across everything Echo still retains, plus runs and seconds over the trailing 30 UTC days. exe narrows it to one executable and is reduced to a lowercase basename by the same rule Echo writes under. It is also the action the daily inventory sync calls.
• foreground always answers “not captured” (constrained, rc 0): this plugin does not capture focus time, and the Echo data it reads has none either.

summary and last_used first check that the file opens and passes a quick integrity check (foreground opens nothing), then read the usage_enabled setting and the usage_daily table, and reports a typed reason instead of an empty result when the source is off, mis-set or missing. It is deliberately not a monitor: it never writes echo.db, never selects a pid, command line or user name (users appear only as a count), and never accepts a database path from the caller.

flowchart LR
  OP["Operator or workflow"] --> SRV["Server: Forensics Read, AdminOrApproval"]
  SRV -->|"gRPC mTLS"| EX["app_usage plugin"]
  Echo["echo plugin: process source and usage fold"] --> DB[("echo.db: usage_daily, usage_daily_user, usage_live")]
  EX -->|"read-only open"| DB
  EX --> ROWS["rows and typed result status"]
  ROWS --> RS[("ResponseStore")] --> API["REST /api/responses"]
  EX -.->|"last_used, in-process, every 24 h"| SYNC["daily sync to the server"]

What you can decide with it

Per OS: on Windows the runs come from process start and stop events and on Linux from /proc (executable names are truncated to 15 characters there); both are supported. On macOS they come from Endpoint Security when the agent holds that entitlement and from polling otherwise, so short-lived processes can be missed and the timestamps are coarser; this is why macOS is constrained. You get no data, only a typed row saying why, when echo.db does not exist, fails its integrity check, or has the usage source switched off; last_used also answers with a typed row when Echo’s process or usage feeder is stopped, while summary only reports that in its meta row.

What a result does and does not prove: a populated summary on a healthy host lists the executables Echo saw run, over at most the last 31 days. It is wall-clock run time of the process, not interactive use, and it never says who used it beyond a count of accounts. History starts when the fold started; there is no “since install” figure. Use summary for a ranked picture, last_used for one executable or the full list, and read the meta row before treating either as complete.

Diagrams

Which result you get

flowchart TD
  A["Dispatch"] --> B{"echo.db opens read-only and passes quick_check?"}
  B -->|"no"| U["status UNAVAILABLE: echo_db_unavailable or echo_db_corrupt, rc 1"]
  B -->|"yes"| C{"usage_enabled"}
  C -->|"false"| D1["constrained: usage_source_disabled"]
  C -->|"unreadable or odd value"| D2["constrained: usage_source_errored"]
  C -->|"true or absent"| F{"last_used only: usage_feeder_enabled true?"}
  F -->|"false or absent"| D3["constrained: usage_feeder_disabled"]
  F -->|"unreadable or odd value"| D5["constrained: usage_feeder_errored"]
  F -->|"true, or summary"| T{"usage_daily table exists?"}
  T -->|"no"| D4["constrained: usage_schema_missing"]
  T -->|"yes"| Q["query, rows, OK"]

summary and last_used run these gates in this order and stop at the first one that fails; only the last box returns data. The feeder check applies to last_used only, because a stopped fold would otherwise keep serving an ageing window as if it were live; summary reports the same fact in its meta row instead.

From process start to a row

sequenceDiagram
  participant P as Echo process source
  participant F as Echo usage fold
  participant D as echo.db
  participant A as app_usage
  participant S as Server
  participant Y as Agent daily sync
  P->>F: process started and stopped events
  F->>D: open runs to usage_live, closed runs to usage_daily and usage_daily_user
  Note over D: daily rows kept 31 days
  S->>A: summary or last_used
  A->>D: read-only open, quick_check, config and table checks
  D-->>A: aggregates only
  A-->>S: rows and typed status
  Y->>A: last_used, in-process, every 24 h
  A-->>Y: rows, or constrained and skipped

Echo is the only writer; app_usage only reads aggregates, so a pid, command line or user name cannot reach a row. The daily sync calls last_used on the agent itself and skips a constrained answer rather than sending an empty replacement, so an off or broken source never wipes the server’s last good view.

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• foreground / Windows — foreground/focus time and per-session attribution are not captured; promoted by the user-context-bridge roadmap without a schema change
• foreground / macOS — foreground/focus time and per-session attribution are not captured; promoted by the user-context-bridge roadmap without a schema change
• foreground / Linux — foreground/focus time and per-session attribution are not captured; promoted by the user-context-bridge roadmap without a schema change
• last_used / macOS — inherits the process source’s names-only constraint; ES entitlement absent -> poll granularity
• summary / macOS — inherits the process source’s names-only constraint; ES entitlement absent -> poll granularity

Privileges and prerequisites

No external binaries, no subprocesses, no network access — every branch is a sqlite3_* call against an already-open handle; no popen/CreateProcess/socket call appears anywhere in app_usage_plugin.cpp or app_usage_parsers.hpp.

Data contract

Inputs

Outputs

Pipe-delimited rows via write_output(). summary emits exactly one meta row (fold health counters) followed by zero or more usage rows, most-active-first. last_used emits zero or more last_used rows, one per executable, ordered by exe_key. Every action’s failure path instead emits a single row in the shared <class>|<reason>[|<detail>] shape (constrained|..., unavailable|..., error|...) — described row-by-row in Result status below — never mixed with a meta/usage/last_used row in the same call.

crossplatform.app_usage.foreground — status|reason|detail

crossplatform.app_usage.last_used — exe_key|last_seen|first_seen|run_count_30d|total_seconds_30d

crossplatform.app_usage.summary — exe_key|run_count|total_seconds|first_seen|last_seen|distinct_users|superseded_runs|expired_runs

Result status

Where the data goes

• Instruction result. Every action’s rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore, queryable at /api/responses/{id}. Rows written by this plugin are served only to callers holding Forensics:Read on the stored-response read paths (REST legacy and v1, MCP, the dashboard including the executions drawer and the hardware result poll) and in the server’s own consumers of them (bundle collation, result-set membership, policy checks, the live output stream); other readers see them as absent, so an empty result does not imply that no data exists. A read that serves them is audited as response.forensics.read, in addition to the ordinary read row where the surface writes one (the dashboard results fragment writes only the forensics row; bundle collation writes this row too, with surface=bundle, next to its own bundle.collate row). Only the plugin name is stored with a row, so the filter works per plugin, not per action. A command’s failure text is reduced to a short machine token in the server’s derived copies of it (execution record, event outbox and stream, failure notification, analytics event, webhook and offload payload); the stored response row keeps the plugin’s own message and is served through the tier. The tier is decided by the plugin the server recorded when it dispatched the command, not by the command id the agent echoes back; a response with no server dispatch record is stored ~unverified and is served under the same tier.
• Also consumed by daily-sync. last_used is additionally invoked in-process (LocalDispatcher, no extra network hop) once per sync cycle by sync_source_app_usage.cpp (ADR-0016), once per 24 hours; the server persists the projection in AppUsageStore. A constrained capture is parsed and skipped (collect() returns std::nullopt) rather than sent as an empty replace, so a disabled/errored/schema-missing host never overwrites a previously-good server view with “zero usage”. summary and foreground are not sync sources — instruction-result only.
• Not consumed by Echo itself, DEX, or metrics — app_usage only reads echo.db; it emits no Prometheus series of its own.
• Sensitivity. Executable names and run times are a working-hours/presence proxy even with no user column at all — a host whose interactive tools (shell, editor, browser) cluster their usage_daily rows in a narrow daily window says something about when its operator is active, regardless of who that operator is. distinct_users is a COUNT(DISTINCT user) only; no user name, pid, or command line ever leaves the agent’s SQLite database — enforced by a grep-based test over the plugin’s own sources (test_app_usage_parsers.cpp) for the raw process-event table name and cmdline.
• Siblings: the echo plugin’s own usage-source query/export actions read the identical tables through Echo’s general-purpose action surface; app_usage is a narrower, purpose-built read with its own Forensics-gated approval posture and daily-sync integration.

Sample output

Windows — captured: windows Windows 10.0.26200 x86_64 · bare-metal · 2026-09-15 · interactive user (elevated) · leg-hash pending

== action=summary
constrained|echo_db_unavailable|C:\ProgramData\yuzu\agent\echo.db|unable to open database file
[result_status] UNAVAILABLE / PARTIAL / unable to open database file
[rc] 1

== action=last_used
constrained|echo_db_unavailable|C:\ProgramData\yuzu\agent\echo.db|unable to open database file
[result_status] UNAVAILABLE / PARTIAL / unable to open database file
[rc] 1

== action=foreground
constrained|foreground_not_captured|user-context-bridge roadmap (session-scope attribution)
[result_status] CONSTRAINED / PARTIAL / foreground/focus attribution not captured by this source

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-15 · euid 501 · leg-hash abdc9bc615f2

== action=summary
constrained|echo_db_unavailable|/var/lib/yuzu/agent/echo.db|unable to open database file
[result_status] UNAVAILABLE / PARTIAL / unable to open database file
[rc] 1

== action=last_used
constrained|echo_db_unavailable|/var/lib/yuzu/agent/echo.db|unable to open database file
[result_status] UNAVAILABLE / PARTIAL / unable to open database file
[rc] 1

== action=foreground
constrained|foreground_not_captured|user-context-bridge roadmap (session-scope attribution)
[result_status] CONSTRAINED / PARTIAL / foreground/focus attribution not captured by this source

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

== action=summary
constrained|echo_db_unavailable|/var/lib/yuzu/agent/echo.db|unable to open database file
[result_status] UNAVAILABLE / PARTIAL / unable to open database file
[rc] 1

== action=last_used
constrained|echo_db_unavailable|/var/lib/yuzu/agent/echo.db|unable to open database file
[result_status] UNAVAILABLE / PARTIAL / unable to open database file
[rc] 1

== action=foreground
constrained|foreground_not_captured|user-context-bridge roadmap (session-scope attribution)
[result_status] CONSTRAINED / PARTIAL / foreground/focus attribution not captured by this source

Caveats and known gaps

1. History is forward-only and bounded. usage_daily holds rows only from when the usage fold started on the host and Echo prunes it on a 31-day default, so a new agent or a source switched on late has no history for the gap. summary takes first and last seen from the requested window; last_used takes them from every retained row; neither is a lifetime figure.
2. foreground is always constrained. This plugin does not capture per-session focus time (the Echo data it reads has none), so every call reports CONSTRAINED/foreground_not_captured with rc 0 and never a hard failure. Nothing here can answer “how long was it in use”.
3. macOS granularity follows Echo’s process source. usage_daily is derived from the process fold, so without the Endpoint Security entitlement Echo polls, which can miss short-lived processes and coarsens first_seen, last_seen and run_count. The plugin cannot tell which regime produced a row.
4. Only as fresh as the feeder, and the unfiltered scan is not cost-bounded. last_used refuses a stopped feeder, but summary still returns OK over a frozen window, so read feeder_enabled and the coverage fields in its meta row. The 5000-row cap limits what is returned, not the scan and sort the unfiltered last_used query performs before the limit.
5. Samples show only the failure path. No capture host had a live echo.db, so every sample is echo_db_unavailable plus the constant foreground answer; a successful row has not been captured, and the Windows sample predates the owner check on echo.db and its sidecar files. Row shapes are as specified by the generated tables and the parser tests.

Source and tests

• Plugin: agents/plugins/app_usage/src/app_usage_parsers.hpp · agents/plugins/app_usage/src/app_usage_plugin.cpp
• Definitions: content/definitions/app_usage.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_app_usage.hpp
• Tests: tests/unit/server/test_app_usage_ingestion.cpp · tests/unit/server/test_app_usage_routes.cpp · tests/unit/server/test_app_usage_store.cpp · tests/unit/test_app_usage_local_dispatcher.cpp · tests/unit/test_app_usage_parsers.cpp
• Privilege row: docs/agent-privilege-model.md (no row yet)