@aintela/chat 0.4.37 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/dist/components.js +7075 -7049
  2. package/dist/components.js.map +1 -1
  3. package/dist/hooks.js +1 -1
  4. package/dist/httpArtifactService-EEhF_mp9.js +1744 -0
  5. package/dist/httpArtifactService-EEhF_mp9.js.map +1 -0
  6. package/dist/{httpSessionService-CUujaUo6.js → httpSessionService-wBby4ggl.js} +51 -53
  7. package/dist/httpSessionService-wBby4ggl.js.map +1 -0
  8. package/dist/index.js +232 -227
  9. package/dist/models.js +1 -1
  10. package/dist/{serializer-DX-yGa_k.js → serializer-CC-nM3ig.js} +497 -498
  11. package/dist/serializer-CC-nM3ig.js.map +1 -0
  12. package/dist/services.js +12 -10
  13. package/dist/src/components/AiChat/ChatPane/CurrentMessage.d.ts +9 -9
  14. package/dist/src/components/AiChat/ChatPane/Message.d.ts +1 -3
  15. package/dist/src/components/AiChat/ChatPane/MessageAgent.d.ts +9 -8
  16. package/dist/src/components/AiChat/ChatPane/MessageScope.d.ts +32 -0
  17. package/dist/src/components/AiChat/ChatPane/MessageUser.d.ts +0 -1
  18. package/dist/src/components/AiChat/ChatPane/StickyQuestionHeader.d.ts +0 -1
  19. package/dist/src/components/AiChat/ChatPane/groupParts.d.ts +32 -0
  20. package/dist/src/components/AiChat/ChatPane/parts/ConnectionOutagePart.d.ts +9 -0
  21. package/dist/src/components/AiChat/ChatPane/parts/types.d.ts +6 -4
  22. package/dist/src/components/AiChat/ChatPane/reasoningHeadlines.d.ts +4 -9
  23. package/dist/src/components/AiChat/sessionStateManagerService.d.ts +36 -35
  24. package/dist/src/components/AiChat/stateConfiguration.d.ts +18 -0
  25. package/dist/src/components/index.d.ts +6 -2
  26. package/dist/src/interfaces/index.d.ts +0 -1
  27. package/dist/src/models/Interaction.d.ts +0 -9
  28. package/dist/src/models/InteractionPart.d.ts +4 -3
  29. package/dist/src/models/Notification.d.ts +7 -1
  30. package/dist/src/models/ServerEvent.d.ts +4 -0
  31. package/dist/src/models/index.d.ts +1 -1
  32. package/dist/src/services/WebSocketConnection/WebSocketConnectionV2.d.ts +28 -108
  33. package/dist/src/services/WebSocketConnection/closeCodes.d.ts +24 -0
  34. package/dist/src/services/WebSocketConnection/streamStats.d.ts +41 -0
  35. package/dist/src/services/WebSocketConnection/streamStats.test.d.ts +1 -0
  36. package/dist/src/services/WebSocketConnection/webSocketConnection.d.ts +15 -12
  37. package/dist/src/services/eventBusService.d.ts +28 -67
  38. package/dist/src/services/index.d.ts +2 -1
  39. package/dist/src/services/interaction/reduceInteraction.d.ts +28 -0
  40. package/dist/src/services/interactionService.d.ts +15 -32
  41. package/dist/src/services/interactionService.invariants.test.d.ts +1 -0
  42. package/dist/src/services/servers/AgentGatewayService.d.ts +3 -182
  43. package/dist/src/services/servers/AgentGatewayWSAsync.d.ts +145 -46
  44. package/dist/src/services/servers/connectionSupervisor.d.ts +173 -0
  45. package/dist/src/services/servers/connectionSupervisor.test.d.ts +1 -0
  46. package/dist/src/services/servers/connectionSupervisor.wire.test.d.ts +0 -0
  47. package/dist/src/services/servers/gatewayErrorClosesTurn.test.d.ts +1 -0
  48. package/dist/src/services/servers/gatewayFixes.test.d.ts +1 -0
  49. package/dist/src/services/servers/throttledEmit.test.d.ts +1 -0
  50. package/dist/src/services/servers/throttledEmitter.d.ts +38 -0
  51. package/dist/src/services/streamPipeline.characterization.test.d.ts +1 -0
  52. package/dist/src/services/wire/decodeFrame.d.ts +21 -0
  53. package/dist/src/services/wire/decodeFrame.test.d.ts +1 -0
  54. package/dist/tests/bench/streamPipeline.bench.d.ts +1 -0
  55. package/dist/tests/fakes/fakeRawWebSocket.d.ts +2 -0
  56. package/dist/tests/fakes/fakeWebSocket.d.ts +4 -3
  57. package/dist/tests/fakes/makeGateway.d.ts +7 -0
  58. package/dist/tests/wire/journey.d.ts +47 -0
  59. package/dist/{useChatSessions-BXYvvd4S.js → useChatSessions-C6sYF4U6.js} +2 -2
  60. package/dist/{useChatSessions-BXYvvd4S.js.map → useChatSessions-C6sYF4U6.js.map} +1 -1
  61. package/package.json +2 -1
  62. package/dist/httpArtifactService-GdGsaFKS.js +0 -1979
  63. package/dist/httpArtifactService-GdGsaFKS.js.map +0 -1
  64. package/dist/httpSessionService-CUujaUo6.js.map +0 -1
  65. package/dist/serializer-DX-yGa_k.js.map +0 -1
  66. package/dist/src/interfaces/IHeartbeatPort.d.ts +0 -4
  67. /package/dist/src/components/AiChat/{sessionStateManagerService.idle.test.d.ts → ChatPane/groupParts.test.d.ts} +0 -0
  68. /package/dist/src/{services/interactionServiceGrouping.test.d.ts → components/AiChat/ChatPane/parts/connectionOutagePart.test.d.ts} +0 -0
