PushConnector

Defined in: packages/client/src/lib/connection-manager/connector.types.ts:482

Extension for connectors that support server-initiated (push) messages.

Push messages are unsolicited responses from the engine, typically triggered by voice interactions where the engine responds without a client request.

Example

if ('onPushMessage' in connector) {
  (connector as PushConnector).onPushMessage((response) => {
    commandProcessor.setLayout(response.layout);
    commandProcessor.executeActions(response.executionPlan);
  });
}

Extends

• EngineConnector

Properties

capabilities

readonly capabilities: ConnectorCapabilities

Defined in: packages/client/src/lib/connection-manager/connector.types.ts:291

Connector capabilities. Metadata for consumers — the ConnectionManager does not use these for flow control.

Inherited from

EngineConnector.capabilities

Methods

addAssistantMessage()

addAssistantMessage(message): Promise<void>

Defined in: packages/client/src/lib/connection-manager/connector.types.ts:416

Add an assistant message to conversation history without LLM processing. Used for programmatic messages (greetings, notifications).

This legacy capability is fire-and-forget: it resolves after the transport accepts the send and does not confirm insertion. Use AcknowledgedAssistantConnector.addAssistantMessageAcknowledged when dependent side effects require a correlated engine outcome.

Parameters

message

AssistantMessage

Returns

Promise<void>

Inherited from

EngineConnector.addAssistantMessage

---

connect()

connect(sessionId): Promise<void>

Defined in: packages/client/src/lib/connection-manager/connector.types.ts:304

Establish the transport connection. Resolves when the connection is ready to use. Throws if the connection cannot be established (ConnectionManager retries).

For stateless transports (HTTP), this may be a no-op or a health check.

Parameters

sessionId

SessionId

The canonical session ID generated by the Provider/Orchestrator. Transports may use it to namespace server-side state (e.g. conversation history) so every channel of a session shares a single namespace with engine requests.

Returns

Promise<void>

Inherited from

EngineConnector.connect

---

disconnect()

disconnect(): Promise<void>

Defined in: packages/client/src/lib/connection-manager/connector.types.ts:310

Close the transport connection. For stateless transports (HTTP), this is a no-op.

Returns

Promise<void>

Inherited from

EngineConnector.disconnect

---

getHistory()

getHistory(sessionId): Promise<readonly SessionHistoryEntry[]>

Defined in: packages/client/src/lib/connection-manager/connector.types.ts:433

Fetch the engine-recorded history for the given session.

Used by clients that persist a session id and need to rehydrate the conversation after a refresh, on a different device, or in a parallel tab. The session id is supplied explicitly (not taken from the connector’s current connection) so callers can fetch any session they have an id for — including a session that predates the current orchestrator instance.

Implementations translate transport / engine errors into thrown Errors, matching the existing process and addAssistantMessage shape. Whether an unknown or empty session resolves to [] or rejects is the engine’s call (the reference engine resolves to []); connectors do not synthesize that behavior themselves.

Parameters

sessionId

SessionId

Returns

Promise<readonly SessionHistoryEntry[]>

Inherited from

EngineConnector.getHistory

---

onPushMessage()

onPushMessage(callback): Unsubscribe

Defined in: packages/client/src/lib/connection-manager/connector.types.ts:486

Subscribe to unsolicited responses from the engine.

Parameters

callback

(response) => void

Returns

Unsubscribe

---

process()

process(message): Promise<MaelstromResponse>

Defined in: packages/client/src/lib/connection-manager/connector.types.ts:323

Send a chart_request envelope to the engine and return the response.

The envelope (ChartRequestMessage) carries sessionId, id, and timestamp — used by the engine for response correlation and session routing. Implementations should use message.id for any request/response correlation logic.

Round-trip guarantee: the returned MaelstromResponse.requestId always equals message.id, regardless of the underlying transport.

Parameters

message

ChartRequestMessage

Returns

Promise<MaelstromResponse>

Inherited from

EngineConnector.process

---

subscribe()

subscribe(handler): Unsubscribe

Defined in: packages/client/src/lib/connection-manager/connector.types.ts:405

Subscribe to transport-level events.

THIS IS THE CRITICAL METHOD FOR CONNECTIONMANAGER

The ConnectionManager uses these events to:

• Detect unexpected disconnections and trigger auto-reconnect
• Update connection state (disconnected, error)
• Log transport errors for monitoring

Events to Emit:

disconnected (REQUIRED for stateful connectors)

Emit when the transport closes (cleanly or unexpectedly).

// Clean disconnect (user clicked disconnect button)
handler({ type: 'disconnected', clean: true, message: 'User disconnected' });

// Unexpected disconnect (network failure, server crash)
handler({ type: 'disconnected', clean: false, message: 'Network error' });

// Server rejected this client outright (e.g. WebSocket close code 1008) —
// retrying would just be rejected again, so flag it non-retryable.
handler({ type: 'disconnected', clean: false, message: 'Policy violation', retryable: false });

ConnectionManager behavior:

• clean: true → No auto-reconnect (intentional disconnect)
• clean: false → Auto-reconnect with exponential backoff
• retryable: false → Opens the circuit breaker immediately instead of auto-reconnecting, regardless of clean. Omit for the default clean-based behavior.

error (Optional but recommended)

Emit when transport-level errors occur (distinct from disconnects).

handler({ type: 'error', error: new Error('WebSocket error') });

Implementation Pattern:

subscribe(handler: (event: ConnectorEvent) => void): Unsubscribe {
  // Store the handler
  this.handlers.add(handler);

  // Set up transport event listeners
  this.ws.onclose = (event) => {
    handler({
      type: 'disconnected',
      clean: event.code === 1000,
      message: event.reason || `Closed with code ${event.code}`,
    });
  };

  this.ws.onerror = () => {
    handler({ type: 'error', error: new Error('WebSocket error') });
  };

  // Return unsubscribe function
  return () => this.handlers.delete(handler);
}

HTTP (Stateless) Implementation:

subscribe(_handler: (event: ConnectorEvent) => void): Unsubscribe {
  // HTTP never emits transport events
  return () => {};
}

Parameters

handler

(event) => void

Callback invoked when transport events occur

Returns

Unsubscribe

Unsubscribe function to remove the handler

See

CONNECTOR_GUIDE.md for detailed examples

Inherited from

EngineConnector.subscribe