feat: stream agent events via subscriptions

[mattjohnsonpint]

Adds support for streaming events from agents via GraphQL Subscriptions over Server Sent Events (SSE).

The primary API exposed to the user is PublishEvent, which is a method on the agent they implement, along with a type definition for their custom events. Events can only be published from an agent - not directly from a function. The runtime will also emit status events for the agent automatically. In the future, there may be other types of events emitted.

To test:

• Build and run the agents example, from either the Go or AssemblyScript SDK.
• Launch the runtime to start the agents example.
• Launch the Modus API explorer in a browser window, and use it to interact with the agent.
• Start an agent and copy the generated Agent ID.
• Open Postman and post a subscription request to the Modus GraphQL endpoint (see notes below). This will start the subscription streaming, which you can observe while you interact with the agent via the Modus API Explorer.
  • Try updating the count, which should send countUpdated events.
  • Also observe events for agent status changes, such as suspended, resumed, and terminated

This PR also enables "passivation" in the actor system - which will automatically suspend the agent after 10 seconds of inactivity, and resume it automatically when needed.

There's also some bits in this PR for testing GoAkt's cluster mode, but that is unused for now and can be ignored safely. We'll expand on that in a future release.

Postman Instructions

In Postman, if you add a request of type GraphQL, its subscriptions will presume you are using WebSockets and the request will fail (since we use SSE). See postmanlabs/postman-app-support#13416

Instead, add a regular HTTP connection. Set the HTTP verb to POST, and select the GraphQL option when pasting the body, which should be as follows:

subscription AgentEvents($agentId: String!) {
    agentEvent(agentId: $agentId) {
        name,
        data,
        timestamp   
    }
}

Pass the variable containing the agent ID like this:

{
    "agentId": "d0jq2f5j5qn953grka40"
}

It should look like this:

Additionally, on the request headers, set Accept to text/event-stream to enable SSE.

Example event stream you can expect to receive (note, postman shows newest events on top):

Expected Client Usage

The implementation conforms to the GraphQL-SSE draft spec. Popular web clients should be able to follow the client usage recipes.

For example, if using urql, the urql subscription docs describe how to set up and use a "subscription exchange", and the urql section of the graphql-sse docs explain how to create a GraphQL-SSE based exchange that's compatible with urql.

[linear]

HYP-3415 GraphQL subscriptions for subscribing to agent event stream

[Copilot]

Pull Request Overview

This PR introduces support for streaming agent events via GraphQL Subscriptions over SSE and enables automatic passivation in the actor system. Key changes include:

• Adding a new GraphQL Subscription schema and SSE logic in the GraphQL handler.
• Introducing a host function “publishEvent” and an events data source for agent events.
• Refining the actor system initialization to support passivation and experimental cluster mode.

Reviewed Changes

Copilot reviewed 40 out of 40 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
runtime/httpserver/health.go	Replaces custom JSON header writing with explicit header setting.
runtime/hostfunctions/agents.go	Registers a new "publishEvent" host function.
runtime/graphql/schemagen/*	Adds new GraphQL schema types for agent events.
runtime/graphql/graphql.go	Implements SSE streaming logic for GraphQL subscriptions.
runtime/graphql/engine/engine.go	Updates datasource configuration types.
runtime/graphql/datasource/*	Refactors datasource planner and adds events and functions data sources.
runtime/actors/*	Updates agent actor lifecycle methods and introduces subscription actors.
runtime/actors/actorsystem.go	Adds experimental cluster mode configuration with dynamic port allocation.
CHANGELOG.md	Documents the new streaming agent events feature.

Comments suppressed due to low confidence (2)

runtime/actors/actorsystem.go:52

• Using dynamically allocated ports for cluster mode may work for testing, but consider making port configuration explicit for production deployments to ensure consistency and reliable discovery.

ports := dynaport.Get(3)

runtime/graphql/datasource/eventsds.go:44

• Since the subscription field name 'agentEvent' is used in multiple places, consider defining it as a constant to avoid potential typos and ensure consistency.

if subName := ci.FieldInfo.Name; subName != "agentEvent" {