@aintela/chat 0.6.0 → 0.7.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 (57) hide show
  1. package/README.md +43 -0
  2. package/dist/components.js +7528 -7182
  3. package/dist/components.js.map +1 -1
  4. package/dist/{httpArtifactService-DYQDPVVH.js → detachedRunActivity-CjyFTKSw.js} +769 -324
  5. package/dist/detachedRunActivity-CjyFTKSw.js.map +1 -0
  6. package/dist/detachedRunModel-X59Pb5V-.js +67 -0
  7. package/dist/{detachedRunModel-1ii9qGTW.js.map → detachedRunModel-X59Pb5V-.js.map} +1 -1
  8. package/dist/hooks.js +1 -1
  9. package/dist/httpSessionService-Ckb9Cxia.js +320 -0
  10. package/dist/httpSessionService-Ckb9Cxia.js.map +1 -0
  11. package/dist/index.js +296 -274
  12. package/dist/models.js +47 -41
  13. package/dist/{serializer-BNsp8xs2.js → serializer-DNUH6kgE.js} +567 -507
  14. package/dist/serializer-DNUH6kgE.js.map +1 -0
  15. package/dist/services.js +22 -15
  16. package/dist/src/components/AiChat/AiChatContext.d.ts +3 -1
  17. package/dist/src/components/AiChat/AiChatTypes.d.ts +7 -1
  18. package/dist/src/components/AiChat/ChatPane/InteractionOriginBadge.d.ts +15 -0
  19. package/dist/src/components/AiChat/ChatPane/messageUserOrigin.test.d.ts +1 -0
  20. package/dist/src/components/AiChat/aiChatEngine.d.ts +13 -1
  21. package/dist/src/components/index.d.ts +2 -0
  22. package/dist/src/components/v2/DetachedRunTaskBox.d.ts +30 -5
  23. package/dist/src/components/v2/DetachedRunTaskBox.live.test.d.ts +1 -0
  24. package/dist/src/components/v2/DetachedRunTranscript.d.ts +89 -0
  25. package/dist/src/components/v2/DetachedRunTranscript.test.d.ts +1 -0
  26. package/dist/src/components/v2/index.d.ts +5 -0
  27. package/dist/src/components/v2/useDetachedRunLiveActivity.d.ts +30 -0
  28. package/dist/src/components/v2/useDetachedRunResumeKey.d.ts +15 -0
  29. package/dist/src/components/v2/useDetachedRunResumeKey.test.d.ts +1 -0
  30. package/dist/src/models/Interaction.d.ts +15 -0
  31. package/dist/src/models/detachedRunModel.d.ts +11 -0
  32. package/dist/src/models/enums.d.ts +3 -1
  33. package/dist/src/models/index.d.ts +4 -3
  34. package/dist/src/models/semanticKernelModel/models.d.ts +22 -1
  35. package/dist/src/services/WebSocketConnection/WebSocketConnectionV2.d.ts +2 -1
  36. package/dist/src/services/WebSocketConnection/webSocketConnection.d.ts +15 -2
  37. package/dist/src/services/detachedRun/DetachedRunFramesTransport.d.ts +68 -0
  38. package/dist/src/services/detachedRun/DetachedRunFramesTransport.test.d.ts +1 -0
  39. package/dist/src/services/detachedRun/detachedRunActivity.d.ts +25 -0
  40. package/dist/src/services/detachedRun/streamDetachedRunFrames.d.ts +110 -0
  41. package/dist/src/services/detachedRun/streamDetachedRunFrames.test.d.ts +1 -0
  42. package/dist/src/services/index.d.ts +7 -0
  43. package/dist/src/services/servers/AgentGatewayService.d.ts +1 -1
  44. package/dist/src/services/servers/AgentGatewayWSAsync.d.ts +67 -1
  45. package/dist/src/services/servers/gatewayAnnounceDetachedRun.test.d.ts +1 -0
  46. package/dist/src/services/servers/gatewayInteractionStarted.test.d.ts +1 -0
  47. package/dist/src/services/wire/decodeFrame.d.ts +6 -1
  48. package/dist/tests/fakes/fakeWebSocket.d.ts +8 -2
  49. package/dist/tests/fakes/makeGateway.d.ts +3 -1
  50. package/dist/{useChatSessions-Q41Jmr6P.js → useChatSessions-aTjNcj8q.js} +2 -2
  51. package/dist/{useChatSessions-Q41Jmr6P.js.map → useChatSessions-aTjNcj8q.js.map} +1 -1
  52. package/package.json +1 -1
  53. package/dist/detachedRunModel-1ii9qGTW.js +0 -50
  54. package/dist/httpArtifactService-DYQDPVVH.js.map +0 -1
  55. package/dist/httpSessionService-BY7JeW8d.js +0 -309
  56. package/dist/httpSessionService-BY7JeW8d.js.map +0 -1
  57. package/dist/serializer-BNsp8xs2.js.map +0 -1
