interaction

How it works

Four of the five actions dispatch a platform-native dialog or notification mechanism and report what happened; the fifth, set_dnd, is a pure local KV-store flag with no OS call. notify and survey first check whether Do Not Disturb is active and, if so, short-circuit to status|suppressed without ever spawning anything. Every dialog action validates its required parameters in the OS-agnostic dispatch layer before reaching a platform leg — a missing title never spawns a subprocess, on any OS. Text fields are then sanitized (metacharacters and quotes stripped) before being interpolated into an osascript/PowerShell script fragment; every spawn itself goes through the bounded argv runner with no shell involved end to end. The plugin never fabricates a dialog outcome: a non-zero exit, a runner-level failure, or an unreachable GUI session is always reported as an honest status|unavailable/status|not_reachable/status|error line rather than a guessed button or cancellation. It is deliberately not a general scripting surface — the only mechanisms it invokes are ShellNotifyIcon/MessageBoxW/PowerShell (Windows), notify-send/zenity (Linux), and osascript (macOS).

flowchart LR
  OP["Operator / workflow"] --> SRV["Server - authz: Infrastructure.Write"]
  SRV -->|"gRPC mTLS"| HOST["Agent plugin host"] --> EX["interaction.execute"]
  EX --> DND{"DND active? notify and survey only"}
  DND -->|"yes"| SUP["status suppressed"]
  DND -->|"no / n-a"| VAL{"required params present?"}
  VAL -->|"no"| ERR["status error"]
  VAL -->|"yes"| WIN["Windows leg - Shell_NotifyIconW / MessageBoxW / PowerShell InputBox / WinForms"]
  VAL -->|"yes"| MAC["macOS leg - osascript display notification / dialog"]
  VAL -->|"yes"| LIN["Linux leg - notify-send / zenity"]
  SUP & ERR & WIN & MAC & LIN --> ROWS["key|value rows"] --> RS[("ResponseStore")] --> API["REST /api/responses"]

OS capability

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

• input / macOS — no reachable GUI session under a headless/root LaunchDaemon
• message_box / macOS — no reachable GUI session under a headless/root LaunchDaemon
• notify / macOS — no reachable GUI session under a headless/root LaunchDaemon
• survey / macOS — no reachable GUI session under a headless/root LaunchDaemon

Privileges and prerequisites

Binaries/subprocesses: PowerShell (C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe, Windows input/survey) · osascript (/usr/bin/osascript, macOS all four dialog actions) · zenity and notify-send (/usr/bin/zenity, /usr/local/bin/zenity, /usr/bin/notify-send, /usr/local/bin/notify-send, Linux). No network access. set_dnd and Windows notify/message_box spawn nothing.

Data contract

Inputs

Outputs

Each action writes one or more key|value lines via write_output(). The dashboard/REST layer treats interaction as a key/value plugin and splits each line into exactly a key and the remainder of the line as its value — so a value can itself contain literal | characters, e.g. status|error|missing required parameter: title has key status and value error|missing required parameter: title. Not every declared column is written on every invocation: response/cancelled are mutually exclusive per action, and status appears only on a validation failure, a suppressed DND, or an undeliverable/failed dialog — a clean button press or clean survey completion never emits a status line at all.

device.interaction.input — response|cancelled|status

device.interaction.message_box — response|status

device.interaction.notify — status

device.interaction.set_dnd — dnd_enabled|dnd_duration_minutes|dnd_expires_at|status

device.interaction.survey — cancelled|question_count|answer_0|answer_1|answer_2|answer_3|answer_4|status

Result status

Where the data goes

• Instruction result only. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore (90-day default retention), queryable at /api/responses/{id}.
• Not consumed by daily-sync inventory, Echo, DEX, or metrics. Nothing runs on a schedule; the plugin executes only when an operator or workflow dispatches one of its five definitions. The dashboard’s generic key/value renderer is the only non-ResponseStore consumer of these rows.
• Sensitivity. Nothing beyond the device id. Every column is either an enum/bool the plugin itself computes (status, response button choice, cancelled, dnd_enabled, question_count) or free text the interactively-logged-in user typed into a dialog (response, answer_0–answer_4) — the schema targets no username, device identifier, or software name, though a user could in principle type anything into a free-text field.
• Siblings: none — no other plugin performs desktop notification/dialog interaction.
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("device.interaction.notify"). 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 dc6c8e5f72d5

== action=notify
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=message_box
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=input
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=survey
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=set_dnd
dnd_enabled|true
status|ok
[result_status] UNDECLARED / UNKNOWN

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

== action=notify
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=message_box
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=input
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=survey
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=set_dnd
dnd_enabled|true
status|ok
[result_status] UNDECLARED / UNKNOWN

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

== action=notify
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=message_box
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=input
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=survey
status|error|missing required parameter: title
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=set_dnd
dnd_enabled|true
status|ok
[result_status] UNDECLARED / UNKNOWN

Caveats and known gaps

1. No sample shows a real dialog. All three captures ran with zero parameters, so every dialog action failed validation before reaching a platform leg. response, cancelled, answer_0–answer_4, question_count, dnd_duration_minutes, and dnd_expires_at have no observed real value anywhere in this repo — see the code paths in Data contract → Outputs for what would populate them.
2. The macOS capture ran as an interactive user, not the production posture. It was taken at euid 501 (a logged-in human), not as the root LaunchDaemon the plugin actually ships under, so it cannot demonstrate the constrained “no reachable GUI session” path even though the descriptor declares macOS CONSTRAINED for all four dialog actions.
3. Honest-status is a hard invariant, not a bug to “fix.” Every dialog leg treats a non-zero exit, a runner failure, or an unreachable session as status|unavailable/status|not_reachable, never a fabricated button. A pre-0.3.0 version wrongly reported response|ok for an undelivered macOS dialog; do not reintroduce a catch-all “unrecognized output → ok” branch on any platform.
4. message_box’s status fires on every OS, not only macOS. It is set on a validation failure (missing title/message or a bad buttons value — all three OSes, confirmed by every sample), the macOS not_reachable sentinel, or a Linux zenity delivery failure — never only the macOS undeliverable path.
5. executeRoles differs per action. notify/set_dnd allow endpoint-operator; message_box/input/survey are endpoint-admin-only. Do not assume one roles line covers every action of this plugin.

Source and tests

• Plugin: agents/plugins/interaction/src/interaction_parsers.hpp · agents/plugins/interaction/src/interaction_plugin.cpp
• Definitions: content/definitions/interaction.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_d.hpp
• Tests: tests/unit/test_interaction_parsers.cpp
• Privilege row: docs/agent-privilege-model.md (no row yet)