The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! The domain event catalog: every cross-module event OpenHuman emits.
//!
//! This is the vocabulary half of what used to be `core::bus`. The
//! machinery half — the bus, the subscriber trait, the handle, the native
//! request registry — now lives in the `tinybus` crate; what stays here is the
//! part that is specific to OpenHuman and has no business in a generic bus.
//!
//! # Why these types are serializable now
//!
//! Events used to be delivered as Rust values inside one process. They now
//! travel over tinybus, which means they cross a process boundary and are
//! encoded as JSON. Two consequences worth knowing before adding a variant:
//!
//! - **Payloads must be plain data.** No `Arc`, no trait objects, no channels.
//! A cross-module call that needs those is a native request
//! (`tinybus::NativeRegistry`), not an event.
//! - **Adding a variant or a field is compatible; renaming or removing one is
//! not.** A subscriber built before the change has to keep parsing what a
//! publisher built after it emits.
//!
//! `domain()` is the routing key: it becomes the last element of the object
//! path the event is published at, so the broker can filter by domain and never
//! wake a process for events it did not ask for.
/// A tool call made while answering a committed turn: name and id only.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ConversationToolCall {
/// Tool name.
pub name: String,
/// Provider-assigned call id, when known.
pub id: Option<String>,
}
/// Top-level domain event. Non-exhaustive so new variants can be added
/// without breaking existing match arms.
#[non_exhaustive]
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub enum DomainEvent {
// ── Agent ───────────────────────────────────────────────────────────
/// An agent turn has started processing.
AgentTurnStarted { session_id: String, channel: String },
/// An agent turn completed with a final response.
AgentTurnCompleted {
session_id: String,
text_chars: usize,
iterations: usize,
},
/// A threaded conversation turn was durably committed. Memory logs the
/// turn itself (`memory::lifecycle::hooks`); this is for observers. Carries the turn text, as
/// `ChannelMessageProcessed` does; subscribers must never log it. Tool
/// calls carry names and ids only — never arguments.
ConversationTurnCommitted {
thread_id: String,
/// The agent definition that answered.
agent_id: Option<String>,
/// The agent's working folder (`action_dir`).
workspace: Option<String>,
/// The channel the turn arrived on (`web`, `telegram`, …).
channel: Option<String>,
user_text: String,
assistant_text: String,
tool_calls: Vec<ConversationToolCall>,
/// Workspace directory active when this event was published.
/// Subscribers that persist data load this workspace's config.
workspace_dir: std::path::PathBuf,
},
/// An error occurred during agent processing.
AgentError {
session_id: String,
message: String,
recoverable: bool,
},
/// A sub-agent was dispatched via `spawn_subagent`.
SubagentSpawned {
/// Parent agent's session id.
parent_session: String,
/// Sub-agent definition id (e.g. `code_executor`, `notion_specialist`, `fork`).
agent_id: String,
/// Spawn mode — `"typed"` or `"fork"`.
mode: String,
/// Per-spawn task id (UUID).
task_id: String,
/// Length of the prompt the parent passed in.
prompt_chars: usize,
},
/// A sub-agent finished successfully.
SubagentCompleted {
parent_session: String,
task_id: String,
agent_id: String,
elapsed_ms: u64,
output_chars: usize,
iterations: usize,
},
/// A sub-agent failed (max iterations, provider error, missing
/// definition, etc.). The error string is suitable for logging
/// and surfacing to the parent model.
SubagentFailed {
parent_session: String,
task_id: String,
agent_id: String,
error: String,
},
/// A sub-agent called `ask_user_clarification` and paused, waiting
/// for the orchestrator to relay the user's answer via
/// `continue_subagent`.
SubagentAwaitingUser {
parent_session: String,
task_id: String,
agent_id: String,
question: String,
},
/// High-level orchestration accepted a child agent for execution.
AgentOrchestrationSpawned {
session_id: String,
orchestration_id: String,
agent_id: String,
parent_agent_id: Option<String>,
},
/// High-level orchestration observed a child agent completion.
AgentOrchestrationCompleted {
session_id: String,
orchestration_id: String,
agent_id: String,
elapsed_ms: u64,
output_chars: usize,
iterations: usize,
},
/// High-level orchestration observed a child agent failure.
AgentOrchestrationFailed {
session_id: String,
orchestration_id: String,
agent_id: String,
error: String,
},
/// High-level orchestration closed or cancelled a child agent.
AgentOrchestrationClosed {
session_id: String,
orchestration_id: String,
reason: Option<String>,
},
// ── Run Queue ──────────────────────────────────────────────────────
/// A message was queued into the active-run queue instead of interrupting.
RunQueueMessageQueued {
thread_id: String,
mode: String,
queue_depth: usize,
/// Stable id of the queued item, when the run queue assigns one.
/// `None` until the queue implementation is updated to mint ids.
#[serde(default, skip_serializing_if = "Option::is_none")]
item_id: Option<String>,
/// Short, non-sensitive preview of the queued text (already
/// truncated by the publisher — never the raw message body at
/// full length). `None` until wired up.
#[serde(default, skip_serializing_if = "Option::is_none")]
text_preview: Option<String>,
},
/// A queued followup message was dispatched as a fresh turn after the
/// current turn completed.
RunQueueFollowupDispatched {
thread_id: String,
followup_count: usize,
#[serde(default, skip_serializing_if = "Option::is_none")]
item_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
text_preview: Option<String>,
},
/// The active turn was interrupted by a new message (default behavior).
RunQueueInterrupted {
thread_id: String,
cancelled_request_id: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
item_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
text_preview: Option<String>,
},
/// One or more queued steer/collect messages were delivered into a running
/// turn's steering handle (the harness applies them at the next iteration
/// checkpoint). Restores the delivery visibility the legacy
/// `RunQueueMessageDelivered` event provided before the TinyAgents migration
/// (issue #4456). `mode` is `"steer"` or `"collect"`.
RunQueueMessageDelivered {
thread_id: String,
mode: String,
delivered: usize,
#[serde(default, skip_serializing_if = "Option::is_none")]
item_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
text_preview: Option<String>,
},
/// Residual steer messages that the turn ended or was cancelled before
/// applying were drained back into the session run queue so they become the
/// next turn's input instead of silently vanishing (issue #4456).
RunQueueSteerRequeued {
thread_id: String,
requeued: usize,
#[serde(default, skip_serializing_if = "Option::is_none")]
item_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
text_preview: Option<String>,
},
// ── Monitor ───────────────────────────────────────────────────────
/// A background monitor changed lifecycle state.
MonitorStatusChanged {
monitor_id: String,
status: String,
thread_id: Option<String>,
description: String,
},
/// A background monitor emitted one bounded stdout/stderr line.
MonitorLine {
monitor_id: String,
thread_id: Option<String>,
timestamp_ms: u64,
stream: String,
line: String,
},
// ── Memory ──────────────────────────────────────────────────────────
/// The configured embedding provider is unreachable or the requested model
/// is not installed, so the memory pipeline fell back to an alternative.
///
/// Published by `memory_store::factories` (once per process via the
/// `OLLAMA_HEALTH_REPORTED` latch) so the UI can surface a user-visible
/// warning with an actionable fix hint. The `message` field is a
/// pre-formatted human-readable string safe to show in a notification.
EmbeddingModelUnhealthy {
/// Short provider slug, e.g. `"ollama"`.
provider: String,
/// The model that was intended but could not be reached / found,
/// e.g. `"bge-m3"`.
model: String,
/// The provider that will serve embeddings for this session instead,
/// e.g. `"cloud"`.
fallback_provider: String,
/// Human-readable explanation with an actionable fix,
/// e.g. `"Local embedding model unreachable — falling back to cloud
/// embeddings. Run \`ollama pull bge-m3\` to fix."`.
message: String,
},
/// A BYO (bring-your-own-key) chat provider rejected the configured API
/// key with `401` / `403` — the third-party key is invalid or revoked.
///
/// Published by `inference::provider::http_error::
/// log_byo_provider_auth_failure` (once per failure episode, via the
/// `auth_error_registry` latch — the underlying 401 repeats per retry).
/// The same rejection demotes the raw error from Sentry (it's
/// unactionable user-state), so this event is what keeps it visible to
/// the user: the notification bridge turns it into a core notification,
/// and the AI-settings panel reads the registry snapshot to render an
/// inline provider-error notice. The `message` field is a pre-formatted,
/// actionable string safe to show as-is.
ProviderApiKeyRejected {
/// Provider slug, e.g. `"openrouter"`.
provider: String,
/// Human-readable, actionable explanation (update the key in
/// Connections → API keys → LLM). See `auth_error_registry::auth_error_message`.
message: String,
},
/// A memory entry was stored.
MemoryStored {
key: String,
category: String,
namespace: String,
/// Chat thread of the turn whose tool call stored the entry; `None`
/// outside a chat turn (CLI, cron, queued background writes).
thread_id: Option<String>,
/// Client of that turn, for the web channel to fan the activity to.
client_id: Option<String>,
},
/// A memory recall query completed.
MemoryRecalled {
query: String,
hit_count: usize,
/// Chat thread of the turn whose tool call recalled; `None` outside a
/// chat turn.
thread_id: Option<String>,
/// Client of that turn.
client_id: Option<String>,
},
// ── Channels ────────────────────────────────────────────────────────
/// An inbound channel message from the transport layer, ready for processing.
///
/// `sender`, `reply_target`, and `thread_ts` are carried alongside
/// `channel` so the agent loop can derive per-sender conversation keys
/// the same way `channels::context::conversation_history_key` does for
/// other inbound paths — keying on `channel` alone collapses distinct
/// senders inside a shared channel into one cached session.
ChannelInboundMessage {
event_name: String,
channel: String,
message: String,
#[doc = "Originating user/account id within the channel. `None` for legacy publishers that don't surface it."]
sender: Option<String>,
#[doc = "Direct-message peer or group thread the reply should go to. `None` when the channel does not distinguish."]
reply_target: Option<String>,
#[doc = "Slack/Discord thread anchor when the message is in-thread. `None` for top-level messages."]
thread_ts: Option<String>,
raw_data: serde_json::Value,
},
/// A message was received on a channel.
ChannelMessageReceived {
channel: String,
message_id: String,
sender: String,
reply_target: String,
content: String,
thread_ts: Option<String>,
/// Provider-neutral envelope projected from the inbound channel message.
/// Legacy publishers may omit it until they adopt TinyChannels.
inbound_envelope: Option<tinychannels_bus::ChannelInboundEnvelope>,
/// Workspace directory active when this event was published.
/// Subscribers that persist data must reject events whose
/// `workspace_dir` does not match their own workspace binding.
workspace_dir: std::path::PathBuf,
},
/// A channel message was fully processed (LLM response sent or error).
ChannelMessageProcessed {
channel: String,
message_id: String,
sender: String,
reply_target: String,
content: String,
thread_ts: Option<String>,
response: String,
/// Provider route selected for the LLM turn.
provider: String,
/// Model route selected for the LLM turn.
model: String,
elapsed_ms: u64,
success: bool,
/// Workspace directory active when this event was published.
/// Subscribers that persist data must reject events whose
/// `workspace_dir` does not match their own workspace binding.
workspace_dir: std::path::PathBuf,
},
/// Retired legacy reaction callback payload, retained as an Events 1.x wire tombstone.
ChannelReactionReceived {
channel: String,
sender: String,
target_message_id: String,
emoji: String,
},
/// Retired legacy reaction callback payload, retained as an Events 1.x wire tombstone.
ChannelReactionSent {
channel: String,
target_message_id: String,
emoji: String,
success: bool,
},
/// A channel connected successfully.
ChannelConnected { channel: String },
/// A channel disconnected.
ChannelDisconnected { channel: String, reason: String },
// ── Cron ────────────────────────────────────────────────────────────
/// A cron job was triggered for execution.
CronJobTriggered {
job_id: String,
job_name: String,
job_type: String,
},
/// A cron job completed execution.
CronJobCompleted {
job_id: String,
success: bool,
output: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
tenant: Option<crate::core::runtime::Tenant>,
},
/// A proactive message requested for user delivery.
ProactiveMessageRequested {
/// Identifies the source (e.g. `"cron:morning_briefing"`, `"cron:welcome"`).
source: String,
/// The message content to deliver.
message: String,
/// Optional job name for display/threading purposes.
job_name: Option<String>,
/// The originating tenant; event subscribers execute outside the publisher task.
#[serde(default, skip_serializing_if = "Option::is_none")]
tenant: Option<crate::core::runtime::Tenant>,
},
/// A host-owned system cron job came due (a `flow`-type row whose command
/// is `system:<job>`, see `cron::system_jobs`). The owning domain runs it.
CronSystemJobDue {
/// The job name, e.g. `memory_context_refresh`.
job: String,
/// The tenant whose scheduler fired the job; `None` for the host's own.
#[serde(default, skip_serializing_if = "Option::is_none")]
tenant: Option<crate::core::runtime::Tenant>,
},
/// Live per-step progress of an in-flight `flows_run` / `flows_resume`
/// (issue G2, live run observation). Published from
/// `flows::observability::FlowRunObserver::on_step_finish` as each
/// non-trigger node settles, so the Workflows UI can show a run advancing
/// node-by-node instead of only polling the settled `flow_runs` row. The
/// durable `flow_runs` row (updated incrementally by the same observer and
/// finalized at settle) remains the source of truth — this event is a
/// best-effort progress feed (broadcast bridges drop on lag), which is why
/// the frontend keeps its 2s poller as a fallback.
FlowRunProgress {
/// The run's stable identifier (== the tinyflows checkpointer thread id).
run_id: String,
/// The node whose step just finished.
node_id: String,
/// Step outcome: `"success"` | `"error"`.
status: String,
},
/// A `flows_run` (or `flows_resume`) invocation just persisted its
/// `flow_runs` row, before execution begins (issue B35, runs-rail live
/// refresh). Published from `flows::ops::flows_run` right after
/// `start_flow_run_row` returns, so the UI can show "Running" immediately
/// instead of waiting for the blocking RPC to resolve or the first
/// `FlowRunProgress` step. Covers every run source (Rpc/Schedule/AppEvent/
/// Resume, incl. copilot live-run) since they all funnel through
/// `start_flow_run_row`.
FlowRunStarted {
/// The affected flow's id.
flow_id: String,
/// The run's stable identifier (== the tinyflows checkpointer thread id).
run_id: String,
},
/// The terminal companion to [`FlowRunStarted`] (issue B35 follow-up, runs
/// rail live finish). Published from `flows::ops::finish_flow_run_row`
/// right after `store::finish_flow_run` persists the terminal
/// `flow_runs` row, so the UI can flip a run to Completed/Failed live
/// instead of relying on a poll to notice the settled row.
FlowRunFinished {
/// The affected flow's id.
flow_id: String,
/// The run's stable identifier (== the tinyflows checkpointer thread id).
run_id: String,
/// Terminal status: `"completed"` | `"failed"` |
/// `"completed_with_warnings"` | `"cancelled"`.
status: String,
},
/// A saved flow's definition changed (created / updated / deleted /
/// enable-toggled). Bridged to a `flow:changed` socket event so an open
/// Workflows list or canvas refetches instead of silently showing stale
/// state — most importantly, so an agent `save_workflow` becomes visible in
/// a canvas the user has open (audit F6). Best-effort (broadcast bridges
/// drop on lag); the UI's own refetch-on-focus remains the backstop.
FlowChanged {
/// The affected flow's id.
flow_id: String,
/// What happened: `"created"` | `"updated"` | `"deleted"` |
/// `"enabled_changed"`.
kind: String,
/// Who made the change: `"agent"` | `"user"` | `"system"` — a coarse
/// hint for the UI banner ("an assistant edited this flow").
actor: String,
},
// ── Skills ──────────────────────────────────────────────────────────
/// A skill was loaded into the runtime.
WorkflowLoaded { skill_id: String, runtime: String },
/// A skill was stopped.
WorkflowStopped { skill_id: String },
/// A skill failed to start.
WorkflowStartFailed { skill_id: String, error: String },
/// A skill tool was executed.
WorkflowExecuted {
skill_id: String,
tool_name: String,
arguments: serde_json::Value,
result: Option<String>,
success: bool,
elapsed_ms: u64,
},
/// The set of installed skills/workflows changed (install / uninstall /
/// create). Lets a live agent session refresh its `## Installed Skills`
/// catalogue mid-conversation instead of waiting for a restart. `reason`
/// is a short tag for logs (e.g. `"install"`, `"uninstall"`, `"create"`).
WorkflowsChanged { reason: String },
// ── Tools ───────────────────────────────────────────────────────────
/// A tool execution started.
ToolExecutionStarted {
tool_name: String,
session_id: String,
},
/// A tool execution completed.
ToolExecutionCompleted {
tool_name: String,
session_id: String,
success: bool,
elapsed_ms: u64,
},
// ── Workspace isolation ─────────────────────────────────────────────
/// A TinyAgents workspace descriptor was prepared for an isolated run.
WorkspacePrepared {
/// Audit identity of the policy that produced the workspace.
policy_id: String,
/// Allowed workspace root.
root: String,
},
/// A TinyAgents workspace descriptor blocked an out-of-root path.
WorkspaceViolation {
/// Path that failed the descriptor's allowed-root policy.
path: String,
},
/// A TinyAgents workspace descriptor was cleaned up.
WorkspaceCleanup {
/// Audit identity of the policy whose workspace was cleaned up.
policy_id: String,
/// Cleanup error, when cleanup failed.
error: Option<String>,
},
// ── Approval ────────────────────────────────────────────────────────
/// Agent attempted a tool call that produces an external side effect;
/// awaiting user approval. Published by `ApprovalGate` before parking the
/// tool-call future. Carries no `session_id`: consumers need only the
/// request id plus optional chat thread/client routing.
ApprovalRequested {
/// Unique id used to correlate the decision back to the
/// parked future.
request_id: String,
/// Tool name being gated (e.g. `"composio"`, `"pushover"`).
tool_name: String,
/// Short human-readable summary of the action, redacted of
/// PII/secrets/message bodies (counts/shape only).
action_summary: String,
/// Redacted JSON arguments — also stripped of raw user content.
args_redacted: serde_json::Value,
/// Chat thread the gated call belongs to, when the turn originated
/// from a chat channel — lets the web channel route a `yes`/`no`
/// reply back to this request. `None` for non-chat callers.
thread_id: Option<String>,
/// Socket.IO client id (room) to surface the approval question to,
/// when known. `None` for non-chat callers.
client_id: Option<String>,
/// The gated tool call's provider-assigned call id, when the parked
/// call originated from a tracked tool-call turn. Lets a frontend
/// correlate the approval card back to the exact `tool_call` /
/// `tool_args_delta` timeline row instead of matching on tool name.
/// `None` until every publish site is updated to pass it through.
#[serde(default, skip_serializing_if = "Option::is_none")]
tool_call_id: Option<String>,
/// RFC3339 expiry of this pending approval, mirrored from
/// `PendingApproval::expires_at`. `None` when the approval has no
/// expiry or the publish site hasn't been updated yet.
#[serde(default, skip_serializing_if = "Option::is_none")]
expires_at: Option<String>,
/// The embedded agent whose turn parked this call, if any.
#[serde(default, skip_serializing_if = "Option::is_none")]
agent_id: Option<String>,
},
/// User decided a pending approval. Published by `approval_decide`
/// RPC handler after the gate's parked future resolves.
ApprovalDecided {
request_id: String,
tool_name: String,
/// `"approve_once"`, `"approve_always_for_tool"`,
/// `"approve_always_for_flow"`, or `"deny"`.
decision: String,
/// Chat thread the decided approval belongs to, mirrored from the
/// original `ApprovalRequested` so a socket bridge can route the
/// decision without re-looking up the (possibly already-cleared)
/// pending-approval record. `None` for non-chat callers and until
/// every publish site is updated.
#[serde(default, skip_serializing_if = "Option::is_none")]
thread_id: Option<String>,
/// Socket.IO client id (room), mirrored the same way.
#[serde(default, skip_serializing_if = "Option::is_none")]
client_id: Option<String>,
/// The gated tool call's provider-assigned call id, mirrored from
/// `ApprovalRequested::tool_call_id`.
#[serde(default, skip_serializing_if = "Option::is_none")]
tool_call_id: Option<String>,
/// Why the parked call resolved, when `decision` alone (`deny`)
/// can't say: `"expired"` (TTL/`expire_stale` sweep denied it with
/// nobody deciding) or `"cancelled"` (the decision channel dropped —
/// external turn teardown). `None` for an ordinary user-made
/// decision (approve or a deliberate deny).
#[serde(default, skip_serializing_if = "Option::is_none")]
resolution: Option<String>,
/// Mirrored from `ApprovalRequested::agent_id`.
#[serde(default, skip_serializing_if = "Option::is_none")]
agent_id: Option<String>,
},
/// A `Workflow`-origin tool call parked in the `ApprovalGate`. It carries
/// no `thread_id`/`client_id` (a flow run has neither), so the chat-routed
/// `web_chat::event_bus::ApprovalSurfaceSubscriber` ignores it. Published
/// by `ApprovalGate::intercept_audited` alongside `ApprovalRequested` and
/// bridged by `openhuman_rpc::server::socketio` to a broadcast
/// `flow_approval_request` Socket.IO event for the Workflows UI.
FlowApprovalRequested {
/// Unique id used to correlate the decision back to the parked
/// future — pass to `approval_decide` unchanged.
request_id: String,
/// The `flows::Flow` id whose run parked this call.
flow_id: String,
/// The run's stable identifier (== the tinyflows checkpointer
/// thread id).
run_id: String,
/// Tool name being gated (e.g. `"composio"`).
tool_name: String,
/// Short human-readable summary of the action (redacted, same as
/// `ApprovalRequested::action_summary`).
summary: String,
/// The embedded agent whose flow run parked this call.
#[serde(default, skip_serializing_if = "Option::is_none")]
agent_id: Option<String>,
},
// ── Egress (privacy spine) ──────────────────────────────────────────
/// An external data transfer is about to leave the device. Published by
/// [`crate::security::egress::emit_external_transfer`] from every
/// external-egress point (LLM inference, Composio tool calls, backend
/// integrations, network-fetch tools, cloud embeddings) *before* the
/// transfer, carrying an [`EgressDescriptor`](crate::security::egress::EgressDescriptor)
/// that answers "what leaves, to where, why". Privacy epic S2 (#4436).
///
/// Bridged to the `external_transfer_pending` web-channel socket event by
/// `EgressSurfaceSubscriber` (defined in
/// `crates/openhuman-core/src/web_chat/event_bus.rs`) when the emitting
/// turn carries chat routing. `thread_id` / `client_id` come from the
/// the egress ledger's chat routing and are `None` for CLI / cron /
/// background transfers (no chat surface to route to).
///
/// Only external transfers fire this event — local-only inference
/// (Ollama / LM Studio / …) never leaves the device and is not published.
ExternalTransferPending {
/// What leaves, to where, and why (plus S5 identification-risk fields,
/// default-empty until the detector lands).
descriptor: crate::security::egress::EgressDescriptor,
/// Chat thread the transfer belongs to, when the turn originated from a
/// chat channel. `None` for non-chat callers.
thread_id: Option<String>,
/// Socket.IO client id (room) to surface the disclosure to, when known.
/// `None` for non-chat callers.
client_id: Option<String>,
/// The turn this transfer was made under, from the ambient
/// `ApprovalChatContext::request_id`. `None` for non-chat callers, or
/// a chat caller that had no turn request_id in scope.
#[serde(default, skip_serializing_if = "Option::is_none")]
request_id: Option<String>,
},
// ── Plan review (interactive plan-mode gate) ────────────────────────
/// An interactive turn parked on a thread-scoped plan the user must
/// review before execution. Published by the OpenHuman notifier for
/// TinyAgents' plan-review store and bridged to the web channel as a
/// `plan_review_request` socket event.
PlanReviewRequested {
/// Unique id correlating the decision back to the parked turn.
request_id: String,
/// Chat thread the parked turn belongs to (routing). `None` for
/// non-chat callers (which auto-approve and never park here).
thread_id: Option<String>,
/// Socket.IO client id (room) to surface the review to, when known.
client_id: Option<String>,
/// One-line description of the plan.
summary: String,
/// Ordered plan steps shown in the review card.
steps: Vec<String>,
/// The gated tool call's provider-assigned call id, when the parked
/// turn originated from a tracked tool-call. `None` until every
/// publish site is updated to pass it through.
#[serde(default, skip_serializing_if = "Option::is_none")]
tool_call_id: Option<String>,
/// RFC3339 expiry of this pending plan review, mirrored the same
/// way as `ApprovalRequested::expires_at`.
#[serde(default, skip_serializing_if = "Option::is_none")]
expires_at: Option<String>,
},
/// User resolved a parked plan review. Published after the gate's parked
/// future wakes. `decision` is `"approve"` / `"reject"` / `"revise"`
/// (revise feedback is user content and is intentionally omitted).
PlanReviewDecided {
request_id: String,
decision: String,
/// Chat thread the decided review belongs to, mirrored from the
/// original `PlanReviewRequested`. `None` for non-chat callers and
/// until every publish site is updated.
#[serde(default, skip_serializing_if = "Option::is_none")]
thread_id: Option<String>,
/// Socket.IO client id (room), mirrored the same way.
#[serde(default, skip_serializing_if = "Option::is_none")]
client_id: Option<String>,
/// The gated tool call's provider-assigned call id, mirrored from
/// `PlanReviewRequested::tool_call_id`.
#[serde(default, skip_serializing_if = "Option::is_none")]
tool_call_id: Option<String>,
/// Why the parked review resolved when `decision` alone (`reject`)
/// can't say: `"expired"` (TTL) or `"cancelled"` (sender dropped —
/// external teardown). `None` for a real user decision.
#[serde(default, skip_serializing_if = "Option::is_none")]
resolution: Option<String>,
},
// ── Artifacts ───────────────────────────────────────────────────────
/// An artifact transitioned to [`ArtifactStatus::Ready`] — file
/// is on disk and ready to be downloaded. Published by
/// [`crate::artifacts::store::finalize_artifact`].
/// Bridged to the web channel as an `artifact_ready` socket event
/// when the publishing turn carries an `ApprovalChatContext`
/// (see [`crate::security::approval::ApprovalChatContext`]).
/// Sub-task #2779 of #1535.
ArtifactReady {
/// UUID of the artifact record.
artifact_id: String,
/// Lowercase variant of `ArtifactKind` (`presentation`,
/// `document`, `image`, `other`).
kind: String,
/// Human-readable title (also the on-disk filename stem).
title: String,
/// Absolute workspace root the artifact belongs to (matches
/// the `workspace_dir` parameter passed to
/// `finalize_artifact`). Bound to the event so a subscriber
/// firing AFTER the user switched workspaces can detect the
/// mismatch and drop the surface — `path` is workspace-
/// relative and would otherwise resolve into the wrong
/// `<workspace>/artifacts/` tree.
workspace_dir: String,
/// File name relative to its root (`"deck.pptx"` in the files folder,
/// legacy `"<uuid>/deck.pptx"`); the absolute path is reachable via
/// `ai_get_artifact` so the renderer never needs the
/// workspace root.
path: String,
/// Final on-disk file size in bytes.
size_bytes: u64,
/// Chat thread the artifact belongs to, when the producing
/// turn carried an `ApprovalChatContext`. `None` for CLI /
/// cron / sub-agent paths — no client to fan out to.
thread_id: Option<String>,
/// Socket.IO client id (room) to surface the card to, when
/// known. `None` for non-chat callers.
client_id: Option<String>,
/// The tool call that produced this artifact, when known — lets the
/// UI attach the finished card to that exact timeline row.
#[serde(default, skip_serializing_if = "Option::is_none")]
tool_call_id: Option<String>,
/// The turn/request id this artifact was produced under, when known.
#[serde(default, skip_serializing_if = "Option::is_none")]
request_id: Option<String>,
},
/// An artifact transitioned to [`ArtifactStatus::Failed`] — the
/// producer surfaced a reason and the UI should render a
/// retry-hint card instead of a download. Bridged the same way
/// as [`Self::ArtifactReady`]. Sub-task #2779 of #1535.
ArtifactFailed {
artifact_id: String,
kind: String,
title: String,
/// Absolute workspace root the artifact belongs to — see
/// [`Self::ArtifactReady::workspace_dir`] for rationale.
workspace_dir: String,
/// Producer-supplied failure reason. Already truncated by the
/// producer (e.g. `PresentationError::truncate_stderr`).
error: String,
thread_id: Option<String>,
client_id: Option<String>,
/// The tool call that produced this artifact, when known.
#[serde(default, skip_serializing_if = "Option::is_none")]
tool_call_id: Option<String>,
/// The turn/request id this artifact was produced under, when known.
#[serde(default, skip_serializing_if = "Option::is_none")]
request_id: Option<String>,
},
/// An artifact record has been **created** (`ArtifactStatus::Pending`)
/// but no bytes are on disk yet — the producing tool has only just
/// reserved the row. Published by
/// [`crate::artifacts::store::create_artifact`].
/// Bridged to the web channel as an `artifact_pending` socket event
/// so the frontend can render an in-progress / "Generating…" card the
/// moment the tool dispatches, instead of waiting until the file
/// arrives via [`Self::ArtifactReady`]. The pending card is replaced
/// in place when the matching `ArtifactReady` / `ArtifactFailed`
/// event with the same `artifact_id` arrives. Sub-task #3162 of #1535.
ArtifactPending {
/// UUID of the freshly-created artifact record.
artifact_id: String,
/// Lowercase variant of `ArtifactKind` (`presentation`,
/// `document`, `image`, `other`).
kind: String,
/// Human-readable title (also the on-disk filename stem).
title: String,
/// Absolute workspace root the artifact belongs to — see
/// [`Self::ArtifactReady::workspace_dir`] for rationale.
workspace_dir: String,
/// The name, relative to the visible files folder (#5505), the file
/// *will* land under. The frontend uses it to render a stable card key
/// so subsequent `ArtifactReady` can swap the same surface in
/// place without flicker.
path: String,
/// Chat thread the artifact belongs to, when the producing turn
/// carried an `ApprovalChatContext`. `None` for CLI / cron /
/// sub-agent paths — no client to fan out to.
thread_id: Option<String>,
/// Socket.IO client id (room) to surface the card to, when known.
/// `None` for non-chat callers.
client_id: Option<String>,
/// The tool call that reserved this artifact, when known.
#[serde(default, skip_serializing_if = "Option::is_none")]
tool_call_id: Option<String>,
/// The turn/request id this artifact was reserved under, when known.
#[serde(default, skip_serializing_if = "Option::is_none")]
request_id: Option<String>,
},
// ── Webhooks ────────────────────────────────────────────────────────
/// An incoming webhook request from the transport layer, ready for routing.
WebhookIncomingRequest {
request: crate::skills::webhooks::WebhookRequest,
raw_data: serde_json::Value,
},
/// A webhook was received and routed to a skill.
WebhookReceived {
tunnel_id: String,
skill_id: String,
method: String,
path: String,
correlation_id: String,
},
/// A webhook tunnel was registered to a skill.
WebhookRegistered {
tunnel_id: String,
skill_id: String,
tunnel_name: Option<String>,
},
/// A webhook tunnel was unregistered from a skill.
WebhookUnregistered { tunnel_id: String, skill_id: String },
/// A webhook request was fully processed (includes timing and status).
WebhookProcessed {
tunnel_id: String,
skill_id: String,
method: String,
path: String,
correlation_id: String,
status_code: u16,
elapsed_ms: u64,
error: Option<String>,
},
// ── Composio ────────────────────────────────────────────────────────
/// A Composio trigger webhook arrived via the backend socket.io bridge
/// and is ready for domain-specific dispatch.
ComposioTriggerReceived {
/// Toolkit slug, e.g. `"gmail"`.
toolkit: String,
/// Trigger slug, e.g. `"GMAIL_NEW_GMAIL_MESSAGE"`.
trigger: String,
/// Composio trigger event id (from backend metadata.id).
metadata_id: String,
/// Composio trigger UUID (from backend metadata.uuid).
metadata_uuid: String,
/// Provider-specific trigger payload.
payload: serde_json::Value,
},
/// A Composio connection OAuth handoff was initiated (connectUrl returned).
ComposioConnectionCreated {
toolkit: String,
connection_id: String,
connect_url: String,
/// The tenant that owns the connection; `None` for the host's own.
#[serde(default, skip_serializing_if = "Option::is_none")]
tenant: Option<crate::core::runtime::Tenant>,
},
/// A Composio connection was removed.
ComposioConnectionDeleted {
toolkit: String,
connection_id: String,
},
/// The connected Composio toolkit set changed (connect/revoke/config flip).
///
/// `toolkits` is the currently-active, sanitised slug list that should
/// drive orchestrator delegation schema rebuilds.
ComposioIntegrationsChanged { toolkits: Vec<String> },
/// A Composio action was executed (success or failure) via the backend.
ComposioActionExecuted {
tool: String,
success: bool,
error: Option<String>,
cost_usd: f64,
elapsed_ms: u64,
},
/// The user changed the Composio routing configuration — either the
/// mode (`"backend"` ↔ `"direct"`) flipped, or the direct-mode API
/// key was stored / cleared. Subscribers should treat any cached
/// tenant-scoped Composio state (connections, toolkit allowlists,
/// tool catalogues) as stale and re-fetch on next access. Published
/// by `composio_set_api_key` / `composio_clear_api_key`.
ComposioConfigChanged {
/// New routing mode after the change (`"backend"` or `"direct"`).
mode: String,
/// Whether a direct-mode API key is now present in the encrypted
/// store. The key itself is never carried on the event.
api_key_set: bool,
/// The tenant the change concerns; `None` for the host's own.
#[serde(default, skip_serializing_if = "Option::is_none")]
tenant: Option<crate::core::runtime::Tenant>,
},
// ── Triage ──────────────────────────────────────────────────────────
//
// Published by `crate::triage` when an external
// trigger (Composio webhook today, cron / webhook / other sources
// later) has been classified by the trigger-triage agent. The
// `source` field is a short slug like `"composio"` / `"cron"` so the
// events stay source-agnostic — any module that calls
// `triage::run_triage` will publish these.
/// A trigger event was evaluated by the triage agent and assigned
/// one of the four actions (drop / acknowledge / react / escalate).
TriggerEvaluated {
/// Where the trigger came from — `"composio"`, `"cron"`, …
source: String,
/// Source-specific stable id for this trigger occurrence.
external_id: String,
/// Human-friendly label, e.g. `"composio/gmail/GMAIL_NEW_GMAIL_MESSAGE"`.
display_label: String,
/// The classifier's action as a short string
/// (`"drop"` / `"acknowledge"` / `"react"` / `"escalate"`).
decision: String,
/// `true` if the triage turn ran on the local LLM, `false` if it
/// ran on the remote default provider.
used_local: bool,
/// Wall-clock time from envelope receipt to published decision.
latency_ms: u64,
},
/// Triage decided to hand the trigger off to another agent
/// (`trigger_reactor` for `react`, `orchestrator` for `escalate`).
/// Only fires for `react` / `escalate` — `drop` / `acknowledge` get
/// only a [`Self::TriggerEvaluated`] event.
TriggerEscalated {
source: String,
external_id: String,
display_label: String,
/// Agent definition id the trigger was handed off to.
target_agent: String,
},
/// Triage failed entirely — both local and remote attempts errored,
/// or the classifier reply could not be parsed after retry. Hooks
/// ops dashboards and future alerting.
TriggerEscalationFailed {
source: String,
external_id: String,
reason: String,
},
// ── Notification ────────────────────────────────────────────────────
/// An integration notification was ingested from an embedded webview.
NotificationIngested {
id: String,
provider: String,
account_id: Option<String>,
},
/// An integration notification's triage scoring completed.
NotificationTriaged {
id: String,
provider: String,
/// One of: "drop", "acknowledge", "react", "escalate"
action: String,
importance_score: f32,
latency_ms: u64,
/// True when the triage result was actually routed to the orchestrator path.
routed: bool,
},
// ── Inbound event queues ────────────────────────────────────────────
/// The inbound event queues ended an event without delivering it: a
/// redelivery of an event already taken, a gate or noise filter, or an
/// invalid envelope. `source` is the module source (`composio:<toolkit>`,
/// `webhook:<tunnel>`); `event_id` is the source's own id.
InboundEventDropped {
source: String,
event_id: String,
/// The module's reason, snake case (e.g. `duplicate`, `noise`).
reason: String,
},
/// Triage of a queued inbound event asked to run again later; the queue
/// redelivers it at `defer_until_ms` instead of dropping it.
InboundDeferred {
source: String,
event_id: String,
/// Unix epoch milliseconds the triage asked to run again at.
defer_until_ms: i64,
/// Already scrubbed; safe to log.
reason: String,
},
/// A queued inbound event will not be delivered: triage reached a terminal
/// state, or the delivery ran out of attempts. It is parked in the
/// dead-letter queue (`inbound.dead`, `inbound.redrive`).
InboundDeadLettered {
source: String,
event_id: String,
/// The delivery attempt that gave up.
attempt: u32,
/// Already scrubbed; safe to log.
detail: String,
},
/// A pinned source's batch ran on its agent and the agent's final text is
/// stored. Carries no text: a subscriber is woken by this and reads the
/// result over `inbound.results` (keyed by `turn_id`).
InboundTurnCompleted {
/// The configured source (`x:mentions`).
source: String,
/// The key the batch was debounced by.
key: String,
/// The queues' turn id, the result's key.
turn_id: String,
/// The source's ids of the events the batch carried.
event_ids: Vec<String>,
/// The pinned agent that ran.
agent_id: String,
},
/// A pinned source's batch failed for good (its last attempt failed, or
/// it failed after its delivery was acknowledged); stored as `failed`.
InboundTurnFailed {
source: String,
key: String,
turn_id: String,
/// Already scrubbed; safe to log.
detail: String,
},
// ── Device pairing ──────────────────────────────────────────────────
/// A mobile device completed the X25519 handshake and is now paired.
DevicePaired {
channel_id: String,
device_pubkey: String,
label: Option<String>,
},
/// A paired device's tunnel session was revoked.
DeviceRevoked { channel_id: String },
/// The backend tunnel reported the peer (device) came online.
DevicePeerOnline { channel_id: String },
/// The backend tunnel reported the peer (device) went offline.
DevicePeerOffline { channel_id: String },
/// An encrypted tunnel frame arrived from the device.
DeviceTunnelFrame {
channel_id: String,
payload_b64: String,
},
// ── MCP Clients ─────────────────────────────────────────────────────
/// A new MCP server was installed from the Smithery registry.
McpServerInstalled {
server_id: String,
qualified_name: String,
},
/// An MCP server subprocess connected and completed the initialize handshake.
McpServerConnected { server_id: String, tool_count: u32 },
/// An MCP server subprocess was disconnected or terminated.
McpServerDisconnected {
server_id: String,
reason: Option<String>,
},
/// An MCP client tool was invoked.
McpClientToolExecuted {
server_id: String,
tool_name: String,
success: bool,
elapsed_ms: u64,
},
/// A remote MCP server returned a tool whose `description` or
/// `title` failed the input-validation scan and was dropped from
/// the registry before reaching the agent LLM context. Surfaced for
/// audit / observability only; carries no payload content because
/// the rejected text could itself be a vector.
McpToolRejected {
/// Registered MCP server name the tool came from.
server: String,
/// Remote tool name as advertised by the server.
tool: String,
/// Short pattern / rule code from the validator (e.g.
/// `"override.ignore_previous"`). Never the rejected payload.
reason: String,
},
// ── MCP reconnect supervisor (#5931) ───────────────────────────────
//
// Published by `mcp::registry::supervisor_events` from the report
// TinyMCP's module-owned supervisor reports each minute. They are what puts
// a probe outcome on the developer Event Log, and what the notification
// bridge reads to tell the user about a server that stays down. An
// answered probe is deliberately not an event: one row per server per
// minute would bury everything else in the log.
/// A connected MCP server did not answer its liveness probe inside the
/// window, but the session was kept: a single slow answer is not
/// evidence of a drop. Only `teardown_after` consecutive timeouts end
/// the session, and that tick publishes
/// [`Self::McpServerTransportDropped`] instead of this.
McpServerProbeTimedOut {
server_id: String,
/// The registry's qualified name, e.g. `"ac.inference.sh/mcp"`.
qualified_name: String,
/// The probe window that elapsed, in seconds.
probe_timeout_secs: u64,
/// How many probes in a row have now timed out, this one included.
consecutive_timeouts: u32,
/// The streak length at which the session is torn down.
teardown_after: u32,
/// Workspace the supervised host belongs to.
///
/// One process supervises every workspace it has opened over its life
/// (`mcp::host::all_hosts`), and a workspace switch leaves the old
/// host open and still supervised. A subscriber that persists one of
/// these must therefore address the store by *this* field rather than
/// by its own workspace binding: the two disagree after a switch, in
/// whichever direction, and using the binding files one account's
/// outage under another's.
workspace_dir: std::path::PathBuf,
},
/// The supervisor ended an MCP server's session because its liveness
/// probe found the transport unusable. A reconnect follows in the same
/// tick and reports as [`Self::McpServerReconnected`],
/// [`Self::McpServerReconnectFailed`] or [`Self::McpServerParked`].
McpServerTransportDropped {
server_id: String,
qualified_name: String,
/// What the probe observed: `"broken"` (the transport answered with
/// an error), `"timed_out"` (the timeout streak reached its limit)
/// or `"missing"` (the entry went away between the membership check
/// and the probe).
outcome: String,
/// The transport error, already rendered and endpoint-redacted by
/// `tinymcp`. `None` unless `outcome` is `"broken"`.
detail: Option<String>,
/// How long the failing probe took, or the window that elapsed for a
/// timeout, in milliseconds. `None` for `"missing"`.
elapsed_ms: Option<u64>,
/// The timeout streak that ended the session; zero unless `outcome`
/// is `"timed_out"`.
consecutive_timeouts: u32,
/// Workspace the supervised host belongs to — see
/// [`Self::McpServerProbeTimedOut::workspace_dir`] for the rule
/// subscribers must apply.
workspace_dir: std::path::PathBuf,
},
/// The supervisor connected an MCP server, either rebuilding a session
/// it had just ended or bringing back one that had stayed down.
McpServerReconnected {
server_id: String,
qualified_name: String,
tool_count: u32,
/// How many consecutive attempts had failed before this one. Zero
/// means the session was rebuilt within the tick that ended it and
/// nobody noticed; anything else means the server's tools had been
/// unavailable across at least one whole tick, which is what the
/// notification bridge keys off to announce a recovery.
after_failures: u32,
/// Workspace the supervised host belongs to — see
/// [`Self::McpServerProbeTimedOut::workspace_dir`] for the rule
/// subscribers must apply.
workspace_dir: std::path::PathBuf,
},
/// The supervisor failed to connect an MCP server and will retry after
/// a backoff. Until a retry succeeds the server's tools are unavailable
/// to the agent.
///
/// Published once per attempt; the notification bridge notifies on the
/// first failure of an episode (`failures == 1`) only.
McpServerReconnectFailed {
server_id: String,
qualified_name: String,
/// The connection error, already rendered and endpoint-redacted.
error: String,
/// How many consecutive attempts have now failed, this one included.
failures: u32,
/// Seconds until the next attempt.
retry_in_secs: u64,
/// Workspace the supervised host belongs to — see
/// [`Self::McpServerProbeTimedOut::workspace_dir`] for the rule
/// subscribers must apply.
workspace_dir: std::path::PathBuf,
},
/// The supervisor gave up on an MCP server because the failure is one
/// retrying cannot fix — today, the launcher runtime (`npx` / `uvx`) is
/// not installed. The server stays parked until it is disabled and
/// re-enabled.
McpServerParked {
server_id: String,
qualified_name: String,
/// The failure, already rendered, including the install guidance
/// `tinymcp` attaches to a missing runtime.
error: String,
/// Workspace the supervised host belongs to — see
/// [`Self::McpServerProbeTimedOut::workspace_dir`] for the rule
/// subscribers must apply.
workspace_dir: std::path::PathBuf,
},
/// An `OPENHUMAN_APPROVAL_GATE=0` env override was observed but
/// IGNORED because the host is the Tauri desktop shell. The gate is
/// always installed under the desktop host; this event lets the UI
/// surface a one-shot info banner so the user sees the override was
/// rejected. Audit-only; carries no payload content.
ApprovalGateOverrideIgnored {
/// Host tag (currently always `"tauri-shell"` — added for forward
/// compatibility when more desktop hosts land).
host: String,
},
/// The approval gate was NOT installed because an
/// `OPENHUMAN_APPROVAL_GATE=0` env override was honored on a
/// standalone host (CLI / Docker). Surfaces the elevated-privilege
/// state so any connected dashboard can flag it; the desktop UI
/// banner subscribes to this variant.
ApprovalGateDisabled {
/// Host tag (`"cli"` or `"docker"`).
host: String,
/// Short reason code so downstream consumers can switch on the
/// cause without parsing free-text logs. Currently always
/// `"env-override"`.
reason: String,
},
// ── System lifecycle ────────────────────────────────────────────────
/// A system component started up.
SystemStartup { component: String },
/// A system component is shutting down.
SystemShutdown { component: String },
/// A restart of the current core process was requested.
SystemRestartRequested { source: String, reason: String },
/// A graceful shutdown of the current core process was requested.
/// Distinct from [`Self::SystemShutdown`] (per-component shutdown
/// notification) — this variant asks the running process to exit.
SystemShutdownRequested { source: String, reason: String },
/// The `[autonomy]` block (agent access mode / filesystem permissions) was
/// changed at runtime. Live sessions should rebuild their `SecurityPolicy`
/// from the persisted config before the next turn.
AutonomyConfigChanged,
/// The agent's filesystem roots (currently the `action_dir` sandbox) were
/// changed at runtime via `config.update_agent_paths`. The live
/// `SecurityPolicy` is hot-swapped in-band; this broadcast lets other
/// listeners observe the change.
AgentPathsChanged,
/// The process switched to a different workspace (#5966).
///
/// One process serves more than one workspace over its life — desktop
/// login, logout and pending-session revalidation all re-resolve it — and
/// until now that happened silently. Long-lived consumers had no way to
/// learn about a switch other than to re-read the marker on a timer, and a
/// process-wide stream like the Event Log had no way at all: it would keep
/// presenting the previous workspace's rows as the current ones.
///
/// Published by the config loader's cached-workspace write-through, and
/// only when the value actually changes — the loader itself runs on far
/// more than switches, and announcing every load would bury the real ones.
///
/// `workspace_dir` is for in-process consumers. Anything crossing to a
/// client sends
/// [`workspace_handle`](crate::config::workspace_handle)
/// instead, since the path is under the user's home directory.
ActiveWorkspaceChanged {
workspace_dir: std::path::PathBuf,
/// Monotonic revision of this transition.
///
/// The connect-time snapshot a client is seeded with and this
/// broadcast travel on separate tasks, so a snapshot resolved before
/// a switch can be delivered after it. Carrying the revision lets a
/// client keep the highest it has seen and discard anything older,
/// rather than being talked back into the previous workspace.
revision: u64,
},
/// A component's health status changed.
HealthChanged {
component: String,
healthy: bool,
message: Option<String>,
},
/// A component restart was observed.
HealthRestarted { component: String },
// ── Keyring ─────────────────────────────────────────────────────────
/// The OS keyring is unavailable and no user consent for local fallback
/// has been recorded. Published once (deduplicated) when a secret
/// operation hits the consent gate. The frontend surfaces a consent
/// dialog in response.
KeyringConsentRequired,
/// A secret field failed to decrypt (rotated master key, corrupted
/// ciphertext, keychain reset). Published so the frontend can surface
/// a recovery prompt instead of silently clearing the field.
KeyringDecryptFailed { field_name: String, reason: String },
// ── Auth ────────────────────────────────────────────────────────────
/// The local app session is no longer valid — typically detected when
/// the backend returns 401 to an LLM inference call or a JSON-RPC
/// method. Subscribers tear down the session and pause background
/// LLM-bound work until the user signs back in.
///
/// `source` is a short slug (e.g. `"llm_provider.openhuman_backend"`,
/// `"jsonrpc.invoke_method"`) so subscribers and logs can attribute
/// the trigger. `reason` is the sanitized error message that caused
/// detection (already redacted by the call site) — surfaced to logs,
/// never to Sentry or the UI verbatim.
SessionExpired { source: String, reason: String },
/// The backend credential this core holds was stored, replaced or
/// cleared (`auth.set_credential` / `auth.clear_credential`, including the
/// teardown after `SessionExpired`). `kind` is `session`, `api_key`,
/// `local` or `cleared` — never the credential itself. Subscribers that
/// cache credential-derived state (the search module's managed routes)
/// refresh on it.
CredentialChanged {
kind: String,
/// The tenant the change concerns; `None` for the host's own.
#[serde(default, skip_serializing_if = "Option::is_none")]
tenant: Option<crate::core::runtime::Tenant>,
},
// ── Task sources ─────────────────────────────────────────────────────
/// A task source completed a fetch pass.
TaskSourceFetched {
source_id: String,
provider: String,
fetched: usize,
routed: usize,
skipped: usize,
},
/// A single external task was ingested and routed onto the board.
TaskSourceTaskIngested {
source_id: String,
provider: String,
external_id: String,
title: String,
urgency: f32,
},
/// A task source fetch pass failed.
TaskSourceFetchFailed {
source_id: String,
provider: String,
error: String,
},
// ── Thread goals ──────────────────────────────────────────────────
/// A thread's goal was created, replaced, or transitioned state
/// (active/paused/budget_limited/complete). Drives the desktop goal chip.
ThreadGoalUpdated {
thread_id: String,
goal_id: String,
status: String,
/// Full goal snapshot (kept as a raw `Value` rather than a typed
/// field to keep this event independent of the harness tool type). `None`
/// until the publish site is updated to pass it through.
#[serde(default, skip_serializing_if = "Option::is_none")]
goal: Option<serde_json::Value>,
},
/// A thread's goal was cleared (deleted).
ThreadGoalCleared { thread_id: String },
/// A thread's session todo list changed (item added, checked, removed,
/// or reordered). Drives the desktop todo drawer.
ThreadTodosChanged {
thread_id: String,
/// Full todo-list snapshot, kept independent of the harness tool type.
todos: serde_json::Value,
},
// ── Plan mode ───────────────────────────────────────────────────────
/// A thread's [`tinyagents_harness::middleware::RunMode`] (Plan vs Build)
/// changed, via `agent.set_run_mode` or the `plan_exit` tool. Bridged to
/// the `run_mode_changed` web-channel socket event by
/// `crate::threads::run_mode::set_mode`'s caller.
ThreadRunModeChanged {
thread_id: String,
/// `"plan"` or `"build"` — see
/// `crate::threads::run_mode::mode_label`.
mode: String,
},
}
/// Truncate to `max` characters, appending `…` when anything was dropped.
///
/// Counted in `char`s, so a multi-byte error cannot be split mid-character.
/// The ellipsis is the point: without it a clipped provider error reads as if
/// it ended where it was cut, and a reader cannot tell a complete message from
/// a truncated one. Shared so the Event Log summary and the notification
/// bodies cannot drift into three different truncation rules — they had.
#[must_use]
pub fn clip_to_chars(text: &str, max: usize) -> String {
let mut out: String = text.chars().take(max).collect();
if text.chars().nth(max).is_some() {
out.push('…');
}
out
}
impl DomainEvent {
/// Returns the domain name for routing and filtering.
pub fn domain(&self) -> &'static str {
match self {
Self::AgentTurnStarted { .. }
| Self::AgentTurnCompleted { .. }
| Self::ConversationTurnCommitted { .. }
| Self::AgentError { .. }
| Self::SubagentSpawned { .. }
| Self::SubagentCompleted { .. }
| Self::SubagentFailed { .. }
| Self::SubagentAwaitingUser { .. }
| Self::AgentOrchestrationSpawned { .. }
| Self::AgentOrchestrationCompleted { .. }
| Self::AgentOrchestrationFailed { .. }
| Self::AgentOrchestrationClosed { .. }
| Self::RunQueueMessageQueued { .. }
| Self::RunQueueFollowupDispatched { .. }
| Self::RunQueueInterrupted { .. }
| Self::RunQueueMessageDelivered { .. }
| Self::RunQueueSteerRequeued { .. } => "agent",
Self::MonitorStatusChanged { .. } | Self::MonitorLine { .. } => "monitor",
Self::EmbeddingModelUnhealthy { .. }
| Self::MemoryStored { .. }
| Self::MemoryRecalled { .. } => "memory",
Self::ChannelInboundMessage { .. }
| Self::ChannelMessageReceived { .. }
| Self::ChannelMessageProcessed { .. }
| Self::ChannelReactionReceived { .. }
| Self::ChannelReactionSent { .. }
| Self::ChannelConnected { .. }
| Self::ChannelDisconnected { .. } => "channel",
Self::CronJobTriggered { .. }
| Self::CronJobCompleted { .. }
| Self::ProactiveMessageRequested { .. }
| Self::CronSystemJobDue { .. }
| Self::FlowRunProgress { .. }
| Self::FlowRunStarted { .. }
| Self::FlowRunFinished { .. }
| Self::FlowChanged { .. } => "cron",
Self::WorkflowLoaded { .. }
| Self::WorkflowStopped { .. }
| Self::WorkflowStartFailed { .. }
| Self::WorkflowExecuted { .. }
| Self::WorkflowsChanged { .. } => "workflow",
Self::ToolExecutionStarted { .. } | Self::ToolExecutionCompleted { .. } => "tool",
Self::WorkspacePrepared { .. }
| Self::WorkspaceViolation { .. }
| Self::WorkspaceCleanup { .. } => "workspace",
Self::WebhookIncomingRequest { .. }
| Self::WebhookReceived { .. }
| Self::WebhookRegistered { .. }
| Self::WebhookUnregistered { .. }
| Self::WebhookProcessed { .. } => "webhook",
Self::ComposioTriggerReceived { .. }
| Self::ComposioConnectionCreated { .. }
| Self::ComposioConnectionDeleted { .. }
| Self::ComposioIntegrationsChanged { .. }
| Self::ComposioActionExecuted { .. }
| Self::ComposioConfigChanged { .. } => "composio",
Self::TriggerEvaluated { .. }
| Self::TriggerEscalated { .. }
| Self::TriggerEscalationFailed { .. } => "triage",
Self::NotificationIngested { .. } | Self::NotificationTriaged { .. } => "notification",
Self::InboundEventDropped { .. }
| Self::InboundDeferred { .. }
| Self::InboundDeadLettered { .. }
| Self::InboundTurnCompleted { .. }
| Self::InboundTurnFailed { .. } => "inbound",
Self::DevicePaired { .. }
| Self::DeviceRevoked { .. }
| Self::DevicePeerOnline { .. }
| Self::DevicePeerOffline { .. }
| Self::DeviceTunnelFrame { .. } => "device",
Self::SystemStartup { .. }
| Self::SystemShutdown { .. }
| Self::SystemRestartRequested { .. }
| Self::SystemShutdownRequested { .. }
| Self::AutonomyConfigChanged
| Self::AgentPathsChanged
| Self::ActiveWorkspaceChanged { .. }
| Self::HealthChanged { .. }
| Self::HealthRestarted { .. } => "system",
Self::KeyringConsentRequired | Self::KeyringDecryptFailed { .. } => "keyring",
Self::SessionExpired { .. }
| Self::CredentialChanged { .. }
| Self::ProviderApiKeyRejected { .. } => "auth",
Self::TaskSourceFetched { .. }
| Self::TaskSourceTaskIngested { .. }
| Self::TaskSourceFetchFailed { .. } => "task_sources",
Self::ThreadGoalUpdated { .. }
| Self::ThreadGoalCleared { .. }
| Self::ThreadTodosChanged { .. }
| Self::ThreadRunModeChanged { .. } => "agent",
Self::ApprovalRequested { .. }
| Self::ApprovalDecided { .. }
| Self::ApprovalGateOverrideIgnored { .. }
| Self::ApprovalGateDisabled { .. }
| Self::FlowApprovalRequested { .. } => "approval",
Self::PlanReviewRequested { .. } | Self::PlanReviewDecided { .. } => "plan_review",
Self::ExternalTransferPending { .. } => "egress",
Self::ArtifactReady { .. }
| Self::ArtifactFailed { .. }
| Self::ArtifactPending { .. } => "artifact",
Self::McpServerInstalled { .. }
| Self::McpServerConnected { .. }
| Self::McpServerDisconnected { .. }
| Self::McpClientToolExecuted { .. }
| Self::McpToolRejected { .. }
| Self::McpServerProbeTimedOut { .. }
| Self::McpServerTransportDropped { .. }
| Self::McpServerReconnected { .. }
| Self::McpServerReconnectFailed { .. }
| Self::McpServerParked { .. } => "mcp_client",
}
}
/// Best-effort agent/session hint for display (not all events carry one).
pub fn agent_hint(&self) -> Option<&str> {
match self {
Self::AgentTurnStarted { session_id, .. }
| Self::AgentTurnCompleted { session_id, .. }
| Self::AgentError { session_id, .. } => Some(session_id.as_str()),
Self::SubagentSpawned { agent_id, .. }
| Self::SubagentCompleted { agent_id, .. }
| Self::SubagentFailed { agent_id, .. }
| Self::SubagentAwaitingUser { agent_id, .. }
| Self::AgentOrchestrationSpawned { agent_id, .. }
| Self::AgentOrchestrationCompleted { agent_id, .. }
| Self::AgentOrchestrationFailed { agent_id, .. } => Some(agent_id.as_str()),
Self::ChannelMessageReceived { channel, .. }
| Self::ChannelConnected { channel, .. }
| Self::ChannelDisconnected { channel, .. } => Some(channel.as_str()),
Self::ToolExecutionStarted { tool_name, .. }
| Self::ToolExecutionCompleted { tool_name, .. } => Some(tool_name.as_str()),
Self::WorkspacePrepared { policy_id, .. }
| Self::WorkspaceCleanup { policy_id, .. } => Some(policy_id.as_str()),
Self::WorkspaceViolation { path } => Some(path.as_str()),
Self::RunQueueMessageQueued { thread_id, .. }
| Self::RunQueueFollowupDispatched { thread_id, .. }
| Self::RunQueueInterrupted { thread_id, .. }
| Self::RunQueueMessageDelivered { thread_id, .. }
| Self::RunQueueSteerRequeued { thread_id, .. } => Some(thread_id.as_str()),
Self::MonitorStatusChanged { thread_id, .. } | Self::MonitorLine { thread_id, .. } => {
thread_id.as_deref()
}
// The Event Log's "agent" column is the only per-row context the
// stream carries, so an MCP row names its server there: the
// install id for the RPC-driven lifecycle, the registry name
// (`ac.inference.sh/mcp`) for the supervisor's verdicts, which is
// how a user knows the server and how the log lines name it.
Self::McpServerInstalled { server_id, .. }
| Self::McpServerConnected { server_id, .. }
| Self::McpServerDisconnected { server_id, .. } => Some(server_id.as_str()),
Self::McpServerProbeTimedOut { qualified_name, .. }
| Self::McpServerTransportDropped { qualified_name, .. }
| Self::McpServerReconnected { qualified_name, .. }
| Self::McpServerReconnectFailed { qualified_name, .. }
| Self::McpServerParked { qualified_name, .. } => Some(qualified_name.as_str()),
_ => None,
}
}
/// The workspace this event belongs to, for the variants bound to one.
///
/// One process serves more than one workspace over its life, so a
/// process-wide consumer — the Event Log, the `core_notification`
/// broadcast — has to be able to ask which workspace a given event came
/// from. Three families already carry the answer and each used to be read
/// by whoever happened to need it: `desktop::notifications` matched the
/// MCP arms in a private helper of its own, and silently did not gate the
/// channel and artifact families that carry the same field. This is the
/// one place that question is answered, so a consumer cannot cover a
/// subset by accident and a new workspace-bound variant has one arm to
/// add rather than several to find (#5966).
///
/// `None` means "not workspace-bound", which is the common case and is
/// **not** the same as "unknown workspace": a consumer filtering by
/// workspace should let these through rather than drop them.
///
/// The value is an absolute path under the user's home directory. It is
/// for in-process comparison only — anything that reaches a client or an
/// export sends
/// [`workspace_handle`](crate::config::workspace_handle)
/// instead.
#[must_use]
pub fn workspace_dir(&self) -> Option<&std::path::Path> {
match self {
// Channel — the workspace the inbound message was received under.
Self::ChannelMessageReceived { workspace_dir, .. }
| Self::ChannelMessageProcessed { workspace_dir, .. } => Some(workspace_dir.as_path()),
// Artifact — carried as a `String` because the producer takes it
// from a config field it already has as text; same meaning.
//
// An empty string reads back as "bound to the empty path", which
// matches no workspace and would therefore hide the event from
// every scoped consumer — a worse failure than not knowing. Today
// the producers pass a real `Path`, so this is a guard against a
// future one that does not, not a case that occurs.
Self::ArtifactReady { workspace_dir, .. }
| Self::ArtifactFailed { workspace_dir, .. }
| Self::ArtifactPending { workspace_dir, .. } => {
if workspace_dir.is_empty() {
None
} else {
Some(std::path::Path::new(workspace_dir))
}
}
// MCP reconnect supervisor (#5931).
Self::McpServerProbeTimedOut { workspace_dir, .. }
| Self::McpServerTransportDropped { workspace_dir, .. }
| Self::McpServerReconnected { workspace_dir, .. }
| Self::McpServerReconnectFailed { workspace_dir, .. }
| Self::McpServerParked { workspace_dir, .. } => Some(workspace_dir.as_path()),
// The switch itself is *about* a workspace rather than bound to
// one: it is what tells a consumer the active workspace changed,
// so filtering it out by the very rule it announces would hide
// the announcement from everyone who is not already up to date.
Self::ActiveWorkspaceChanged { .. } => None,
_ => None,
}
}
}
mod log_detail;
mod variant_names;
#[cfg(test)]
#[path = "events_tests.rs"]
mod tests;
impl tinybus::Event for DomainEvent {
fn domain(&self) -> &str {
// Delegates to the inherent method, which every variant is already
// matched in. Keeping one implementation means a new variant cannot
// route correctly for subscribers and incorrectly for the bus.
DomainEvent::domain(self)
}
}