@@ -0,0 +1,89 @@
1
+ import { default as React } from 'react';
2
+ import { AiChatBaseProps } from '../AiChat/AiChatTypes';
3
+ import { AiChatEngine } from '../AiChat/aiChatEngine';
4
+ import { User } from '../../models/contexts';
5
+ import { INotificationPort } from '../../interfaces/INotificationPort';
6
+ import { DetachedRunFramesTransport } from '../../services/detachedRun/DetachedRunFramesTransport';
7
+ import { DetachedRunFetch, DetachedRunFollowError, DetachedRunFramesRetry } from '../../services/detachedRun/streamDetachedRunFrames';
8
+ /** Where a run's frames come from, and with whose credentials. */
9
+ export interface DetachedRunTranscriptSource {
10
+ /** The run — what `start_task` returned. */
11
+ runId: string;
12
+ /** The agents server the run lives on (the chat's `serverBaseUrl`). */
13
+ baseUrl: string;
14
+ /** The HTTP layer for the frames stream — a host's authenticated `fetch` wrapper. Default: the global `fetch`. */
15
+ fetchImpl?: DetachedRunFetch;
16
+ /** The bearer for the frames stream, read on every (re)connect. Default: the user's `access_token`. */
17
+ getToken?: () => string | undefined | null | Promise<string | undefined | null>;
18
+ /**
19
+ * Called on a 401 from the frames stream: refresh the credentials and resolve true to retry once with a fresh
20
+ * token. Without it a 401 is retried only when `getToken` already returns a different token.
21
+ */
22
+ onUnauthorized?: () => Promise<boolean>;
23
+ /** The signed-in user — whose token reads the run's artifacts. Prefer `getUser` (read live). */
24
+ user?: User;
25
+ getUser?: () => User | undefined;
26
+ notificationPort?: INotificationPort;
27
+ retry?: DetachedRunFramesRetry;
28
+ }
29
+ export interface DetachedRunTranscriptEngine {
30
+ /** An ordinary chat engine over the run's frames — adopt it with `<AiChat engine={…}>` like any other. */
31
+ engine: AiChatEngine;
32
+ transport: DetachedRunFramesTransport;
33
+ }
34
+ /**
35
+ * A chat engine that draws one detached run as a read-only transcript (AIA Issue 1548, phase 5): the ordinary engine,
36
+ * gateway and store, over a {@link DetachedRunFramesTransport} instead of a socket, with
37
+ * `transcriptOfDetachedRun` so the run's frames are the conversation. Creating it touches no network; call
38
+ * {@link openDetachedRunTranscript} to follow the run, `engine.dispose()` to stop.
39
+ */
40
+ export declare function createDetachedRunTranscriptEngine(source: DetachedRunTranscriptSource): DetachedRunTranscriptEngine;
41
+ /**
42
+ * Start following the run. The session record is bound first, under the run id, so the connect that follows finds it
43
+ * in place rather than replacing the store's session while the first frames land.
44
+ */
45
+ export declare function openDetachedRunTranscript({ engine }: DetachedRunTranscriptEngine, runId: string): Promise<string>;
46
+ export interface UseDetachedRunTranscriptOptions extends DetachedRunTranscriptSource {
47
+ /**
48
+ * Change it to follow the run again from where the transcript is — after the host answered the run. The frames
49
+ * stream ends when the run stops (settled, or waiting for an answer) and does not reopen by itself.
50
+ */
51
+ resumeKey?: unknown;
52
+ /** The run's stream ended: it settled, or stopped to ask. */
53
+ onStreamEnd?: (lastSeq: number) => void;
54
+ /**
55
+ * Following stopped for good, and why — so the page can say it: `notFound` (404), `forbidden` (403),
56
+ * `unauthorized` (401 after the refresh chance), `gaveUp` (anything else, or retries ran out).
57
+ */
58
+ onError?: (error: DetachedRunFollowError) => void;
59
+ }
60
+ /**
61
+ * The engine of {@link createDetachedRunTranscriptEngine}, owned by the calling component: one per run, following
62
+ * from mount, stopped on unmount. For a host that mounts its own `<AiChat engine={…}>` wrapper (with its UI tools and
63
+ * renderers) around a `<ChatPane />`; {@link DetachedRunTranscript} is that wrapper, ready-made.
64
+ */
65
+ export declare function useDetachedRunTranscript(options: UseDetachedRunTranscriptOptions): DetachedRunTranscriptEngine;
66
+ /**
67
+ * The chat presentation props a transcript passes through to `<AiChat>` — everything the component does not set
68
+ * itself. Omitted: the engine's own inputs (it builds the engine), the session/connection inputs (it follows the run),
69
+ * the prompt (there is none), `children` / `bottomSlot` (use `footer`) and `onError` (the transcript's own, below).
70
+ */
71
+ export type DetachedRunTranscriptPresentationProps = Omit<AiChatBaseProps, 'serverBaseUrl' | 'user' | 'getUser' | 'sessionService' | 'sessionId' | 'autoCreateSession' | 'hidePromptInput' | 'onGetWebSocketProvider' | 'children' | 'bottomSlot' | 'notificationPort' | 'artifactService' | 'storageService' | 'eventBusService' | 'onError' | 'onSessionCreated' | 'onSessionEstablished' | 'onGatewayReady'>;
72
+ export interface DetachedRunTranscriptProps extends UseDetachedRunTranscriptOptions, DetachedRunTranscriptPresentationProps {
73
+ /** Drawn under the transcript, inside the chat's providers — where a host puts its answer composer. */
74
+ footer?: React.ReactNode;
75
+ /** Not accepted: the transcript builds its own engine over the run's frames. */
76
+ engine?: never;
77
+ /** Not accepted: a transcript speaks as nobody. */
78
+ agentContext?: never;
79
+ }
80
+ /**
81
+ * A detached run as a read-only chat transcript (AIA Issue 1548, phase 5): its briefing and follow-ups as the user's
82
+ * bubbles, the agent's reasoning, tool calls and answer streaming exactly as the chat draws them — it IS the chat,
83
+ * over the run's frames stream instead of a socket, with no prompt. Presentation props (`uiTools`, `partRenderers`,
84
+ * `showPersona`, `verbosity`, …) pass through to `<AiChat>`; `footer` is the host's place for an answer composer.
85
+ *
86
+ * <p>Give it a definite height, like `ChatPane`: the transcript scrolls inside it.</p>
87
+ */
88
+ export declare function DetachedRunTranscript(props: DetachedRunTranscriptProps): import("react/jsx-runtime").JSX.Element;
89
+ export default DetachedRunTranscript;
@@ -41,6 +41,11 @@ export type { TaskListV2Props as TaskListProps, TaskListV2Props } from './TaskLi
41
41
  export { DetachedRunBoxV2 as DetachedRunBox, DetachedRunBoxV2 } from './DetachedRunBoxV2';
