@aintela/chat 0.5.3 → 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 (73) hide show
  1. package/README.md +46 -3
  2. package/dist/Memory-BUnmYGNv.js +37 -0
  3. package/dist/Memory-BUnmYGNv.js.map +1 -0
  4. package/dist/components.js +7782 -7222
  5. package/dist/components.js.map +1 -1
  6. package/dist/{httpArtifactService-EEhF_mp9.js → detachedRunActivity-CjyFTKSw.js} +784 -339
  7. package/dist/detachedRunActivity-CjyFTKSw.js.map +1 -0
  8. package/dist/detachedRunModel-X59Pb5V-.js +67 -0
  9. package/dist/detachedRunModel-X59Pb5V-.js.map +1 -0
  10. package/dist/hooks.js +1 -1
  11. package/dist/httpSessionService-Ckb9Cxia.js +320 -0
  12. package/dist/httpSessionService-Ckb9Cxia.js.map +1 -0
  13. package/dist/index.js +291 -265
  14. package/dist/models.js +46 -39
  15. package/dist/{serializer-CC-nM3ig.js → serializer-DNUH6kgE.js} +607 -547
  16. package/dist/serializer-DNUH6kgE.js.map +1 -0
  17. package/dist/services.js +22 -15
  18. package/dist/src/components/AiChat/AiChatContext.d.ts +3 -1
  19. package/dist/src/components/AiChat/AiChatTypes.d.ts +7 -1
  20. package/dist/src/components/AiChat/ChatPane/InteractionOriginBadge.d.ts +15 -0
  21. package/dist/src/components/AiChat/ChatPane/messageUserOrigin.test.d.ts +1 -0
  22. package/dist/src/components/AiChat/ChatPane/parts/uiToolRegistry.d.ts +1 -1
  23. package/dist/src/components/AiChat/aiChatEngine.d.ts +13 -1
  24. package/dist/src/components/AiChat/index.d.ts +1 -1
  25. package/dist/src/components/AiChat/stateConfiguration.d.ts +5 -5
  26. package/dist/src/components/index.d.ts +3 -1
  27. package/dist/src/components/v2/{SubAgentBoxV2.d.ts → DetachedRunBoxV2.d.ts} +6 -6
  28. package/dist/src/components/v2/DetachedRunTaskBox.d.ts +68 -0
  29. package/dist/src/components/v2/DetachedRunTaskBox.live.test.d.ts +1 -0
  30. package/dist/src/components/v2/DetachedRunTaskBox.test.d.ts +1 -0
  31. package/dist/src/components/v2/DetachedRunTranscript.d.ts +89 -0
  32. package/dist/src/components/v2/DetachedRunTranscript.test.d.ts +1 -0
  33. package/dist/src/components/v2/index.d.ts +9 -2
  34. package/dist/src/components/v2/toolCategories.d.ts +1 -1
  35. package/dist/src/components/v2/useDetachedRunLiveActivity.d.ts +30 -0
  36. package/dist/src/components/v2/useDetachedRunResumeKey.d.ts +15 -0
  37. package/dist/src/components/v2/useDetachedRunResumeKey.test.d.ts +1 -0
  38. package/dist/src/models/Interaction.d.ts +15 -0
  39. package/dist/src/models/ServerEvent.d.ts +3 -3
  40. package/dist/src/models/detachedRunModel.d.ts +59 -0
  41. package/dist/src/models/detachedRunModel.test.d.ts +1 -0
  42. package/dist/src/models/enums.d.ts +3 -1
  43. package/dist/src/models/index.d.ts +5 -4
  44. package/dist/src/models/semanticKernelModel/models.d.ts +27 -6
  45. package/dist/src/services/WebSocketConnection/WebSocketConnectionV2.d.ts +2 -1
  46. package/dist/src/services/WebSocketConnection/streamStats.d.ts +2 -2
  47. package/dist/src/services/WebSocketConnection/webSocketConnection.d.ts +15 -2
  48. package/dist/src/services/detachedRun/DetachedRunFramesTransport.d.ts +68 -0
  49. package/dist/src/services/detachedRun/DetachedRunFramesTransport.test.d.ts +1 -0
  50. package/dist/src/services/detachedRun/detachedRunActivity.d.ts +25 -0
  51. package/dist/src/services/detachedRun/streamDetachedRunFrames.d.ts +110 -0
  52. package/dist/src/services/detachedRun/streamDetachedRunFrames.test.d.ts +1 -0
  53. package/dist/src/services/index.d.ts +7 -0
  54. package/dist/src/services/servers/AgentGatewayService.d.ts +1 -1
  55. package/dist/src/services/servers/AgentGatewayWSAsync.d.ts +72 -6
  56. package/dist/src/services/servers/gatewayAnnounceDetachedRun.test.d.ts +1 -0
  57. package/dist/src/services/servers/gatewayInteractionStarted.test.d.ts +1 -0
  58. package/dist/src/services/wire/decodeFrame.d.ts +7 -2
  59. package/dist/tests/fakes/fakeWebSocket.d.ts +8 -2
  60. package/dist/tests/fakes/makeGateway.d.ts +3 -1
  61. package/dist/tests/fixtures.d.ts +8 -8
  62. package/dist/{useChatSessions-C6sYF4U6.js → useChatSessions-aTjNcj8q.js} +2 -2
  63. package/dist/{useChatSessions-C6sYF4U6.js.map → useChatSessions-aTjNcj8q.js.map} +1 -1
  64. package/package.json +1 -1
  65. package/dist/ClientMessage-DUby3KyC.js +0 -34
  66. package/dist/ClientMessage-DUby3KyC.js.map +0 -1
  67. package/dist/Memory-CjrYSkzB.js +0 -47
  68. package/dist/Memory-CjrYSkzB.js.map +0 -1
  69. package/dist/httpArtifactService-EEhF_mp9.js.map +0 -1
  70. package/dist/httpSessionService-wBby4ggl.js +0 -309
  71. package/dist/httpSessionService-wBby4ggl.js.map +0 -1
  72. package/dist/serializer-CC-nM3ig.js.map +0 -1
  73. package/dist/src/models/subAgentModel.d.ts +0 -48
