Notifications

Notifications are ephemeral broadcasts that are not part of the state tree. They are not processed by reducers and are not replayed on reconnection.

JSON Schema: notifications.schema.json

Protocol Notifications

notify/sessionAdded 📄

Broadcast to all connected clients when a new session is created.

Field	Type	Description
type	NotificationType.SessionAdded
summary	SessionSummary	Summary of the new session

Example:

{
  "jsonrpc": "2.0",
  "method": "notification",
  "params": {
    "notification": {
      "type": "notify/sessionAdded",
      "summary": {
        "resource": "copilot:/<uuid>",
        "provider": "copilot",
        "title": "New Session",
        "status": 1,
        "createdAt": 1710000000000,
        "modifiedAt": 1710000000000
      }
    }
  }
}

notify/sessionRemoved 📄

Broadcast to all connected clients when a session is disposed.

Field	Type	Description
type	NotificationType.SessionRemoved
session	URI	URI of the removed session

Example:

{
  "jsonrpc": "2.0",
  "method": "notification",
  "params": {
    "notification": {
      "type": "notify/sessionRemoved",
      "session": "copilot:/<uuid>"
    }
  }
}

notify/sessionSummaryChanged 📄

Broadcast to all connected clients when an existing session's summary changes (title, status, modifiedAt, model, working directory, read/done state, or diff statistics).

This notification lets clients that maintain a cached session list — for example, the result of a previous listSessions() call — stay in sync with in-flight sessions without having to subscribe to every session URI individually. It is complementary to, not a replacement for, notify/sessionAdded and notify/sessionRemoved: those signal lifecycle (creation/disposal), while this signals summary-level mutations on an already-known session.

Semantics:

• Only fields present in changes have new values; omitted fields are unchanged on the client's cached summary.
• Identity fields (resource, provider, createdAt) never change and are not carried.
• Like all protocol notifications, this is ephemeral: it is not replayed on reconnect. On reconnect, clients should re-fetch the full catalog via listSessions() as usual.
• The server SHOULD emit this notification whenever any mutable field on {@link SessionSummary | SessionSummary} changes for a session the server has surfaced via listSessions() or notify/sessionAdded. Servers MAY coalesce or debounce updates for noisy fields (for example, modifiedAt bumps while a turn is streaming, or rapidly changing diffs) at their discretion.
• Clients that have no cached entry for session MAY ignore the notification; it is not a substitute for notify/sessionAdded.

Field	Type	Description
type	NotificationType.SessionSummaryChanged
session	URI	URI of the session whose summary changed
changes	Partial<SessionSummary>	Mutable summary fields that changed; omitted fields are unchanged.

Identity fields (resource, provider, createdAt) never change and MUST be omitted by senders; receivers SHOULD ignore them if present. |

Example:

{
  "jsonrpc": "2.0",
  "method": "notification",
  "params": {
    "notification": {
      "type": "notify/sessionSummaryChanged",
      "session": "copilot:/<uuid>",
      "changes": {
        "title": "Refactor auth middleware",
        "status": 8,
        "modifiedAt": 1710000123456
      }
    }
  }
}

Usage Pattern

Clients use notifications to maintain a local session list cache:

1. On connect, fetch the full session list via listSessions().
2. Listen for notify/sessionAdded and notify/sessionRemoved to track lifecycle, and notify/sessionSummaryChanged to patch cached summaries in place.
3. On reconnect, re-fetch the full list — notifications are not replayed.

Version Introduction

Notification Type	Version
notify/sessionAdded	1
notify/sessionRemoved	1
notify/sessionSummaryChanged	1

Server Notifications

In addition to protocol notifications, the server pushes action envelopes to subscribed clients:

action

Wraps an ActionEnvelope for delivery to subscribed clients:

{
  "jsonrpc": "2.0",
  "method": "action",
  "params": {
    "envelope": {
      "action": { "type": "session/delta", ... },
      "serverSeq": 43,
      "origin": { "clientId": "client-1", "clientSeq": 1 }
    }
  }
}