42
42
  export { DetachedRunTaskBox, parseDetachedRunConclusion, detachedRunHeadline } from './DetachedRunTaskBox';
43
43
  export type { DetachedRunTaskBoxProps, DetachedRunConclusion } from './DetachedRunTaskBox';
44
+ export { useDetachedRunLiveActivity, canStreamDetachedRun } from './useDetachedRunLiveActivity';
45
+ export type { DetachedRunStreamAuth, DetachedRunLiveActivity } from './useDetachedRunLiveActivity';
46
+ export { DetachedRunTranscript, useDetachedRunTranscript, createDetachedRunTranscriptEngine, openDetachedRunTranscript, } from './DetachedRunTranscript';
47
+ export type { DetachedRunTranscriptProps, DetachedRunTranscriptSource, DetachedRunTranscriptEngine, DetachedRunTranscriptPresentationProps, UseDetachedRunTranscriptOptions, } from './DetachedRunTranscript';
48
+ export { useDetachedRunResumeKey } from './useDetachedRunResumeKey';
44
49
  export type { DetachedRunBoxV2Props as DetachedRunBoxProps, DetachedRunBoxV2Props, DetachedRunBoxV2Level as DetachedRunBoxLevel, DetachedRunBoxV2Level } from './DetachedRunBoxV2';
45
50
  export { AgentActivityV2 as AgentActivity, AgentActivityV2 } from './AgentActivityV2';
46
51
  export type { AgentActivityV2Props as AgentActivityProps, AgentActivityV2Props } from './AgentActivityV2';
@@ -0,0 +1,30 @@
1
+ import { TodoList } from '../../models/todoListModel';
2
+ import { DetachedRunFetch } from '../../services/detachedRun/streamDetachedRunFrames';
3
+ /** How a box reaches a run's frames — the same credentials the transcript takes. */
4
+ export interface DetachedRunStreamAuth {
5
+ /** The agents server the run lives on. Without it (and `fetchImpl` or `getToken`) nothing is streamed. */
6
+ baseUrl?: string;
7
+ fetchImpl?: DetachedRunFetch;
8
+ getToken?: () => string | undefined | null | Promise<string | undefined | null>;
9
+ onUnauthorized?: () => Promise<boolean>;
10
+ }
11
+ export interface DetachedRunLiveActivity {
12
+ /** One quiet line: the latest tool call in friendly words, or the tail of what the agent is writing. */
13
+ activity: string | null;
14
+ /** The task list as the latest `todolistUpdated` frame left it, and when that frame arrived (epoch ms). */
15
+ todo: {
16
+ todoList: TodoList;
17
+ at: number;
18
+ } | null;
19
+ /** A stream is open right now. */
20
+ streaming: boolean;
21
+ }
22
+ /** Whether the box has what it needs to stream: a base URL and some way to authenticate. */
23
+ export declare function canStreamDetachedRun(auth: DetachedRunStreamAuth): boolean;
24
+ /**
25
+ * Follow a run's frames while it is `active` (AIA Issue 1548 §3b): the latest activity for a one-line ticker and the
26
+ * task list the moment it changes. Closes when `active` turns false, when the server ends the stream, and on unmount;
27
+ * opens again when the run becomes active again after having stopped (it was resumed). The cursor survives a reopen,
28
+ * so a resumed run is not replayed from the start.
29
+ */
30
+ export declare function useDetachedRunLiveActivity(runId: string, active: boolean, auth: DetachedRunStreamAuth): DetachedRunLiveActivity;
@@ -0,0 +1,15 @@
1
+ import { DetachedRunView } from '../../models/detachedRunModel';
2
+ /**
3
+ * The `resumeKey` for a {@link DetachedRunTranscript} that follows a run you also READ (AIA Issue 1548): it changes
4
+ * whenever the record leaves a wait — resumed, settled, or waiting on a NEWER question.
5
+ *
6
+ * <p>The frames stream ends when the run stops to ask, and the answer can come from any channel — a page's composer,
7
+ * the conversation's task box, WhatsApp. Keyed on a host's own send, a transcript answered elsewhere stayed frozen on
8
+ * the first question while the record already said the run had moved on (seen 2026-10-12: a WhatsApp answer, a second
9
+ * question, then a failure, and the details still drawing the first question). The record is the one thing every
10
+ * channel moves, so it is the cue.</p>
11
+ *
12
+ * <p>A host that answers optimistically (sets the record out of the wait before the next read) gets its re-follow
13
+ * from the same change — it needs no key of its own.</p>
14
+ */
15
+ export declare function useDetachedRunResumeKey(run: Pick<DetachedRunView, 'status' | 'updatedAt'> | null | undefined): number;
@@ -1,6 +1,14 @@
1
1
  import { TodoList } from './todoListModel';
2
2
  import { Artifact } from './Artifact';
3
3
  import { InteractionPart } from './InteractionPart';