@@ -0,0 +1,68 @@
1
+ import { default as React } from 'react';
2
+ import { DetachedRunView } from '../../models/detachedRunModel';
3
+ import { DetachedRunStreamAuth } from './useDetachedRunLiveActivity';
4
+ import { DetachedRunTranscriptPresentationProps } from './DetachedRunTranscript';
5
+ import { PartRendererMap, UiToolRegistry } from '../AiChat/ChatPane/parts';
6
+ import { User } from '../../models/contexts';
7
+ /** A task's structured conclusion, as far as the box reads it: `{ outcome?, summary, question? }`. */
8
+ export interface DetachedRunConclusion {
9
+ outcome?: string;
10
+ summary: string;
11
+ question?: string;
12
+ }
13
+ export interface DetachedRunTaskBoxProps extends DetachedRunStreamAuth {
14
+ /** The run's id — what `start_task` returned. */
15
+ runId: string;
16
+ /** Display name until the first read answers. */
17
+ name?: string;
18
+ /** The status the start reported — drawn until the first read answers. */
19
+ initialStatus?: string;
20
+ /** Reads the run (the SDK's `GET /detached-runs/{id}`); null when it does not exist. */
21
+ fetchRun: (runId: string, signal: AbortSignal) => Promise<DetachedRunView | null>;
22
+ /** How often a working run is re-read. Default 5 s. */
23
+ pollIntervalMs?: number;
24
+ /** How often a run waiting for an answer is re-read — the answer may come from another channel. Default 15 s. */
25
+ waitingPollMs?: number;
26
+ /** Draws the conclusion; the default shows its `summary` and `question` (or the raw text). */
27
+ renderConclusion?: (conclusion: DetachedRunConclusion, run: DetachedRunView) => React.ReactNode;
28
+ /** The word before the name in the header. Default "tarefa". */
29
+ label?: string;
30
+ /**
31
+ * Called once per settle the conversation has not been told about (`announced === false` on a Completed / Failed /
32
+ * Cancelled / WaitingForInput record) — whether the box watched it settle or found it so on its first read (a
33
+ * conversation reopened later). Once per `(runId, settledAt)`: a resumed run that settles anew calls it again. The
34
+ * host answers it with `engine.announceDetachedRun(run.id, run.settledAt)` (AIA Issue 1548 §5).
35
+ */
36
+ onSettled?: (run: DetachedRunView) => void;
37
+ /** The user whose token reads the run's artifacts in the detailed view (see `DetachedRunTranscript`). */
38
+ user?: User;
39
+ getUser?: () => User | undefined;
40
+ /** Renderers for the detailed view — the host's, so the run's tool cards look as they do in the chat. */
41
+ uiTools?: UiToolRegistry;
42
+ partRenderers?: PartRendererMap;
43
+ /** Any other presentation prop for the detailed view's `DetachedRunTranscript`. */
44
+ transcriptProps?: Partial<DetachedRunTranscriptPresentationProps>;
45
+ /** Height of the detailed view. Default 360 px. */
46
+ transcriptHeight?: number | string;
47
+ }
48
+ /**
49
+ * A detached run (a task) drawn where the conversation started it, kept current until it ends (AIA Issue 1548).
50
+ *
51
+ * <p><b>Driven by a read; enlivened by the stream.</b> A run executes on its own session — in-process or on a worker —
52
+ * and its frames do not reach the conversation's socket, so the box reads the run's stored state every few seconds:
53
+ * the record is the source of truth (status, progress, conclusion), current wherever the run executes, and it survives
54
+ * a reconnect or a session reopened tomorrow. Given a `baseUrl` and credentials (`fetchImpl` / `getToken`), the box
55
+ * also follows the run's frames while it is Pending/Running — for a live activity line and a task list that moves the
56
+ * moment the agent updates it, the record winning whenever it is newer. Expanded ("ver detalhes"), it shows the run's
57
+ * whole transcript. Without credentials it polls only, as before.</p>
58
+ *
59
+ * <p>The read stops at a terminal status and when the box unmounts. `WaitingForInput` is not terminal: the task
60
+ * stopped to ask, and the answer resumes it on the same id, so the box keeps reading it, slowly. A failed read is
61
+ * shown quietly and retried — a box that goes blank because one request failed reads as the task having vanished.</p>
62
+ */
63
+ export declare function DetachedRunTaskBox({ runId, name, initialStatus, fetchRun, pollIntervalMs, waitingPollMs, renderConclusion, label, onSettled, baseUrl, fetchImpl, getToken, onUnauthorized, user, getUser, uiTools, partRenderers, transcriptProps, transcriptHeight, }: DetachedRunTaskBoxProps): import("react/jsx-runtime").JSX.Element;
64
+ /** A task's conclusion is JSON in its own format (`{ outcome, summary, question }` for the booking task); anything
65
+ * else is shown as it came. */
66
+ export declare function parseDetachedRunConclusion(conclusion: string | null | undefined): DetachedRunConclusion | null;
67
+ /** The header's one-word state. */
68
+ export declare function detachedRunHeadline(status: string, outcome?: string, missing?: boolean): string;
@@ -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;
@@ -38,8 +38,15 @@ export { ChatsHistoryV2 as ChatsHistory, ChatsHistoryV2 } from './ChatsHistoryV2
38
38
  export type { ChatsHistoryV2Props as ChatsHistoryProps, ChatsHistoryV2Props, ChatsHistoryV2Item as ChatsHistoryItem, ChatsHistoryV2Item, } from './ChatsHistoryV2';