@@ -4,39 +4,26 @@ import { SendMessageResponse } from '../../models/SendMessageResponse';
4
4
  import { IArtifactService } from '../../services/interfaces/artifactService';
5
5
  import { AgentGatewayService } from '../../services/servers/AgentGatewayService';
6
6
  import { ISessionService } from '../../services/servers/sessionService/ISessionService';
7
- export declare const WARNING_THRESHOLD = 0.75;
8
- export declare const BASE_MULTIPLIER = 1000;
9
- export declare const IDLE_TIMEOUT: number;
10
- export declare const DEFAULT_WAIT_TIME = 500;
11
- export declare const MAX_RETRY_WAIT = 20000;
12
7
  export interface SessionStateManagerOptions {
13
8
  onSessionEstablished?: (sessionId: string) => void;
14
9
  }
10
+ /**
11
+ * The SESSION side of going live: load the session record over REST, keep the store's session
12
+ * in step with the socket's session, and tell the gateway (and the host) which session it is on.
13
+ *
14
+ * It no longer owns the connection. Until 2026-10-07 this class also ran a 2 s heartbeat that
15
+ * redialled a dropped socket on its own backoff curve and closed idle sessions — the second of
16
+ * two reconnect loops (the transport had the other), and the seam between them is where every
17
+ * reconnect bug lived. The gateway's ConnectionSupervisor is now the one owner of dial, redial,
18
+ * idle close and every `connectionStatus` write; this class binds the record whenever the
19
+ * supervisor reports a connected session, so a session that only came up on the third retry
20
+ * still gets its history and its `onSessionEstablished`.
21
+ */
15
22
  export declare class SessionStateManagerService {
16
- private idleTime;
17
- internalHearBeat: ReturnType<typeof setInterval> | null;
18
- lastConCheck: number;
19
23
  sessionState: AiChatState;
20
24
  agentGatewayService: AgentGatewayService;
21
- paused: boolean;
22
- waitTimeForRetry: number;
23
25
  sessionService: ISessionService;
24
26
  artifactService: IArtifactService;
25
- workingSessionId?: string;
26
- /**
27
- * Set by the first {@link bindAndOpenLiveSession}. The retry loop used to
28
- * gate on `workingContext` being present — i.e. "has anyone armed this
29
- * manager yet?" — so removing that field (issue #59) needs the same latch
30
- * kept explicitly, or a heartbeat could dial a session no host ever asked for.
31
- */
32
- private armed;
33
- /**
34
- * Latch for the "about to idle out" warning: the beat runs every 2s, so an unlatched
35
- * warning would print ~35 times across the last quarter of the window. Reset whenever
36
- * activity brings the session back.
37
- */
38
- private idleWarningLogged;
39
- pendingClosePromise?: Promise<SendMessageResponse | null>;
40
27
  private onSessionEstablished?;
41
28
  constructor(agentGatewayService: AgentGatewayService, sessionService: ISessionService, artifactService: IArtifactService, sessionStore: AiChatStore, options?: SessionStateManagerOptions);
42
29
  /**
@@ -46,18 +33,20 @@ export declare class SessionStateManagerService {
46
33
  * different agent than the one the socket had been sending as.
47
34
  */
48
35
  private get agentContext();
49
- pause(): void;
50
- start(): void;
51
- beat(): void;
52
36
  /** Create a server-side session for the gateway's agent. The agent is NOT a parameter — see {@link agentContext}. */
53
37
  createSession(sessionId: string): Promise<ChatSession>;
54
38
  retrieveSession(sessionId: string): Promise<ChatSession | null>;
39
+ private cacheArtifacts;
55
40
  /**
56
- * Open the socket and bind a session FOR THE GATEWAY'S AGENT. There is
57
- * deliberately no context parameter (issue #59): a caller that could pass
58
- * one could open a conversation as an agent the gateway will never send as,
59
- * which is precisely how a page bound to `expense-agent` ended up talking to
60
- * `booking-flow-agent`.
41
+ * Load the session record and open the socket on it, FOR THE GATEWAY'S AGENT. There is
42
+ * deliberately no context parameter (issue #59): a caller that could pass one could open a
43
+ * conversation as an agent the gateway will never send as, which is precisely how a page
44
+ * bound to `expense-agent` ended up talking to `booking-flow-agent`.
45
+ *
46
+ * Resolves once the first dial succeeds and rejects when it fails; the supervisor keeps
47
+ * redialling in the background either way (see ConnectionSupervisor). The REST load runs as
48
+ * the dial's `prepare` step, so a server that is down for both is retried for both, on one
49
+ * curve, and the record is bound whenever the session finally comes up.
61
50
  *
62
51
  * @param options.resume keep the socket's replay cursor, so the server replays what was
63
52
  * emitted while we were away. Use it when redialling a session the client already holds
@@ -66,7 +55,19 @@ export declare class SessionStateManagerService {
66
55
  bindAndOpenLiveSession(sessionId?: string, options?: {
67
56
  resume?: boolean;
68
57
  }): Promise<void>;
69
- closeLiveConnection(stoneCold?: boolean, closeTurn?: boolean): Promise<void>;
58
+ /** The REST load of an existing session, shown as `loading` in the store while it runs. */
59
+ private loadSessionRecord;
60
+ /**
61
+ * Make the store's session the one the socket is on. A record already bound to this id is left
62
+ * alone; anything else (a fresh session, a record the REST load did not find) gets a
63
+ * placeholder the stream fills in.
64
+ */
65
+ bindSessionRecord(socketSessionId: string): void;
66
+ /**
67
+ * Hang up and stop supervising. `closeTurn` also closes an open turn in the store (the
68
+ * connection toggle in the composer passes false: pausing the socket is not ending the turn).
69
+ */
70
+ closeLiveConnection(closeTurn?: boolean): Promise<SendMessageResponse | null>;
71
+ /** Tear down: the host unmounted or the engine is being disposed. Never throws. */
70
72
  stop(): Promise<void>;
71
- processRetryLoop(_identification?: string): void;
72
73
  }