4
+ /**
5
+ * Where a turn came from (AIA Issue 1548), as the SDK's `InteractionOrigins` name it: `user` — a person typing in a
6
+ * client; `whatsapp` — a WhatsApp message relayed by the WhatsApp host; `platform` — the platform itself (a wake turn
7
+ * after a task settled, a detached run's briefing); `api` — any other `POST /run` caller.
8
+ */
9
+ export type InteractionOrigin = 'user' | 'whatsapp' | 'platform' | 'api';
10
+ /** The wire's origin string as an {@link InteractionOrigin}, case-insensitively; undefined for anything unknown. */
11
+ export declare function toInteractionOrigin(value: string | null | undefined): InteractionOrigin | undefined;
4
12
  export interface TurnOpenCloseDetails {
5
13
  stack: string[];
6
14
  turnClosed: boolean;
@@ -16,6 +24,13 @@ export interface Interaction {
16
24
  turn_complete?: boolean;
17
25
  isFinalResponse?: boolean;
18
26
  interactionQuestion?: string;
27
+ /** Where the turn came from; absent means a person typing (`user`). See {@link InteractionOrigin}. */
28
+ origin?: InteractionOrigin;
29
+ /**
30
+ * True for a turn this client did not send — the server announced it (`InteractionStarted`), or its frames
31
+ * arrived without one. The live view draws such a turn's question itself, since no composer here holds it.
32
+ */
33
+ remote?: boolean;
19
34
  asyncFinalResponse?: boolean;
20
35
  version: number;
21
36
  parts: InteractionPart[];
@@ -37,7 +37,18 @@ export interface DetachedRunView {
37
37
  created?: string | null;
38
38
  updatedAt?: string | null;
39
39
  settledAt?: string | null;
40
+ /**
41
+ * True once the conversation that started the run was told about its latest settle (the SDK's
42
+ * `AnnouncedAt >= SettledAt`, AIA Issue 1548 §5). False on a settled run nobody announced yet — the cue for the
43
+ * client to ask for the announcement. Absent on records from an SDK that predates it.
44
+ */
45
+ announced?: boolean;
40
46
  }
47
+ /** The statuses a run SETTLES on — it stopped, for good or to ask — and that the conversation is told about. */
48
+ export declare const DETACHED_RUN_SETTLED_STATUSES: ReadonlyArray<DetachedRunStatus>;
49
+ export declare function isDetachedRunSettledStatus(status: string | undefined | null): boolean;
50
+ /** True while the run executes (or is about to): the statuses a live view follows. */
51
+ export declare function isDetachedRunActiveStatus(status: string | undefined | null): boolean;
41
52
  /**
42
53
  * Status values after which the detached run will never change again. `WaitingForInput` is deliberately absent:
43
54
  * the run has stopped, but the task resumes when its question is answered.
@@ -11,7 +11,7 @@ export declare const RunMode: {
11
11
  readonly Interactive: "interactive";
12
12
  readonly Autonomous: "autonomous";
13
13
  };
14
- export type ChatAction = 'SendMessage' | 'Suspend' | 'Ping' | 'Close' | 'Other' | 'AnswerHumanTool';
14
+ export type ChatAction = 'SendMessage' | 'Suspend' | 'Ping' | 'Close' | 'Other' | 'AnswerHumanTool' | 'AnnounceDetachedRun';
15
15
  export declare const ChatAction: {
16
16
  readonly SendMessage: "SendMessage";
17
17
  readonly Other: "Other";
@@ -19,6 +19,8 @@ export declare const ChatAction: {
19
19
  readonly Close: "Close";
20
20
  readonly Ping: "Ping";
21
21
  readonly AnswerHumanTool: "AnswerHumanTool";
22
+ /** Ask the server for the announcement turn of this conversation's settled detached runs (AIA Issue 1548 §5). */
23
+ readonly AnnounceDetachedRun: "AnnounceDetachedRun";
22
24
  };
23
25
  export type EventType = 'partial_function_call' | 'tool_event' | 'function_call' | 'not_defined' | 'function_response' | 'function_client_output' | 'user_answer' | 'video' | 'thought' | 'thought_highlight' | 'inline_data' | 'file_data' | 'code_execution_result' | 'executable_code' | 'text' | 'other' | 'waiting' | 'suspended' | 'server_error';
24
26
  export declare const EventType: {
@@ -1,4 +1,5 @@
1
- export type { Interaction, TurnOpenCloseDetails } from './Interaction';
1
+ export type { Interaction, TurnOpenCloseDetails, InteractionOrigin } from './Interaction';
2
+ export { toInteractionOrigin } from './Interaction';
2
3
  export type { InteractionPart } from './InteractionPart';
3
4
  export { InteractionPartUtils } from './InteractionPart';
4
5
  export type { ChatSession } from './ChatSession';
@@ -19,7 +20,7 @@ export type { Artifact } from './Artifact';
19
20
  export type { ArtifactData } from './ArtifactData';
20
21
  export type { TodoList, TodoItem, TodoItemStatus } from './todoListModel';
21
22
  export type { DetachedRunView, DetachedRunStatus, DetachedRunStopReason } from './detachedRunModel';
22
- export { isDetachedRunTerminalStatus, isDetachedRunWaitingForInput, DETACHED_RUN_TERMINAL_STATUSES } from './detachedRunModel';
23
+ export { isDetachedRunTerminalStatus, isDetachedRunWaitingForInput, DETACHED_RUN_TERMINAL_STATUSES, DETACHED_RUN_SETTLED_STATUSES, isDetachedRunSettledStatus, isDetachedRunActiveStatus } from './detachedRunModel';
23
24
  export type { SendMessageResponse, StartStreamResponse, ServerSendMessageResponse } from './SendMessageResponse';
24
25
  export type { Prompt as PromptModel } from './Prompt';
25
26
  export { PromptUtils } from './Prompt';
@@ -32,4 +33,4 @@ export type { SemanticMemory, SemanticMemoryInput, SemanticMemorySearchOptions }
32
33
  export type { FunctionDetails, ThoughtDetails, TextDetails, ErrorDetails, ToolEventDetails, ExecutableCodeDetails, CodeExecutionResultDetails, } from './ServerEvent';
33
34
  export { ServerEvent } from './ServerEvent';
34
35
  export { deserializeEvent, deserializePayload, serializeEvent, createEventSerializer, createStreamingResponseSerializer, sanitizeJsonString, } from './semanticKernelModel/serializer';
35
- export { LlmEvent, StreamingResponse, TextContent, FunctionCallContent, FunctionResultContent, ChatMessageContent, StreamingTextContent, StreamingReasoningContent, StreamingFunctionCallUpdateContent, } from './semanticKernelModel/models';
36
+ export { LlmEvent, StreamingResponse, TextContent, FunctionCallContent, FunctionResultContent, ChatMessageContent, StreamingTextContent, StreamingReasoningContent, StreamingFunctionCallUpdateContent, InteractionStart, InteractionOriginContent, } from './semanticKernelModel/models';
@@ -1,5 +1,5 @@
1
1
  import { Artifact } from '../../models/Artifact';
2
- export type PartType = 'ToolEventContent' | 'StreamingToolEventContent' | 'TextContent' | 'StreamingFinalFunctionCallContent' | 'StreamingFinalFunctionResultContent' | 'StreamingClientOutputContent' | 'StreamingReasoningContent' | 'StreamingThoughtHighlightContent' | 'ImageContent' | 'FunctionCallContent' | 'FunctionResultContent' | 'FunctionClientOutputContent' | 'UserUiContent' | 'ChatMessageContent' | 'StreamingTextContent' | 'StreamingFunctionCallUpdateContent' | 'Unknown';
2
+ export type PartType = 'ToolEventContent' | 'StreamingToolEventContent' | 'TextContent' | 'StreamingFinalFunctionCallContent' | 'StreamingFinalFunctionResultContent' | 'StreamingClientOutputContent' | 'StreamingReasoningContent' | 'StreamingThoughtHighlightContent' | 'ImageContent' | 'FunctionCallContent' | 'FunctionResultContent' | 'FunctionClientOutputContent' | 'UserUiContent' | 'InteractionOriginContent' | 'ChatMessageContent' | 'StreamingTextContent' | 'StreamingFunctionCallUpdateContent' | 'Unknown';
3
3
  export declare const PartType: {
4
4
  readonly TextContent: "TextContent";
5
5
  readonly ToolEventContent: "ToolEventContent";
@@ -11,6 +11,7 @@ export declare const PartType: {
11
11
  readonly FunctionResultContent: "FunctionResultContent";
12
12
  readonly FunctionClientOutputContent: "FunctionClientOutputContent";
13
13
  readonly UserUiContent: "UserUiContent";
14
+ readonly InteractionOriginContent: "InteractionOriginContent";
14
15
  readonly ChatMessageContent: "ChatMessageContent";
15
16
  readonly StreamingTextContent: "StreamingTextContent";
16
17
  readonly StreamingFunctionCallUpdateContent: "StreamingFunctionCallUpdateContent";
@@ -119,6 +120,9 @@ export declare class UserUiContent extends KernelContent {
119
120
  name?: string;
120
121
  args?: string;
121
122
  }
123
+ export declare class InteractionOriginContent extends KernelContent {
124
+ origin?: string;
125
+ }
122
126
  export declare class ChatMessageContent extends KernelContent {
123
127
  role?: AuthorRole;
124
128
  items?: KernelContent[];
@@ -196,6 +200,21 @@ export declare class PartialLlmEvent {
196
200
  partialEventType?: EventTypeInformation;
197
201
  detachedRunId?: string;
198
202
  }
203
+ /**
204
+ * The payload of an `InteractionStarted` frame (AIA Issue 1548): a turn announcing itself before its first delta, so a
205
+ * client that did not send it — a WhatsApp message, a platform wake turn, a detached run's briefing — can open it with
206
+ * the text that started it. Server-side `InteractionStart`, camelCase, nulls omitted.
207
+ */
208
+ export declare class InteractionStart {
209
+ interactionId?: string;
210
+ /** The text that started the turn — what the client draws as the user's bubble. */
211
+ content?: string;
212
+ /** `user` | `whatsapp` | `platform` | `api` (the SDK's `InteractionOrigins`). */
213
+ origin?: string;
214
+ agentId?: string;
215
+ /** Set when the turn belongs to a detached run (it executes on the run's own session). */
216
+ detachedRunId?: string;
217
+ }
199
218
  export declare class StreamingResponse {
200
219
  type: string;
201
220
  event?: LlmEvent;
@@ -208,6 +227,8 @@ export declare class StreamingResponse {
208
227
  */
209
228
  accessToken?: string;
210
229
  partialEvent?: PartialLlmEvent;
230
+ /** Only on `type: "InteractionStarted"`: the turn that is about to stream. */
231
+ interaction?: InteractionStart;
211
232
  detachedRunId?: string;
212
233
  detachedRunName?: string;
213
234
  /**
@@ -1,6 +1,6 @@
1
1
  import { ServerEvent } from '../../models/ServerEvent';
2
2
  import { TypedJSON } from 'typedjson';
3
- import { InteractionStatistics, LlmEvent, StreamingResponse } from '../../models/semanticKernelModel/models';
3
+ import { InteractionStart, InteractionStatistics, LlmEvent, StreamingResponse } from '../../models/semanticKernelModel/models';
4
4
  import { ConnectOptions, IWebSocketConnection, IMessage, IMessageBase } from './webSocketConnection';
5
5
  import { APPLICATION_CLOSED_CODE, HEARTBEAT_TIMEOUT_CODE, SESSION_ALREADY_ATTACHED_CODE } from './closeCodes';
6
6
  export { APPLICATION_CLOSED_CODE, HEARTBEAT_TIMEOUT_CODE, SESSION_ALREADY_ATTACHED_CODE };
@@ -29,6 +29,7 @@ export declare class WebSocketConnecionV2 implements IWebSocketConnection {
29
29
  * reset partial-streaming UI for this session and rely on persisted history.
30
30
  */
31
31
  onRewindLost?: (sessionId: string, resumingFromSeq: number) => void;
32
+ onInteractionStarted?: (start: InteractionStart) => void;
32
33
  sessionId?: string;
33
34
  /** Coalesced stats updates (see StreamStatsTracker.STATS_FLUSH_MS). */
34
35
  set onNewPacket(listener: ((stats: InteractionStatistics) => void) | undefined);
@@ -1,6 +1,6 @@
1
1
  import { ServerEvent } from '../../models/ServerEvent';
2
2
  import { ChatAction } from '../../models/enums';
3
- import { InteractionStatistics } from '../../models/semanticKernelModel/models';
3
+ import { InteractionStart, InteractionStatistics } from '../../models/semanticKernelModel/models';
4
4
  export interface IMessageBase {
5
5
  Action: ChatAction;
6
6
  ModelId?: string;
@@ -9,6 +9,9 @@ export interface IMessageBase {
9
9
  /** ask_user answer routing (Action === 'AnswerHumanTool'): the parked tool-call id and the user's answer. */
10
10
  ToolCallId?: string;
11
11
  Answer?: string;
12
+ /** Action === 'AnnounceDetachedRun': the conversation the announcement turn runs on, and the run it is about. */
13
+ SessionId?: string;
14
+ DetachedRunId?: string;
12
15
  }
13
16
  export interface IMessageImage {
14
17
  MimeType: string;
@@ -17,7 +20,6 @@ export interface IMessageImage {
17
20
  }
18
21
  export interface IMessage extends IMessageBase {
19
22
  Content: string;
20
- SessionId?: string;
21
23
  Parameters?: {
22
24
  [key: string]: string;
23
25
  };
@@ -70,6 +72,12 @@ export interface IWebSocketConnection {
70
72
  * reset partial-streaming state for the affected session.
71
73
  */
72
74
  onRewindLost?: (sessionId: string, resumingFromSeq: number) => void;
75
+ /**
76
+ * An `InteractionStarted` frame (AIA Issue 1548): a turn announced itself before its first delta. Called in frame
77
+ * order with `onEvent`, so the announcement lands before the turn's first event. The envelope's `detachedRunId` is
78
+ * copied onto the payload when the payload has none. Optional: a transport that never sees one need not set it.
79
+ */
80
+ onInteractionStarted?: (start: InteractionStart) => void;
73
81
  /**
74
82
  * Dial the socket ONCE. Resolves with the session id the server answered with, rejects when
75
83
  * the socket died first; a later close is reported through `onClose` with its code and the
@@ -89,4 +97,9 @@ export interface IWebSocketConnection {
89
97
  * rather than throwing, which is what a socket that cannot deliver right now already means.
90
98
  */
91
99
  answerHumanTool?: (toolCallId: string, answer: string) => 'sent' | 'queued';
100
+ /**
101
+ * Send a frame that is not a turn of the user's (`AnnounceDetachedRun`). Throws when the socket is not open.
102
+ * Optional like `answerHumanTool`: a transport without it cannot ask for an announcement, and the gateway says so.
103
+ */
104
+ sendBaseMessage?: (message: IMessageBase) => void;
92
105
  }
@@ -0,0 +1,68 @@
1
+ import { ServerEvent } from '../../models/ServerEvent';
2
+ import { InteractionStart, InteractionStatistics } from '../../models/semanticKernelModel/models';
3
+ import { ConnectOptions, IMessage, IWebSocketConnection } from '../WebSocketConnection/webSocketConnection';
4
+ import { DetachedRunFetch, DetachedRunFollowError, DetachedRunFramesRetry } from './streamDetachedRunFrames';
5
+ export interface DetachedRunFramesTransportOptions {
6
+ /** The agents server the run lives on. */
7
+ baseUrl: string;
8
+ fetchImpl?: DetachedRunFetch;
9
+ getToken?: () => string | undefined | null | Promise<string | undefined | null>;
10
+ /** Refresh after a 401; true retries once (see `streamDetachedRunFrames`). */
11
+ onUnauthorized?: () => Promise<boolean>;
12
+ retry?: DetachedRunFramesRetry;
13
+ }
14
+ /**
15
+ * A read-only {@link IWebSocketConnection} over a detached run's frames stream (AIA Issue 1548, phase 5) — what lets
16
+ * the ordinary chat engine draw a run as a transcript, rendering exactly as the chat does.
17
+ *
18
+ * <p>`connect(runId)` follows `GET /detached-runs/{runId}/frames` and resolves with the run id once the server answers
19
+ * with a stream; every frame then goes through the same decode as the socket's — `InteractionStarted` to
20
+ * `onInteractionStarted`, everything else to `onEvent` as a `ServerEvent`. The reader reconnects a dropped stream from
21
+ * the last seq on its own, so the gateway's supervisor sees one long connection; only an answer no retry will change
22
+ * (404, 401/403) reaches it, as the close code it would have had on the socket.</p>
23
+ *
24
+ * <p>Nothing is ever sent: there is no prompt in a transcript. A turn's end marker the server streams past (a resumed
25
+ * run going on into its next turn) is only a cursor move; {@link onEnd} fires when the server closes the stream right
26
+ * after one. That end (the run stopped — it settled, or is waiting for an answer) is not a close either: the
27
+ * transcript stays as it is, and {@link follow} picks the stream up again from the last seq when the host knows the
28
+ * run moved on (it answered it).</p>
29
+ */
30
+ export declare class DetachedRunFramesTransport implements IWebSocketConnection {
31
+ onEvent?: (event: MessageEvent | ServerEvent) => Promise<void>;
32
+ onError?: (error: string) => void;
33
+ onOpen?: () => void;
34
+ onFirstToken?: (interactionId: string) => void;
35
+ onSuspended?: () => void;
36
+ onClose?: (code: number, reason: string) => void;
37
+ onNewPacket?: (stats: InteractionStatistics) => void;
38
+ onInteractionStarted?: (start: InteractionStart) => void;
39
+ /** The stream of the current follow is over: the server closed it right after an `event: end`. */
40
+ onEnd?: (lastSeq: number) => void;
41
+ /** Following stopped for good — the run is gone, forbidden, the credentials failed twice, or retries ran out. */
42
+ onFollowError?: (error: DetachedRunFollowError) => void;
43
+ private readonly options;
44
+ private readonly serializer;
45
+ private readonly firstTokens;
46
+ private runId?;
47
+ private controller;
48
+ private following;
49
+ private lastSeq;
50
+ constructor(options: DetachedRunFramesTransportOptions);
51
+ /** The highest seq delivered so far — where the next follow resumes. */
52
+ get cursor(): number;
53
+ /** Whether a follow is running (false after `end`, an abort or a fatal answer). */
54
+ get isFollowing(): boolean;
55
+ connect(runId?: string, options?: ConnectOptions): Promise<string>;
56
+ /**
57
+ * Follow again from the last seq — after the stream ended and the run was resumed (answered). A no-op while a
58
+ * follow is running. Resolves once the server answers with the stream.
59
+ */
60
+ follow(): Promise<string>;
61
+ private start;
62
+ /** One frame, decoded exactly as the chat socket decodes it. A frame that fails to decode is skipped. */
63
+ private dispatch;
64
+ sendMessage(_message: IMessage): void;
65
+ suspendStream(): void;
66
+ closeStream(): void;
67
+ isConnected(): boolean;
68
+ }
@@ -0,0 +1,25 @@
1
+ import { TodoList } from '../../models/todoListModel';
2
+ /**
3
+ * What one frame of a detached run says about its progress, as far as a task box reads it (AIA Issue 1548 §3b):
4
+ * a tool it called, a piece of what it is writing, or its task list changing.
5
+ */
6
+ export type DetachedRunActivitySignal = {
7
+ kind: 'tool';
8
+ name: string;
9
+ interactionId: string;
10
+ } | {
11
+ kind: 'text';
12
+ text: string;
13
+ partial: boolean;
14
+ interactionId: string;
15
+ } | {
16
+ kind: 'todo';
17
+ todoList: TodoList;
18
+ };
19
+ /** The tool event the agent emits whenever its task list changes; its data is the list as JSON. */
20
+ export declare const TODO_LIST_UPDATED_EVENT = "todolistUpdated";
21
+ /**
22
+ * The progress signals in one frame of a run's stream, in order — decoded exactly as the chat decodes the frame.
23
+ * Anything else (an announcement, reasoning, a tool's result) says nothing a one-line activity needs.
24
+ */
25
+ export declare function readDetachedRunActivity(raw: unknown, serializer?: import('typedjson').TypedJSON<import('../..').StreamingResponse>): DetachedRunActivitySignal[];
@@ -0,0 +1,110 @@
1
+ /**
2
+ * Following a detached run's frames over server-sent events (AIA Issue 1548, phase 5).
3
+ *
4
+ * The SDK serves `GET {baseUrl}/detached-runs/{id}/frames?afterSeq=N` as `text/event-stream`: one event per frame —
5
+ * `id: {seq}` + `data: {the frame exactly as the chat socket sends it}` — plus `event: end` + `data: {its seq}` for
6
+ * every turn's end marker, and `: alive` comments in between to keep proxies from idling the request out.
7
+ *
8
+ * <p><b>An `end` event is advisory; the CLOSE is what ends the stream.</b> A resumed run's turns all live in one
9
+ * session, each closed by its own end marker, and the server relays every one of them — it closes the response only
10
+ * after an end that is the last thing saved for a run no longer active. So the reader records an end's seq (a
11
+ * reconnect then asks from after it), keeps reading into the next turn, and decides on the close: a body that finished
12
+ * right after an end is over; one that finished after frames past the last end (or with no end at all) dropped, and is
13
+ * reconnected. Stopping at the first end froze a run opened in its second turn at the end of its first.</p>
14
+ *
15
+ * <p><b>`fetch`, not `EventSource`.</b> The route is behind a bearer token, and `EventSource` cannot send an
16
+ * `Authorization` header. So the body is read as a stream and parsed here, and the reconnect `EventSource` would have
17
+ * done is done here too: a connection that drops anywhere but right after an `end` is reopened from the last seq it delivered, on a bounded
18
+ * backoff, until the caller aborts.</p>
19
+ *
20
+ * <p><b>The HTTP layer is the host's to supply.</b> A host with its own auth (a refresh on 401, a tenant header) passes
21
+ * a fetch-compatible `fetchImpl`; a host with only a token passes `getToken`. Both may be given — the token is set as
22
+ * the `Authorization` header and the host's fetch may override it.</p>
23
+ *
24
+ * <p><b>A 401 gets one second chance.</b> A long follow outlives a token: on a 401 the reader asks the host's
25
+ * `onUnauthorized` to refresh (true ⇒ retry), or else re-reads `getToken` and retries if the token changed. A second
26
+ * 401 in a row is final.</p>
27
+ */
28
+ /** The slice of `fetch` the reader uses. A host's authenticated wrapper around `window.fetch` fits it. */
29
+ export type DetachedRunFetch = (input: string, init: RequestInit) => Promise<Response>;
30
+ export interface DetachedRunFramesRetry {
31
+ /** First delay after a dropped connection. Default 500 ms. */
32
+ initialMs?: number;
33
+ /** The ceiling the doubling stops at. Default 15 s. */
34
+ maxMs?: number;
35
+ /** Consecutive failed attempts before the reader gives up and rejects. Default: never gives up. */
36
+ maxAttempts?: number;
37
+ }
38
+ export interface StreamDetachedRunFramesOptions {
39
+ /** The agents server the run lives on (the same base URL the chat socket dials). */
40
+ baseUrl: string;
41
+ runId: string;
42
+ /** The HTTP layer. Default: the global `fetch`. */
43
+ fetchImpl?: DetachedRunFetch;
44
+ /** The bearer token, read before EVERY request so a refreshed token is picked up on a reconnect. */
45
+ getToken?: () => string | undefined | null | Promise<string | undefined | null>;
46
+ /** Deliver frames after this seq. Default 0 (the run's whole history). */
47
+ afterSeq?: number;
48
+ /** Stops the reader — the open request is cancelled and the promise resolves `aborted`. */
49
+ signal?: AbortSignal;
50
+ /** One frame, parsed from its `data:` JSON, with its seq (`id:`). Frames at or below the cursor are skipped. */
51
+ onFrame: (frame: unknown, seq: number | undefined) => void;
52
+ /**
53
+ * The run's stream is over — the server closed it right after an `event: end` — and nothing will follow until the
54
+ * run is resumed. An end the server keeps streaming past (a finished turn of a run still going) does not fire it.
55
+ */
56
+ onEnd?: (lastSeq: number) => void;
57
+ /** A request was answered with a stream (every successful (re)connect). */
58
+ onOpen?: () => void;
59
+ /**
60
+ * A request was answered 401. Refresh the credentials and resolve true to retry once with a fresh `getToken`;
61
+ * false (or no hook) retries only when `getToken` already returns a different token.
62
+ */
63
+ onUnauthorized?: () => Promise<boolean>;
64
+ /** A connection failed or dropped and will be retried in `retryInMs`. */
65
+ onRetry?: (error: unknown, attempt: number, retryInMs: number) => void;
66
+ retry?: DetachedRunFramesRetry;
67
+ }
68
+ export interface DetachedRunFramesResult {
69
+ /** `end`: the server closed the stream right after an end marker; `aborted`: the caller stopped it. */
70
+ reason: 'end' | 'aborted';
71
+ /** The highest seq delivered, end markers included — where a later follow resumes. */
72
+ lastSeq: number;
73
+ }
74
+ /** An answer no retry will change: the run is not there, or the caller may not see it. */
75
+ export declare class DetachedRunFramesHttpError extends Error {
76
+ readonly status: number;
77
+ constructor(status: number, message?: string);
78
+ }
79
+ /** Why following a run stopped for good — what a page tells the reader. */
80
+ export interface DetachedRunFollowError {
81
+ /** `notFound` 404/410 · `forbidden` 403 · `unauthorized` 401 (after the second chance) · `gaveUp` anything else. */
82
+ kind: 'notFound' | 'forbidden' | 'gaveUp' | 'unauthorized';
83
+ status?: number;
84
+ cause?: unknown;
85
+ }
86
+ /** Classify what {@link streamDetachedRunFrames} rejected with. */
87
+ export declare function toDetachedRunFollowError(error: unknown): DetachedRunFollowError;
88
+ /** One dispatched server-sent event. */
89
+ export interface SseEvent {
90
+ event?: string;
91
+ data: string;
92
+ id?: string;
93
+ }
94
+ /**
95
+ * A server-sent-events parser over text chunks that may split anywhere — mid-line, mid-field, between the `\r` and
96
+ * `\n` of a CRLF. Fields per the HTML spec: `field: value` with one optional space after the colon, `data` lines joined
97
+ * by `\n`, a line starting with `:` is a comment, a blank line dispatches. An event with neither data nor a name is
98
+ * dropped (that is what a lone comment block amounts to).
99
+ */
100
+ export declare function createSseParser(onEvent: (event: SseEvent) => void): {
101
+ push(chunk: string): void;
102
+ flush(): void;
103
+ idle(): boolean;
104
+ };
105
+ /**
106
+ * Follow a detached run's frames until the server ends the stream or `signal` aborts. Resolves with why it stopped
107
+ * and the last seq delivered; rejects with {@link DetachedRunFramesHttpError} for an answer a retry will not change
108
+ * (4xx other than 408/429), or with the last error once `retry.maxAttempts` consecutive attempts failed.
109
+ */
110
+ export declare function streamDetachedRunFrames(options: StreamDetachedRunFramesOptions): Promise<DetachedRunFramesResult>;
@@ -6,6 +6,7 @@ export { EventBusService } from './eventBusService';
6
6
  export type { FirstTokenEventDetails } from './eventBusService';
7
7
  export { AgentGatewayService } from './servers/AgentGatewayService';
8
8
  export type { GatewaySendMessageOptions } from './servers/AgentGatewayService';
9
+ export type { AgentGatewayOptions, AnnounceDetachedRunResult } from './servers/AgentGatewayWSAsync';
9
10
  export { AgentGatewayWSAsync } from './servers/AgentGatewayWSAsync';
10
11
  export { WebSocketConnecionV2 } from './WebSocketConnection/WebSocketConnectionV2';
11
12
  export type { IWebSocketConnection, IMessage } from './WebSocketConnection/webSocketConnection';
@@ -17,3 +18,9 @@ export { HttpSessionService } from './httpSessionService';
17
18
  export { HttpArtifactService } from './httpArtifactService';
18
19
  export { resolveAccessToken } from './accessTokenProvider';
19
20
  export type { AccessTokenProvider } from './accessTokenProvider';
21
+ export { streamDetachedRunFrames, createSseParser, DetachedRunFramesHttpError, toDetachedRunFollowError, } from './detachedRun/streamDetachedRunFrames';
22
+ export type { StreamDetachedRunFramesOptions, DetachedRunFramesResult, DetachedRunFramesRetry, DetachedRunFetch, DetachedRunFollowError, SseEvent, } from './detachedRun/streamDetachedRunFrames';
23
+ export { DetachedRunFramesTransport } from './detachedRun/DetachedRunFramesTransport';
24
+ export { readDetachedRunActivity, TODO_LIST_UPDATED_EVENT } from './detachedRun/detachedRunActivity';
25
+ export type { DetachedRunActivitySignal } from './detachedRun/detachedRunActivity';
26
+ export type { DetachedRunFramesTransportOptions } from './detachedRun/DetachedRunFramesTransport';
@@ -1,3 +1,3 @@
1
1
  export { AgentGatewayWSAsync as AgentGatewayService } from './AgentGatewayWSAsync';
2
- export type { GatewaySendMessageOptions } from './AgentGatewayWSAsync';
2
+ export type { GatewaySendMessageOptions, AnnounceDetachedRunResult } from './AgentGatewayWSAsync';
3
3
  export type { OpenOptions as GatewayOpenOptions, HaltReason } from './connectionSupervisor';