39
39
  export { TaskListV2 as TaskList, TaskListV2 } from './TaskListV2';
40
40
  export type { TaskListV2Props as TaskListProps, TaskListV2Props } from './TaskListV2';
41
- export { SubAgentBoxV2 as SubAgentBox, SubAgentBoxV2 } from './SubAgentBoxV2';
42
- export type { SubAgentBoxV2Props as SubAgentBoxProps, SubAgentBoxV2Props, SubAgentBoxV2Level as SubAgentBoxLevel, SubAgentBoxV2Level } from './SubAgentBoxV2';
41
+ export { DetachedRunBoxV2 as DetachedRunBox, DetachedRunBoxV2 } from './DetachedRunBoxV2';
42
+ export { DetachedRunTaskBox, parseDetachedRunConclusion, detachedRunHeadline } from './DetachedRunTaskBox';
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';
49
+ export type { DetachedRunBoxV2Props as DetachedRunBoxProps, DetachedRunBoxV2Props, DetachedRunBoxV2Level as DetachedRunBoxLevel, DetachedRunBoxV2Level } from './DetachedRunBoxV2';
43
50
  export { AgentActivityV2 as AgentActivity, AgentActivityV2 } from './AgentActivityV2';
44
51
  export type { AgentActivityV2Props as AgentActivityProps, AgentActivityV2Props } from './AgentActivityV2';
