AcknowledgedAssistantConnector

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

Connector that reports whether an assistant message was inserted or deduped.

Optional capability: EngineConnector.addAssistantMessage stays fire-and-forget. Detect support with isAcknowledgedAssistantConnector.

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

---

addAssistantMessageAcknowledged()

addAssistantMessageAcknowledged(message): Promise<AssistantMessageOutcome>

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

Insert an assistant message and wait for the engine outcome.

Unlike legacy EngineConnector.addAssistantMessage, this does not resolve merely because the transport accepted the send. It rejects when request construction or sending fails, the transport is not connected, the engine reports an error, the connection closes, or the bounded acknowledgement wait expires. A silent legacy server therefore times out rather than producing a false insertion result.

Parameters

message

AssistantMessage

Returns

Promise<AssistantMessageOutcome>

---

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

---

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