Aleph
Gateway RPCMethods Reference

events.*

Event subscription and streaming RPC methods

events.* manages real-time event subscriptions over a WebSocket connection. All events flow through a single topic bus (src/gateway/event_bus.rs) and are filtered per connection by a SubscriptionManager.

Methods

MethodDescription
events.subscribeAdd topic subscriptions (additive)
events.unsubscribeRemove topic subscriptions
events.listList active subscriptions on this connection

Event Delivery

Events are delivered as JSON-RPC notifications (no id) over WebSocket, serialised from TopicEvent:

{
  "jsonrpc": "2.0",
  "method": "event",
  "params": {
    "topic": "agent.run.complete",
    "data": { "run_id": "run-uuid-123", "duration_ms": 5000 },
    "timestamp": 1706400000000
  }
}

Events are fire-and-forget: the server pushes without waiting for acknowledgement; events that fire while a client is disconnected are lost. Topic names come from GatewayEventFrame::topic_name() — see Event Topics.

events.subscribe

Subscribe to one or more topics. Subscriptions are additive — repeated calls append patterns without affecting existing ones.

Request (patterns only):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "events.subscribe",
  "params": {
    "topics": ["agent.run.*", "session.*"]
  }
}

Request (with field filter):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "events.subscribe",
  "params": {
    "topics": [
      "agent.run.*",
      { "topic": "tools.changed", "where": [{ "field": "scope", "equals": "extension" }] }
    ]
  }
}

Response:

{ "jsonrpc": "2.0", "id": 1, "result": { "subscribed": ["agent.run.*", "session.*"], "changed": 2 } }

Parameters:

ParameterTypeRequiredDescription
topicsarrayYesArray of topic selectors; each is a string pattern or {topic, where} filter object

Each where predicate is { "field": "<json_path>", "equals": <value> }; the event is delivered only when the payload field strictly equals the value. When no payload is available, predicates are skipped (the event is dropped, never blindly passed through).

events.unsubscribe

Remove patterns by exact match. A pattern is removed only if it matches the subscribed form exactly.

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "events.unsubscribe",
  "params": { "topics": ["agent.run.*"] }
}

Response:

{ "jsonrpc": "2.0", "id": 2, "result": { "subscribed": ["session.*"], "changed": 1 } }

events.list

List every active pattern on this connection.

Request:

{ "jsonrpc": "2.0", "id": 3, "method": "events.list" }

Response:

{ "jsonrpc": "2.0", "id": 3, "result": { "subscribed": ["session.*"] } }

Event Topics

Topics are grouped by namespace; a single events.subscribe call can subscribe to multiple groups via wildcards.

Run / Agent Lifecycle (run.*, agent.*)

TopicDescription
run.acceptedRun queued and started
agent.reasoningReasoning-phase output
agent.reasoning.blockReasoning block (dual-process cognition)
agent.tool.startTool call begins
agent.tool.updateTool progress update
agent.tool.endTool call ends
agent.traceExecution-trace event
agent.response.chunkResponse text chunk
agent.context.gaugeContext-window utilisation
agent.run.completeRun completed successfully
agent.run.errorRun failed
agent.run.retryingFailure-driven retry
agent.ask.userask_user clarification request
agent.clarification.endedClarification round resolved
agent.uncertaintyModel uncertainty signal
agent.model.resolvedModel selection resolved

Session / Running Set

TopicDescription
session.updatedSession metadata update
session.lifecycle.changedSession lifecycle phase change
running.set.changedActive-run set change

Channels

TopicDescription
channel.messageInbound message
channel.typingTyping indicator
channel.statusChannel runtime status
channel.errorChannel error

Config / Approvals

TopicDescription
config.changedConfiguration change (file-watcher hot-reload or RPC)
approval.requested / approval.resolved / approval.expiredApproval lifecycle

Cron / Heartbeat

TopicDescription
cron.job.changedCron job change (including cron.run triggers)
heartbeat.task.changedHeartbeat task change

Teams / ACP / Gateway Credentials

TopicDescription
team.changedTeam composition or task change
acp.sessions.changedACP session set change
gateway.token.rotatedGateway token rotation
gateway.device.revokedDevice revocation

Surfaces / Runtimes

TopicDescription
surface.notifySurface-level notification
surface.approvalSurface approval request
runtimes.install.progressRuntime install progress (step / log / done / failed)

Glob Pattern Matching

Subscription patterns use glob-style matching (src/gateway/event_bus.rs::topic_matches):

PatternMatches
agent.run.*agent.run.started, agent.run.complete, etc.
agent.*Every event under the agent. prefix
*Every event
agent.run.completeExact match only
*.completeAny event ending in .complete

* matches a single non-dot segment; patterns match against the full topic string.

Typical Client Flow

// 1. Subscribe to relevant topics
{ "jsonrpc": "2.0", "id": 1, "method": "events.subscribe", "params": { "topics": ["agent.*", "session.*"] } }

// 2. Start a run
{ "jsonrpc": "2.0", "id": 2, "method": "agent.run", "params": { "input": "Check disk usage" } }

// 3. Receive events (no id = notification)
{ "jsonrpc": "2.0", "method": "event", "params": { "topic": "run.accepted", "data": { "run_id": "run-123" } } }
{ "jsonrpc": "2.0", "method": "event", "params": { "topic": "agent.response.chunk", "data": { "run_id": "run-123", "content": "Disk usage is at 45%..." } } }
{ "jsonrpc": "2.0", "method": "event", "params": { "topic": "agent.run.complete", "data": { "run_id": "run-123", "duration_ms": 4200 } } }

See Also

cron.*

Scheduled job management RPC methods

heartbeat.*

Heartbeat task RPC methods

On this page

MethodsEvent Deliveryevents.subscribeevents.unsubscribeevents.listEvent TopicsRun / Agent Lifecycle (run.*, agent.*)Session / Running SetChannelsConfig / ApprovalsCron / HeartbeatTeams / ACP / Gateway CredentialsSurfaces / RuntimesGlob Pattern MatchingTypical Client FlowSee Also