45
52
  export { RunProgressPanelV2 as RunProgressPanel, RunProgressPanelV2 } from './RunProgressPanelV2';
@@ -1,5 +1,5 @@
1
1
  import { default as React } from 'react';
2
- export type ToolCategoryId = 'sql' | 'files' | 'shell' | 'python' | 'dashboard' | 'web' | 'memory' | 'subagent' | 'tasks' | 'scripts' | 'other';
2
+ export type ToolCategoryId = 'sql' | 'files' | 'shell' | 'python' | 'dashboard' | 'web' | 'memory' | 'task' | 'tasks' | 'scripts' | 'other';
3
3
  export interface ToolCategoryMeta {
4
4
  id: ToolCategoryId;
5
5
  label: string;
@@ -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[];
@@ -69,7 +69,7 @@ export interface ThoughtDetails {
69
69
  export interface ToolEventDetails {
70
70
  eventName: string;
71
71
  eventData: string;
72
- subAgentId?: string;
72
+ detachedRunId?: string;
73
73
  /** Id of the session that generated the event (server-stamped). Lets consumers
74
74
  * persist event-derived state to the right session even for stale/trailing events. */
75
75
  sessionId?: string;
@@ -127,8 +127,8 @@ export declare class ServerEvent {
127
127
  endMessageData?: EndMessageData;
128
128
  command?: string;
129
129
  session_information?: SessionInformation;
130
- subAgentId?: string;
131
- subAgentName?: string;
130
+ detachedRunId?: string;
131
+ detachedRunName?: string;
132
132
  visible: boolean;
133
133
  constructor(interactionId: string);
134
134
  static createErrorEvent(errorMessage: string, interactionId: string): ServerEvent;
@@ -0,0 +1,59 @@
1
+ import { TodoList } from './todoListModel';
2
+ /**
3
+ * Mirrors the SDK's `AIA.Agents.Models.Agent.AgentStatus` enum. Values come back as plain strings (the
4
+ * record keeps `Status.ToString()`).
5
+ *
6
+ * `WaitingForInput` (AIntelA.Agents ≥ 0.20): the run stopped to ask a question and nothing is executing.
7
+ * It is NOT terminal — the task resumes when an answer arrives — so a poller should keep watching it.
8
+ */
9
+ export type DetachedRunStatus = 'Pending' | 'Running' | 'WaitingForInput' | 'Completed' | 'Failed' | 'Cancelled' | 'Unknown';
10
+ /**
11
+ * Why a settled run stopped — the SDK's `StopReason`. Absent while a run is active and on records written
12
+ * before the SDK had it.
13
+ */
14
+ export type DetachedRunStopReason = 'Concluded' | 'NeedsInput' | 'EndedWithoutConclusion' | 'Cancelled' | 'Failed';
15
+ /**
16
+ * A detached run as the Agents SDK's REST surface returns it (`GET /detached-runs`, `GET /detached-runs/{id}`):
17
+ * the state a client draws — a task box, a page of runs.
18
+ *
19
+ * `percentComplete` is 0–100 (null while the run has no task list). `conclusion` is the run's structured
20
+ * conclusion as raw JSON, in the task's own format.
21
+ */
22
+ export interface DetachedRunView {
23
+ id: string;
24
+ name: string;
25
+ agentId: string;
26
+ status: DetachedRunStatus | string;
27
+ stopReason?: DetachedRunStopReason | string | null;
28
+ todoList?: TodoList | null;
29
+ percentComplete?: number | null;
30
+ currentStep?: string | null;
31
+ error?: string | null;
32
+ hasConclusion: boolean;
33
+ conclusion?: string | null;
34
+ parentSessionId: string;
35
+ sessionId: string;
36
+ cancelRequested: boolean;
37
+ created?: string | null;
38
+ updatedAt?: string | null;
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;
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;
52
+ /**
53
+ * Status values after which the detached run will never change again. `WaitingForInput` is deliberately absent:
54
+ * the run has stopped, but the task resumes when its question is answered.
55
+ */
56
+ export declare const DETACHED_RUN_TERMINAL_STATUSES: ReadonlyArray<DetachedRunStatus>;
57
+ export declare function isDetachedRunTerminalStatus(status: string | undefined | null): boolean;
58
+ /** True when the task stopped to ask a question and is waiting for an answer. */
59
+ export declare function isDetachedRunWaitingForInput(status: string | undefined | null): boolean;
@@ -0,0 +1 @@
1
+ export {};
@@ -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';
@@ -18,8 +19,8 @@ export * from './enums';
18
19
  export type { Artifact } from './Artifact';
19
20
  export type { ArtifactData } from './ArtifactData';
20
21
  export type { TodoList, TodoItem, TodoItemStatus } from './todoListModel';
21
- export type { SubAgentDto, SubAgentMessage, SubAgentStatus } from './subAgentModel';
22
- export { isSubAgentTerminalStatus, SUB_AGENT_TERMINAL_STATUSES } from './subAgentModel';
22
+ export type { DetachedRunView, DetachedRunStatus, DetachedRunStopReason } 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[];
@@ -180,8 +184,8 @@ export declare class LlmEvent {
180
184
  command?: Commands;
181
185
  content?: ChatMessageContent;
182
186
  streamingParts?: StreamingKernelContent[];
183
- subAgentId?: string;
184
- subAgentName?: string;
187
+ detachedRunId?: string;
188
+ detachedRunName?: string;
185
189
  text?: string;
186
190
  }
187
191
  export declare class PartialLlmEvent {
@@ -194,7 +198,22 @@ export declare class PartialLlmEvent {
194
198
  type?: string;
195
199
  iteractionId?: string;
196
200
  partialEventType?: EventTypeInformation;
197
- subAgentId?: string;
201
+ detachedRunId?: string;
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;
198
217
  }
199
218
  export declare class StreamingResponse {
200
219
  type: string;
@@ -208,8 +227,10 @@ export declare class StreamingResponse {
208
227
  */
209
228
  accessToken?: string;
210
229
  partialEvent?: PartialLlmEvent;
211
- subAgentId?: string;
212
- subAgentName?: string;
230
+ /** Only on `type: "InteractionStarted"`: the turn that is about to stream. */
231
+ interaction?: InteractionStart;
232
+ detachedRunId?: string;
233
+ detachedRunName?: string;
213
234
  /**
214
235
  * Server-assigned monotonic sequence number for events emitted by an InteractionRun.
215
236
  * Tracked client-side as `lastSeq` so reconnects can resume mid-stream via
@@ -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);
@@ -29,13 +29,13 @@ export declare class StreamStatsTracker {
29
29
  resetForInteraction(): void;
30
30
  /**
31
31
  * Account for one decoded frame. `sessionInformation` is only read off main-agent
32
- * frames — a sub-agent's reading describes a different session.
32
+ * frames — a detached run's reading describes a different session.
33
33
  */
34
34
  record(opts: {
35
35
  rawLength: number;
36
36
  textLength: number;
37
37
  sessionInformation?: SessionInformation;
38
- fromSubAgent: boolean;
38
+ fromDetachedRun: boolean;
39
39
  }): void;
40
40
  private flushCoalesced;
41
41
  }
@@ -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
+ }