@healthcloudai/hc-ams 3.5.1 → 3.6.1

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 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;
package/package.json CHANGED
@@ -1,12 +1,15 @@
1
1
  {
2
2
  "name": "@healthcloudai/hc-ams",
3
- "version": "3.5.1",
3
+ "version": "3.6.1",
4
4
  "description": "HealthCloud AMS SDK — application-agent discovery for AMS Services.",
5
5
  "author": "Healthcheck Systems Inc",
6
6
  "license": "MIT",
7
+ "bugs": {
8
+ "url": "https://github.com/healthcloudservices/healthcloud-services/issues"
9
+ },
7
10
  "repository": {
8
11
  "type": "git",
9
- "url": "git+https://github.com/healthcloudservices/healthcloud-sdk.git",
12
+ "url": "git+https://github.com/healthcloudservices/healthcloud-services.git",
10
13
  "directory": "packages/npm-ams"
11
14
  },
12
15
  "keywords": [
@@ -54,5 +57,8 @@
54
57
  "tsx": "^4.23.13",
55
58
  "typescript": "^5.3.0",
56
59
  "vitest": "^5.0.0"
60
+ },
61
+ "overrides": {
62
+ "source-map-js": "^1.2.2"
57
63
  }
58
64
  }