@@ -36,6 +36,17 @@ export interface SubAgentState {
36
36
  * stuck on "Continuar" between turns.
37
37
  */
38
38
  export type SuspendState = 'idle' | 'suspending' | 'suspended';
39
+ /** See `AiChatState.connectionOutage`. Times are epoch ms. */
40
+ export interface ConnectionOutage {
41
+ /** When the drop was noticed. */
42
+ since: number;
43
+ /** When the next redial fires; null once the supervisor halted. In the past while a dial is in flight. */
44
+ retryAt: number | null;
45
+ /** Consecutive failed attempts so far (1 while waiting for the first redial). */
46
+ attempt: number;
47
+ /** Set when the supervisor gave up: 'attached-elsewhere' | 'session-gone' | 'closed-by-server'. */
48
+ halted: string | null;
49
+ }
39
50
  export interface AiChatState {
40
51
  session: ChatSession | null;
41
52
  sendingMessage: boolean;
@@ -46,6 +57,12 @@ export interface AiChatState {
46
57
  skillLevel: SkillLevel;
47
58
  turnOpen: boolean;
48
59
  suspendState: SuspendState;
60
+ /**
61
+ * A working connection dropped and the supervisor is redialling (or gave up). Null while the
62
+ * socket is up. The live message draws it as a part while a turn is open — the stream is what
63
+ * the outage interrupts — and a host can draw its own affordance from it anywhere.
64
+ */
65
+ connectionOutage: ConnectionOutage | null;
49
66
  statistics?: InteractionStatistics;
50
67
  connectionStatus: ConnectionState;
51
68
  lastToolEvent?: ToolEventDetails;
@@ -66,6 +83,7 @@ export interface AiChatState {
66
83
  setNewMessage: (message: Interaction) => void;
67
84
  setTurnOpen: (status: boolean) => void;
68
85
  setSuspendState: (status: SuspendState) => void;
86
+ setConnectionOutage: (outage: ConnectionOutage | null) => void;
69
87
  setConnectionStatus: (status: ConnectionState) => void;
70
88
  setSubAgentMessage: (subAgentId: string, interaction: Interaction, name?: string) => void;
71
89
  completeSubAgent: (subAgentId: string) => void;
@@ -7,10 +7,12 @@ export { AiChatServiceContext, useAiChatServices, useAiChatSessionStore, } from
7
7
  export { useTurnOpen } from './AiChat/useTurnOpen';
8
8
  export type { AiChatContextState as AiChatServices } from './AiChat/AiChatContext';
9
9
  export type { AiChatProps, AiChatBaseProps, AiChatEngineProps, AiChatHandle, AiChatStyleProps, AiChatDrawerProps, AiChatFloatingProps, ConnectionInformation, AuthPromptContext, } from './AiChat/AiChatTypes';
10
- export type { AiChatState, AiChatStore, SubAgentState } from './AiChat/stateConfiguration';
10
+ export type { AiChatState, AiChatStore, SubAgentState, ConnectionOutage } from './AiChat/stateConfiguration';
11
11
  export { createAiChatStore } from './AiChat/stateConfiguration';
12
12
  export { createAiChatSessionStore } from './AiChat/AiChatSessionStore';
13
- export { SessionStateManagerService, IDLE_TIMEOUT, WARNING_THRESHOLD, } from './AiChat/sessionStateManagerService';
13
+ export { SessionStateManagerService } from './AiChat/sessionStateManagerService';
14
+ export { IDLE_TIMEOUT, WARNING_THRESHOLD, ConnectionSupervisor } from '../services/servers/connectionSupervisor';
15
+ export type { HaltReason } from '../services/servers/connectionSupervisor';
14
16
  export { createAiChatEngine } from './AiChat/aiChatEngine';
15
17
  export type { AiChatEngine, AiChatEngineConfig } from './AiChat/aiChatEngine';
16
18
  export { useAgentEngine, engineKeyFor, getSharedAiChatEngine, disposeSharedAiChatEngine, } from './AiChat/useAgentEngine';
@@ -43,3 +45,5 @@ export type { TurnAwarePhase } from './Library/turnAwareButtonState';
43
45
  export { LlmResponseRender, LiveJsxBlock, JsxErrorBoundary, EnvironmentProvider, InertEnvironmentProvider, useEnvironment, useEnvironmentOptional, LiveTsxConfigProvider, useLiveTsxMaxCharsForFull, LIVE_TSX_DEFAULT_MAX_CHARS_FOR_FULL, extendModuleRegistry, extendDefaultScope, getDefaultJsxScope, parseContentBlocks, } from './LlmResponseRender';
44
46
  export type { ContentBlock } from './LlmResponseRender';
45
47
  export * from './v2';
48
+ export { MessageScopeProvider, useMessageScope } from './AiChat/ChatPane/MessageScope';
49
+ export type { MessageScope } from './AiChat/ChatPane/MessageScope';
@@ -1,4 +1,3 @@
1
- export type { IHeartbeatPort } from './IHeartbeatPort';
2
1
  export type { INotificationPort } from './INotificationPort';
3
2
  export * from './memoryService';
4
3
  export * from './schedulingService';
@@ -1,15 +1,6 @@
1
1
  import { TodoList } from './todoListModel';
2
2
  import { Artifact } from './Artifact';
3
3
  import { InteractionPart } from './InteractionPart';
4
- export interface MergeResult {
5
- updatedInteraction: Interaction;
6
- updatedParts: InteractionPart[];
7
- newArtifacts: Partial<Artifact>[] | null;
8
- mainBranch: Interaction | null;
9
- analyticsBranch: Interaction | null;
10
- mainBranchPartsChanged: InteractionPart[] | null;
11
- analyticsBranchPartsChanged: InteractionPart[] | null;
12
- }
13
4
  export interface TurnOpenCloseDetails {
14
5
  stack: string[];
15
6
  turnClosed: boolean;
@@ -17,10 +17,11 @@ export interface InteractionPart {
17
17
  text?: string;
18
18
  hasTask?: boolean;
19
19
  rawDetails?: any;
20
- textLastChunk?: string;
21
- thoughtLastChunk?: string;
22
20
  partial: boolean;
23
- isStillWriting: boolean;
21
+ /** @deprecated Write-only; nothing reads it. Kept optional so hosts' fixtures still compile. Goes in 0.5. */
22
+ textLastChunk?: string;
23
+ /** @deprecated Write-only; nothing reads it. Kept optional so hosts' fixtures still compile. Goes in 0.5. */
24
+ isStillWriting?: boolean;
24
25
  mustPush: boolean;
25
26
  textAppendable: boolean;
26
27
  waitingDetails?: {
@@ -7,7 +7,13 @@ export type NotificationType = 'info' | 'warning' | 'error';
7
7
  * their own connection affordance suppress this one; see `AgentGatewayWSAsync`'s `everConnected`
8
8
  * gate for why it is not raised on the initial dial.
9
9
  */
10
- export type NotificationKind = 'connection-restarting';
10
+ export type NotificationKind = 'connection-restarting'
11
+ /** 4002 — another socket (another tab, usually) holds this session; the supervisor stopped redialling. */
12
+ | 'session-attached-elsewhere'
13
+ /** The server no longer has the session (4004, or it answered a dial with a different id); no redial. */
14
+ | 'session-gone'
15
+ /** The server closed on purpose (1000) or rejected the credentials (1008); no redial. */
16
+ | 'connection-closed';
11
17
  export interface BasicNotification {
12
18
  type: NotificationType;
13
19
  message: string;
@@ -97,6 +97,8 @@ export interface CodeExecutionResultDetails {
97
97
  output?: string;
98
98
  }
99
99
  export declare class ServerEvent {
100
+ /** The call id the SDK puts on its error sentinel (`Event.ServerErrorIdentification`). */
101
+ static readonly SERVER_ERROR_CALL_ID = "Server Error";
100
102
  uniqueId: string;
101
103
  mimeType: string;
102
104
  created: Date;
@@ -132,6 +134,8 @@ export declare class ServerEvent {
132
134
  static createErrorEvent(errorMessage: string, interactionId: string): ServerEvent;
133
135
  static parseFlatPropertiesTypedEvent(event: LlmEvent): ServerEvent;
134
136
  static getPartType(part: KernelContent | StreamingKernelContent): PartType;
137
+ /** True when the event holds the SDK's "Server Error" sentinel call (`Event.GetErrorEvent`). */
138
+ static carriesServerError(event: LlmEvent): boolean;
135
139
  static parseFromTypedEvent(event: LlmEvent): ServerEvent;
136
140
  static createFromThought(interactionId: string, thinkingText: string): ServerEvent;
137
141
  static createFromFunctionName(functionName: string, interactionId: string, callData?: any): ServerEvent;
@@ -1,4 +1,4 @@
1
- export type { Interaction, MergeResult, TurnOpenCloseDetails } from './Interaction';
1
+ export type { Interaction, TurnOpenCloseDetails } from './Interaction';
2
2
  export type { InteractionPart } from './InteractionPart';
3
3
  export { InteractionPartUtils } from './InteractionPart';
4
4
  export type { ChatSession } from './ChatSession';
@@ -1,35 +1,14 @@
1
1
  import { ServerEvent } from '../../models/ServerEvent';
2
2
  import { TypedJSON } from 'typedjson';
3
3
  import { InteractionStatistics, LlmEvent, StreamingResponse } from '../../models/semanticKernelModel/models';
4
- import { IWebSocketConnection, IMessage, IMessageBase } from './webSocketConnection';
5
- export declare const APPLICATION_CLOSED_CODE = 4001;
6
- /**
7
- * The server uses this WS close code when rejecting a duplicate attachment for the
8
- * same sessionId (single-attach policy in InteractionRunRegistry). The user already
9
- * has another WS connected for this session — usually another browser tab — so
10
- * silently auto-reconnecting would just bounce the rejection forever. Surface the
11
- * close to the consumer instead.
12
- */
13
- export declare const SESSION_ALREADY_ATTACHED_CODE = 4002;
14
- /**
15
- * Client-local close code used when the heartbeat declares the peer dead. It never
16
- * goes on the wire (there is nobody left to receive it); it reaches `onClose` so a
17
- * consumer can tell a detected dead peer from a server-initiated close. Retryable:
18
- * the inner loop resumes the session with its replay cursor when the channel was
19
- * proven, otherwise the outer state manager takes over as for any other drop.
20
- */
21
- export declare const HEARTBEAT_TIMEOUT_CODE = 4100;
4
+ import { ConnectOptions, IWebSocketConnection, IMessage, IMessageBase } from './webSocketConnection';
5
+ import { APPLICATION_CLOSED_CODE, HEARTBEAT_TIMEOUT_CODE, SESSION_ALREADY_ATTACHED_CODE } from './closeCodes';
6
+ export { APPLICATION_CLOSED_CODE, HEARTBEAT_TIMEOUT_CODE, SESSION_ALREADY_ATTACHED_CODE };
22
7
  export declare class WebSocketConnecionV2 implements IWebSocketConnection {
23
8
  ws: WebSocket | null;
24
- stats: InteractionStatistics;
25
- /**
26
- * Compaction history for the whole CONNECTION, and the previous size reading it
27
- * is derived from. Deliberately not inside `stats`: those are rebuilt on every
28
- * interaction (see emitFirstToken), and a session's compaction history outlives
29
- * any one turn — it is the thing the usage panel plots.
30
- */
31
- private readonly sessionCompactions;
32
- private previousSessionInformation?;
9
+ /** Frame counts, byte totals, the token-rate estimate and the compaction history — see StreamStatsTracker. */
10
+ private readonly statsTracker;
11
+ get stats(): InteractionStatistics;
33
12
  baseUrl: string;
34
13
  /**
35
14
  * Optional callback that returns the current JWT. We re-evaluate it on every connect/reconnect
@@ -43,12 +22,7 @@ export declare class WebSocketConnecionV2 implements IWebSocketConnection {
43
22
  onOpen?: () => void;
44
23
  onFirstToken?: (interactionId: string) => void;
45
24
  onSuspended?: () => void;
46
- onPong?: (sessionId: string) => void;
47
25
  onClose?: (code: number, reason: string) => void;
48
- /** Fired when an unexpected close triggers a reconnect attempt. */
49
- onReconnecting?: (attempt: number, delayMs: number) => void;
50
- /** Fired the first time the socket reopens after an unexpected close. */
51
- onReconnected?: (sessionId: string) => void;
52
26
  /**
53
27
  * Fired when the server signals that we lost streaming events on resume — our
54
28
  * `lastSeq` fell off the end of the in-memory replay buffer. Consumers should
@@ -56,38 +30,17 @@ export declare class WebSocketConnecionV2 implements IWebSocketConnection {
56
30
  */
57
31
  onRewindLost?: (sessionId: string, resumingFromSeq: number) => void;
58
32
  sessionId?: string;
59
- onNewPacket?: (stats: InteractionStatistics) => void;
60
- /**
61
- * Stats can fire dozens of times per second during streaming. We
62
- * coalesce to a fixed cadence so subscribers see steady,
63
- * digestible updates instead of a per-packet firehose — the
64
- * latter caused a "Maximum update depth exceeded" cascade in
65
- * heavy v2 surfaces (RunProgressPanelV2 + StreamStatistics +
66
- * ChatTranscript all subscribed to `statistics` and re-rendered
67
- * on every packet, with their useEffect-driven setStates pushing
68
- * React's nested-update counter past its threshold).
69
- */
70
- private statsFlushTimer;
71
- private statsLastFlushed;
72
- private readonly STATS_FLUSH_MS;
33
+ /** Coalesced stats updates (see StreamStatsTracker.STATS_FLUSH_MS). */
34
+ set onNewPacket(listener: ((stats: InteractionStatistics) => void) | undefined);
35
+ get onNewPacket(): ((stats: InteractionStatistics) => void) | undefined;
73
36
  monitorInterval: NodeJS.Timeout | null;
74
37
  streamingResponseSerializer: TypedJSON<StreamingResponse>;
75
- events: [number, number][];
76
38
  lastActivity: number;
77
39
  /** When the outstanding heartbeat Ping went out; null while no reply is pending. */
78
40
  private pingSentAt;
79
41
  firstTokenInteractions: Set<string>;
80
- /** Last sessionId we successfully had — used to resume on reconnect. */
42
+ /** Last sessionId we successfully had — stamps parked answers, labels log lines. */
81
43
  private lastKnownSessionId?;
82
- /** True when the consumer called `disconnect()` — suppresses auto-reconnect. */
83
- private intentionalDisconnect;
84
- /** Number of reconnect attempts since the last clean open. */
85
- private reconnectAttempts;
86
- private reconnectTimer;
87
- /** True while we are in the middle of an unexpected-close → reconnect cycle. */
88
- private isReconnecting;
89
- /** Internal flag set by `scheduleReconnect` so `connect()` does not reset the backoff state. */
90
- private _internalReconnect;
91
44
  /**
92
45
  * Highest server-assigned `seq` we have observed and processed. The next
93
46
  * reconnect appends `?lastSeq={lastSeq}` so the server can replay anything
@@ -104,51 +57,19 @@ export declare class WebSocketConnecionV2 implements IWebSocketConnection {
104
57
  * the single-attach policy makes it undeliverable from here anyway.
105
58
  */
106
59
  private pendingAnswers;
107
- /**
108
- * True once *any* socket on this instance has received at least one packet.
109
- * Used by `onclose` to distinguish a real mid-stream drop (we had a working
110
- * channel) from a connect attempt that never produced traffic (server down,
111
- * unreachable, etc.). The inner reconnect loop is only meant for the former
112
- * — fresh-connect failures should be handed straight to the outer
113
- * SessionStateManagerService.processRetryLoop instead of being retried
114
- * twice in here. Sticky for the lifetime of this connection instance so
115
- * that internal resume attempts keep their full inner-loop budget even
116
- * when a replacement socket fails before delivering its first message.
117
- * Cleared by `disconnect()`.
118
- */
119
- private hasEverReceivedPacket;
120
60
  constructor(baseUrl?: string, getToken?: () => string | undefined);
121
61
  /**
122
- * Connect to the WebSocket endpoint.
62
+ * Dial the endpoint once. Resolves with the session id the server's first Pong carries;
63
+ * rejects when the socket closes, or times out, before that. A close AFTER the Pong is
64
+ * reported through `onClose` only.
123
65
  *
124
66
  * `options.resume` keeps the replay cursor so the server can send back everything emitted
125
- * while we were away (`?lastSeq=N`). Until it existed, only the socket's OWN
126
- * `scheduleReconnect` could resume: every other caller landed in the "fresh connect" branch
127
- * below, which discards `lastSeq`. A host that redials deliberately — a mobile app coming
128
- * back to the foreground, say — therefore lost every frame emitted while it was suspended,
129
- * silently, because the transcript looked intact right up to the gap.
67
+ * while we were away (`?lastSeq=N`). Without it the dial is fresh and the cursor is dropped:
68
+ * a cursor from one conversation must never be presented to another.
130
69
  */
131
- connect(sessionId?: string, options?: {
132
- resume?: boolean;
133
- }): Promise<string>;
134
- /**
135
- * Returns true when the close code is something we believe a fresh connect
136
- * (with the same sessionId) can recover from. We deliberately do NOT retry
137
- * on:
138
- * - 1000 normal closure
139
- * - 1008 policy violation (auth rejected)
140
- * - 4001 our own intentional disconnect
141
- * - 4002 the session is attached elsewhere (another tab) — retrying just bounces
142
- * Retried, on purpose:
143
- * - 4003 the server's idle close ("reconnect on next interaction"): resuming is
144
- * cheap and lossless, and while the user is present the outer loop would redial
145
- * anyway; when they are gone the client's own idle timer closes first.
146
- * - 4100 HEARTBEAT_TIMEOUT_CODE, our own dead-peer verdict.
147
- */
148
- private shouldAttemptReconnect;
149
- private cancelPendingReconnect;
150
- private computeBackoffDelay;
151
- private scheduleReconnect;
70
+ connect(sessionId?: string, options?: ConnectOptions): Promise<string>;
71
+ /** Drop the current socket without reporting it: handlers off, then close. */
72
+ private detachSocket;
152
73
  sleep(ms: number): Promise<unknown>;
153
74
  /** The session this instance believes it is on — for log lines, never for logic. */
154
75
  private get sessionLabel();
@@ -192,7 +113,6 @@ export declare class WebSocketConnecionV2 implements IWebSocketConnection {
192
113
  */
193
114
  sendMessage(message: IMessage): void;
194
115
  sendBaseMessage(message: IMessageBase): void;
195
- sendSuspendMessage(message: IMessage): void;
196
116
  /**
197
117
  * Heartbeat: keep a quiet socket alive with a Ping every PING_INTERVAL_MS, and
198
118
  * declare it dead when a Ping goes PONG_TIMEOUT_MS without ANY inbound frame.
@@ -203,13 +123,20 @@ export declare class WebSocketConnecionV2 implements IWebSocketConnection {
203
123
  * Send a heartbeat ping and start the reply clock (unless one is already running).
204
124
  */
205
125
  ping(): void;
126
+ /**
127
+ * Behave as if the peer vanished: the socket is closed and reported as an abnormal close (1006),
128
+ * exactly the path the heartbeat's dead-peer verdict takes. For demos and tests of the resume —
129
+ * the supervisor redials with the replay cursor and the server replays what it buffered — on a
130
+ * server that is still running; a real drop needs a cable pulled.
131
+ */
132
+ simulateDrop(): void;
206
133
  /**
207
134
  * Declare the current socket dead and run the close path NOW, without waiting
208
135
  * for the browser: for a half-open peer `onclose` can lag by minutes or never
209
136
  * come, and the decision has already been made. The dead socket's own onclose
210
- * handler is invoked with a client-local code, so the reconnect-vs-handoff
211
- * logic that runs is exactly the one a server close would run. Handlers are
212
- * detached first so a late real close event cannot run it a second time.
137
+ * handler is invoked with a client-local code, so the consumer sees exactly
138
+ * what a server close would have produced. Handlers are detached first so a
139
+ * late real close event cannot run it a second time.
213
140
  */
214
141
  private failSocket;
215
142
  /**
@@ -220,12 +147,5 @@ export declare class WebSocketConnecionV2 implements IWebSocketConnection {
220
147
  * Check if connected
221
148
  */
222
149
  isConnected(): boolean;
223
- /**
224
- * Push the latest stats out to `onNewPacket`, but at most every
225
- * `STATS_FLUSH_MS` ms. Subsequent packets within the window
226
- * schedule a trailing flush so the UI eventually sees the final
227
- * value without each individual packet causing a re-render.
228
- */
229
- private flushStatsCoalesced;
230
150
  handleEvent(llmEvent: LlmEvent, rawData: string): Promise<void>;
231
151
  }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * WebSocket close codes with a meaning in this protocol. The 4xxx range is application-defined;
3
+ * the server (AIA-AgentsSdk, `SocketController` / `InteractionRunRegistry`) sends 4002 and 4003,
4
+ * the client sends 4001 and reports 4100 to itself. 4004 is reserved for the server's "session
5
+ * not found" verdict (not emitted yet — today an unknown session closes with 1001 after the
6
+ * upgrade); the client already treats it as final.
7
+ */
8
+ /** Our own intentional disconnect. Never retried, never reported as a drop. */
9
+ export declare const APPLICATION_CLOSED_CODE = 4001;
10
+ /**
11
+ * The server rejected a duplicate attachment for the same session (single-attach policy): the user
12
+ * already has another socket on it — usually another browser tab. Retrying just bounces, so the
13
+ * supervisor halts and the host tells the user.
14
+ */
15
+ export declare const SESSION_ALREADY_ATTACHED_CODE = 4002;
16
+ /** The server closed an idle session ("reconnect on next interaction"). Resuming is cheap and lossless. */
17
+ export declare const SERVER_IDLE_CLOSE_CODE = 4003;
18
+ /** The server no longer has this session. Final: a redial would only create a new conversation. */
19
+ export declare const SESSION_NOT_FOUND_CODE = 4004;
20
+ /**
21
+ * Client-local: the heartbeat declared the peer dead. Never goes on the wire (nobody is left to
22
+ * receive it); reaches `onClose` so the supervisor can tell a detected dead peer from a server close.
23
+ */
24
+ export declare const HEARTBEAT_TIMEOUT_CODE = 4100;
@@ -0,0 +1,41 @@
1
+ import { InteractionStatistics, SessionInformation } from '../../models/semanticKernelModel/models';
2
+ /**
3
+ * Per-connection stream statistics: frame counts, bytes, a tokens-per-second
4
+ * estimate over a sliding window, the session-size reading and the compactions
5
+ * inferred from it. Client-only — the server sends no stats payload.
6
+ *
7
+ * Two lifetimes live here on purpose. `stats` is rebuilt for every interaction
8
+ * (see {@link resetForInteraction}); the compaction history spans the whole
9
+ * connection, because it is the thing the usage panel plots across turns.
10
+ *
11
+ * Flushes to `onFlush` are coalesced to {@link STATS_FLUSH_MS}: stats can
12
+ * change dozens of times per second during streaming, and a per-packet
13
+ * firehose once drove heavy v2 surfaces (RunProgressPanelV2, StreamStatistics,
14
+ * ChatTranscript all subscribed) into React's nested-update limit.
15
+ */
16
+ export declare class StreamStatsTracker {
17
+ static readonly STATS_FLUSH_MS = 120;
18
+ stats: InteractionStatistics;
19
+ onFlush?: (stats: InteractionStatistics) => void;
20
+ private readonly sessionCompactions;
21
+ private previousSessionInformation?;
22
+ /** [timestamp, text length] per frame, for the sliding-window rate. */
23
+ private events;
24
+ private flushTimer;
25
+ private lastFlushed;
26
+ constructor();
27
+ private fresh;
28
+ /** A new interaction started streaming: counters restart, the compaction history does not. */
29
+ resetForInteraction(): void;
30
+ /**
31
+ * Account for one decoded frame. `sessionInformation` is only read off main-agent
32
+ * frames — a sub-agent's reading describes a different session.
33
+ */
34
+ record(opts: {
35
+ rawLength: number;
36
+ textLength: number;
37
+ sessionInformation?: SessionInformation;
38
+ fromSubAgent: boolean;
39
+ }): void;
40
+ private flushCoalesced;
41
+ }
@@ -47,6 +47,15 @@ export interface IMessage extends IMessageBase {
47
47
  Args?: string;
48
48
  };
49
49
  }
50
+ export interface ConnectOptions {
51
+ /** Keep the replay cursor (`?lastSeq=N`), so the server replays what was emitted while we were away. */
52
+ resume?: boolean;
53
+ /**
54
+ * The turn the client still has open, sent as `?openInteraction=` on a resume. An instance that finds nothing to
55
+ * resume (the one that ran the turn is gone) then tells the client the turn is lost instead of leaving it waiting.
56
+ */
57
+ openInteractionId?: string;
58
+ }
50
59
  export interface IWebSocketConnection {
51
60
  onEvent?: (event: MessageEvent | ServerEvent) => Promise<void>;
52
61
  onError?: (error: string) => void;
@@ -55,11 +64,6 @@ export interface IWebSocketConnection {
55
64
  onSuspended?: () => void;
56
65
  onClose?: (code: number, reason: string) => void;
57
66
  onNewPacket?: (stats: InteractionStatistics) => void;
58
- onPong?: (sessionId: string) => void;
59
- /** Emitted when an unexpected close kicks off the auto-reconnect loop. */
60
- onReconnecting?: (attempt: number, delayMs: number) => void;
61
- /** Emitted on the first successful re-open after one or more reconnect attempts. */
62
- onReconnected?: (sessionId: string) => void;
63
67
  /**
64
68
  * Emitted when the server signals that some events were lost on resume —
65
69
  * our `lastSeq` was older than its in-memory replay buffer. UI should
@@ -67,16 +71,15 @@ export interface IWebSocketConnection {
67
71
  */
68
72
  onRewindLost?: (sessionId: string, resumingFromSeq: number) => void;
69
73
  /**
70
- * Open the socket. `options.resume` keeps the replay cursor so the server replays what was
71
- * emitted while we were gone (`?lastSeq=N`); without it a connect is treated as fresh and
72
- * the cursor is discarded.
74
+ * Dial the socket ONCE. Resolves with the session id the server answered with, rejects when
75
+ * the socket died first; a later close is reported through `onClose` with its code and the
76
+ * transport does not redial on its own (the gateway's ConnectionSupervisor does).
77
+ * `options.resume` keeps the replay cursor so the server replays what was emitted while we
78
+ * were gone (`?lastSeq=N`); without it a connect is fresh and the cursor is discarded.
73
79
  */
74
- connect: (sessionId?: string, options?: {
75
- resume?: boolean;
76
- }) => Promise<string>;
80
+ connect: (sessionId?: string, options?: ConnectOptions) => Promise<string>;
77
81
  sendMessage: (message: IMessage) => void;
78
82
  suspendStream: () => void;
79
- disconnect: () => void;
80
83
  closeStream: () => void;
81
84
  isConnected: () => boolean;
82
85
  /**