@healthcloudai/hc-ams 3.5.1 → 3.6.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.
- package/README.md +103 -0
- package/dist/index.cjs +8 -0
- package/dist/index.d.cts +20 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +8 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -71,6 +71,18 @@ only cover the plain-CRUD path.
|
|
|
71
71
|
|
|
72
72
|
## WebSocket agent-chat runtime
|
|
73
73
|
|
|
74
|
+
> **Since 3.5.1**: the patient token is sent as the first WebSocket frame
|
|
75
|
+
> (`{"type":"auth","token":"..."}`) right after the socket opens, never in
|
|
76
|
+
> the connect URL or as a WS subprotocol — `chat.connect()` doesn't resolve
|
|
77
|
+
> until the server replies `auth_ok`. This is handled internally; you don't
|
|
78
|
+
> need to change any calling code that already passes `healthcloudToken` or
|
|
79
|
+
> `getAccessToken`. It **does require the AMS backend to be on the matching
|
|
80
|
+
> version** (the corresponding server-side change is
|
|
81
|
+
> [healthcloudservices/healthcloud-ams-services#280](https://github.com/healthcloudservices/healthcloud-ams-services/issues/280),
|
|
82
|
+
> merged via #288) — against an older backend, `connect()` will reject with
|
|
83
|
+
> an auth timeout instead of connecting. `WssClientOptions.tokenTransport`
|
|
84
|
+
> (0.0.1) is removed; if your code set it explicitly, delete that line.
|
|
85
|
+
|
|
74
86
|
```ts
|
|
75
87
|
const sdk = new HCAmsSDK({ environment: "dev", tenantId: "<TENANT_ID>", accessToken: tenantAdminToken });
|
|
76
88
|
|
|
@@ -91,6 +103,30 @@ console.log(turn.message, turn.transfers, turn.artifacts, turn.notifications, tu
|
|
|
91
103
|
chat.close();
|
|
92
104
|
```
|
|
93
105
|
|
|
106
|
+
**Note:** the `HCAmsSDK` instance's own `accessToken` (Tenant Admin) above
|
|
107
|
+
is only needed because this example uses `testPersonas.login` to mint a
|
|
108
|
+
*synthetic* test patient — a testing convenience, not a production
|
|
109
|
+
pattern. `connectAgentChat`/`WssClient` never read that `accessToken`;
|
|
110
|
+
they only ever use the `healthcloudToken` you pass them explicitly. A real
|
|
111
|
+
patient-facing app needs **no Tenant Admin token at all** — get the
|
|
112
|
+
patient token from your own patient auth (`@healthcloudai/hc-sdk`), e.g.:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
import { HCSDK } from "@healthcloudai/hc-sdk";
|
|
116
|
+
import { HCAmsSDK } from "@healthcloudai/hc-ams";
|
|
117
|
+
|
|
118
|
+
const patientSdk = new HCSDK({ environment: "dev", tenantId: "<TENANT_ID>" });
|
|
119
|
+
const login = await patientSdk.auth.login({ email, password }); // real patient credentials
|
|
120
|
+
|
|
121
|
+
const amsSdk = new HCAmsSDK({ environment: "dev", tenantId: "<TENANT_ID>" }); // no accessToken needed
|
|
122
|
+
const chat = amsSdk.connectAgentChat({
|
|
123
|
+
patientId: login.fhir_patient_id,
|
|
124
|
+
healthcloudToken: login.access_token,
|
|
125
|
+
agentId: "<AGENT_ID>",
|
|
126
|
+
});
|
|
127
|
+
await chat.connect();
|
|
128
|
+
```
|
|
129
|
+
|
|
94
130
|
`WssClient` also exposes raw typed event subscription for finer-grained
|
|
95
131
|
control:
|
|
96
132
|
|
|
@@ -104,6 +140,73 @@ The entire multi-agent conversation (orchestrator plus any number of
|
|
|
104
140
|
downstream specialist agents) lives on this **one** WebSocket connection —
|
|
105
141
|
agent switches arrive as `transfer` events, not reconnects.
|
|
106
142
|
|
|
143
|
+
For a **reconnect** (network drop, or your own periodic re-auth), pass
|
|
144
|
+
`getAccessToken` instead of a static `healthcloudToken` so a fresh token is
|
|
145
|
+
resolved on every `connect()` call rather than replaying a captured,
|
|
146
|
+
possibly-expired one:
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
const chat = sdk.connectAgentChat({
|
|
150
|
+
patientId,
|
|
151
|
+
getAccessToken: () => myAuthStore.getCurrentPatientToken(), // called on every connect()
|
|
152
|
+
agentId,
|
|
153
|
+
});
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Guest chat before sign-in, then handoff to an authenticated conversation
|
|
157
|
+
|
|
158
|
+
For an agent configured with `requires_auth: false` (a public, pre-login
|
|
159
|
+
agent), no patient login or access token is needed. The connection still
|
|
160
|
+
requires a `patientId` to form its session ID; generate a random guest ID
|
|
161
|
+
for that — it is **not** a real FHIR patient ID, and the server never
|
|
162
|
+
resolves it against a real patient record for a `requires_auth: false`
|
|
163
|
+
agent.
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
const { public: publicAgents, orchestrator } = await amsSdk.ams.getAgentsForTenant(tenantId);
|
|
167
|
+
|
|
168
|
+
const guestId = crypto.randomUUID();
|
|
169
|
+
const guestChat = amsSdk.connectAgentChat({
|
|
170
|
+
patientId: guestId,
|
|
171
|
+
healthcloudToken: "", // no token needed for a requires_auth: false agent
|
|
172
|
+
agentId: publicAgents[0],
|
|
173
|
+
});
|
|
174
|
+
await guestChat.connect();
|
|
175
|
+
|
|
176
|
+
const guestTurn = await guestChat.sendAndAwaitTurn("What services are available?");
|
|
177
|
+
console.log(guestTurn.message);
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Once the patient signs in, start a **new** connection with the real
|
|
181
|
+
`patientId`/`healthcloudToken` — and pass `handoff` with the guest
|
|
182
|
+
transcript so the orchestrator's first greeting can acknowledge it,
|
|
183
|
+
instead of the conversation starting as if nothing was said:
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
guestChat.close();
|
|
187
|
+
|
|
188
|
+
const login = await patientSdk.auth.login({ email, password });
|
|
189
|
+
|
|
190
|
+
const chat = amsSdk.connectAgentChat({
|
|
191
|
+
patientId: login.fhir_patient_id,
|
|
192
|
+
healthcloudToken: login.access_token,
|
|
193
|
+
agentId: orchestrator[0],
|
|
194
|
+
handoff: [
|
|
195
|
+
{ role: "user", content: "What services are available?" },
|
|
196
|
+
{ role: "assistant", content: guestTurn.message },
|
|
197
|
+
],
|
|
198
|
+
});
|
|
199
|
+
await chat.connect();
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`handoff` is sent once, at connect time — the server reads it before
|
|
203
|
+
generating the first greeting, so the greeting itself can reference the
|
|
204
|
+
handed-off content (e.g. "I see you were asking about X — let's continue
|
|
205
|
+
from there"). It is **not** the same as `sendHandoff(messages)` (a
|
|
206
|
+
post-connect frame kept only for callers on the older contract): that one
|
|
207
|
+
can only silently append to history after the greeting has already gone
|
|
208
|
+
out.
|
|
209
|
+
|
|
107
210
|
On Node < 21 (no global `WebSocket`), pass a compatible implementation:
|
|
108
211
|
|
|
109
212
|
```ts
|
package/dist/index.cjs
CHANGED
|
@@ -661,6 +661,14 @@ var WssClient = class {
|
|
|
661
661
|
const path = options.agentId ? `/ws/agents/${encodeURIComponent(options.agentId)}/chat` : "/ws";
|
|
662
662
|
const url = new URL(`${base}${path}`);
|
|
663
663
|
url.searchParams.set("session_id", sessionId);
|
|
664
|
+
if (options.lang) url.searchParams.set("lang", options.lang);
|
|
665
|
+
if (options.voice) url.searchParams.set("voice", "1");
|
|
666
|
+
if (options.voiceId) url.searchParams.set("voice_id", options.voiceId);
|
|
667
|
+
if (options.audioFormat) url.searchParams.set("audio_format", options.audioFormat);
|
|
668
|
+
if (options.replaySince !== void 0) url.searchParams.set("replay_since", String(options.replaySince));
|
|
669
|
+
if (options.handoff && options.handoff.length > 0) {
|
|
670
|
+
url.searchParams.set("handoff", JSON.stringify(options.handoff));
|
|
671
|
+
}
|
|
664
672
|
this.url = url.toString();
|
|
665
673
|
this.turnTimeoutMs = (_b = options.turnTimeoutMs) != null ? _b : 6e4;
|
|
666
674
|
this.authTimeoutMs = (_c = options.authTimeoutMs) != null ? _c : 1e4;
|
package/dist/index.d.cts
CHANGED
|
@@ -911,6 +911,26 @@ interface WssClientOptions {
|
|
|
911
911
|
turnTimeoutMs?: number;
|
|
912
912
|
/** Timeout (ms) waiting for the server's `auth_ok` after the socket opens and the auth frame is sent. Defaults to 10000, matching the AMS server's own `WS_AUTH_TIMEOUT_SECONDS`. */
|
|
913
913
|
authTimeoutMs?: number;
|
|
914
|
+
/** Greeting language (server defaults to `"en"`). */
|
|
915
|
+
lang?: string;
|
|
916
|
+
/**
|
|
917
|
+
* Carries a prior, unauthenticated conversation's transcript into this
|
|
918
|
+
* (usually now-authenticated) connection, so the greeting can acknowledge
|
|
919
|
+
* it instead of it just silently appearing in history — e.g. a patient
|
|
920
|
+
* chatting with a public, `requires_auth: false` pre-login agent, who
|
|
921
|
+
* then logs in and reconnects to the real orchestrator. Sent once, as
|
|
922
|
+
* part of the connect URL (`?handoff=`), not as a post-open frame — the
|
|
923
|
+
* server reads it before generating the first greeting.
|
|
924
|
+
*/
|
|
925
|
+
handoff?: HandoffFramePayload["messages"];
|
|
926
|
+
/** Starts the session in voice mode (server default: off). */
|
|
927
|
+
voice?: boolean;
|
|
928
|
+
/** Preferred TTS voice ID for the connect-time greeting and voice-mode replies, if voice streaming is enabled for this agent. */
|
|
929
|
+
voiceId?: string;
|
|
930
|
+
/** Audio format for voice replies (server default: `"mp3"`). */
|
|
931
|
+
audioFormat?: string;
|
|
932
|
+
/** Resume support: replays non-audio runtime events with `event_seq` greater than this value after reconnect. */
|
|
933
|
+
replaySince?: number;
|
|
914
934
|
}
|
|
915
935
|
type Listener<K extends WssEventType> = (payload: WssEventMap[K]) => void;
|
|
916
936
|
/**
|
package/dist/index.d.ts
CHANGED
|
@@ -911,6 +911,26 @@ interface WssClientOptions {
|
|
|
911
911
|
turnTimeoutMs?: number;
|
|
912
912
|
/** Timeout (ms) waiting for the server's `auth_ok` after the socket opens and the auth frame is sent. Defaults to 10000, matching the AMS server's own `WS_AUTH_TIMEOUT_SECONDS`. */
|
|
913
913
|
authTimeoutMs?: number;
|
|
914
|
+
/** Greeting language (server defaults to `"en"`). */
|
|
915
|
+
lang?: string;
|
|
916
|
+
/**
|
|
917
|
+
* Carries a prior, unauthenticated conversation's transcript into this
|
|
918
|
+
* (usually now-authenticated) connection, so the greeting can acknowledge
|
|
919
|
+
* it instead of it just silently appearing in history — e.g. a patient
|
|
920
|
+
* chatting with a public, `requires_auth: false` pre-login agent, who
|
|
921
|
+
* then logs in and reconnects to the real orchestrator. Sent once, as
|
|
922
|
+
* part of the connect URL (`?handoff=`), not as a post-open frame — the
|
|
923
|
+
* server reads it before generating the first greeting.
|
|
924
|
+
*/
|
|
925
|
+
handoff?: HandoffFramePayload["messages"];
|
|
926
|
+
/** Starts the session in voice mode (server default: off). */
|
|
927
|
+
voice?: boolean;
|
|
928
|
+
/** Preferred TTS voice ID for the connect-time greeting and voice-mode replies, if voice streaming is enabled for this agent. */
|
|
929
|
+
voiceId?: string;
|
|
930
|
+
/** Audio format for voice replies (server default: `"mp3"`). */
|
|
931
|
+
audioFormat?: string;
|
|
932
|
+
/** Resume support: replays non-audio runtime events with `event_seq` greater than this value after reconnect. */
|
|
933
|
+
replaySince?: number;
|
|
914
934
|
}
|
|
915
935
|
type Listener<K extends WssEventType> = (payload: WssEventMap[K]) => void;
|
|
916
936
|
/**
|
package/dist/index.js
CHANGED
|
@@ -615,6 +615,14 @@ var WssClient = class {
|
|
|
615
615
|
const path = options.agentId ? `/ws/agents/${encodeURIComponent(options.agentId)}/chat` : "/ws";
|
|
616
616
|
const url = new URL(`${base}${path}`);
|
|
617
617
|
url.searchParams.set("session_id", sessionId);
|
|
618
|
+
if (options.lang) url.searchParams.set("lang", options.lang);
|
|
619
|
+
if (options.voice) url.searchParams.set("voice", "1");
|
|
620
|
+
if (options.voiceId) url.searchParams.set("voice_id", options.voiceId);
|
|
621
|
+
if (options.audioFormat) url.searchParams.set("audio_format", options.audioFormat);
|
|
622
|
+
if (options.replaySince !== void 0) url.searchParams.set("replay_since", String(options.replaySince));
|
|
623
|
+
if (options.handoff && options.handoff.length > 0) {
|
|
624
|
+
url.searchParams.set("handoff", JSON.stringify(options.handoff));
|
|
625
|
+
}
|
|
618
626
|
this.url = url.toString();
|
|
619
627
|
this.turnTimeoutMs = (_b = options.turnTimeoutMs) != null ? _b : 6e4;
|
|
620
628
|
this.authTimeoutMs = (_c = options.authTimeoutMs) != null ? _c : 1e4;
|