@healthcloudai/hc-ams 0.0.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 CHANGED
@@ -1,6 +1,8 @@
1
1
  # HealthCloud AMS SDK for NodeJS / TypeScript
2
2
 
3
- Typed access to AMS Services' public application-agent discovery endpoint.
3
+ Typed access to AMS Services: agent/department/team/skill/policy/guardrail
4
+ CRUD, the data-source and tool catalogs, synthetic test-patient personas,
5
+ conversation history, and the real-time WebSocket agent-chat runtime.
4
6
 
5
7
  ## Installation
6
8
 
@@ -23,16 +25,211 @@ const agents = await sdk.ams.getAgentsForTenant("<TENANT_ID>");
23
25
 
24
26
  `ams.getAgentsForTenant` is public and requires no access token.
25
27
 
28
+ Every other REST client (`agents`, `departments`, `teams`, `skills`,
29
+ `policies`, `guardrails`, `dataSources`, `tools`, `testPersonas`) requires a
30
+ **Tenant Admin** Bearer token, set via `accessToken` in the constructor or
31
+ `sdk.setAccessToken(token)`. This SDK does not obtain that token itself —
32
+ get one from AMS's own `sdk.auth.login(...)` or from
33
+ `@healthcloudai/hc-tenantadmin`, and pass it in.
34
+
35
+ The WebSocket runtime (`sdk.connectAgentChat(...)` / `WssClient`) is
36
+ authenticated with a **patient** Health Cloud access token instead — obtain
37
+ one via `sdk.testPersonas.login(credentialId)` for testing, or from your
38
+ own patient auth flow in production.
39
+
40
+ ## REST clients
41
+
42
+ | Client | Resource | Notes |
43
+ | --- | --- | --- |
44
+ | `sdk.ams` | Public application-agent discovery | No auth required |
45
+ | `sdk.agents` | Agent CRUD, transfer candidates, conversation history | `create`/`update`/`delete` may 405 if the tenant has `disable_direct_agent_mutations` enabled (see below) |
46
+ | `sdk.departments` | Department CRUD + activate/deactivate | |
47
+ | `sdk.teams` | Team CRUD | |
48
+ | `sdk.skills` | Skill CRUD | |
49
+ | `sdk.policies` | Policy CRUD | |
50
+ | `sdk.guardrails` | Guardrail CRUD | |
51
+ | `sdk.dataSources` | Data source catalog | Read-only — AMS exposes no create/update/delete |
52
+ | `sdk.tools` | Tool catalog | Read-only — AMS exposes no create/update/delete |
53
+ | `sdk.testPersonas` | Synthetic QA patient persona CRUD + login | `login()` mints a real Health Cloud patient token |
54
+ | `sdk.auth` | AMS's own Tenant Admin auth proxy (`/api/auth/*`) | Resolves against a different base path than every other client |
55
+
56
+ ```ts
57
+ const sdk = new HCAmsSDK({ environment: "dev", accessToken: tenantAdminToken });
58
+
59
+ const department = await sdk.departments.create({ name: "Cardiology", created_by_user_id: "admin-1" });
60
+ const agent = await sdk.agents.create({ name: "Cardiology Intake", department_id: department.id });
61
+ const history = await sdk.agents.getConversation(agent.id, `${tenantId}/${patientId}`);
62
+ ```
63
+
64
+ ### Direct agent mutation
65
+
66
+ Some tenants run with `disable_direct_agent_mutations` enabled, in which
67
+ case AMS's plain `POST/PUT/DELETE /agents` routes respond 405 and real agent
68
+ authoring happens through the Vibe Coder plan/apply flow instead. That flow
69
+ is intentionally out of scope for this SDK — `sdk.agents.create/update/delete`
70
+ only cover the plain-CRUD path.
71
+
72
+ ## WebSocket agent-chat runtime
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
+
86
+ ```ts
87
+ const sdk = new HCAmsSDK({ environment: "dev", tenantId: "<TENANT_ID>", accessToken: tenantAdminToken });
88
+
89
+ // Mint a patient token for a synthetic test persona.
90
+ const session = await sdk.testPersonas.login(personaCredentialId);
91
+
92
+ // Connect and hold a multi-turn conversation with one agent.
93
+ const chat = sdk.connectAgentChat({
94
+ patientId: session.patient_id,
95
+ healthcloudToken: session.access_token,
96
+ agentId: "<AGENT_ID>", // omit to use the tenant's default agent
97
+ });
98
+ await chat.connect();
99
+
100
+ const turn = await chat.sendAndAwaitTurn("Hi, I'd like to schedule a check-up.");
101
+ console.log(turn.message, turn.transfers, turn.artifacts, turn.notifications, turn.activity);
102
+
103
+ chat.close();
104
+ ```
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
+
130
+ `WssClient` also exposes raw typed event subscription for finer-grained
131
+ control:
132
+
133
+ ```ts
134
+ chat.on("turn_started", (e) => console.log("turn started", e.turn_id));
135
+ chat.on("chat", (e) => process.stdout.write(e.content));
136
+ chat.on("transfer", (e) => console.log("agent switched", e.to_agent_id));
137
+ ```
138
+
139
+ The entire multi-agent conversation (orchestrator plus any number of
140
+ downstream specialist agents) lives on this **one** WebSocket connection —
141
+ agent switches arrive as `transfer` events, not reconnects.
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
+
210
+ On Node < 21 (no global `WebSocket`), pass a compatible implementation:
211
+
212
+ ```ts
213
+ import WebSocket from "ws";
214
+
215
+ const chat = sdk.connectAgentChat({
216
+ patientId,
217
+ healthcloudToken,
218
+ WebSocketImpl: WebSocket as any,
219
+ });
220
+ ```
221
+
222
+ See [`TEST_LIST.md`](./TEST_LIST.md) for a full end-to-end flow: creating a
223
+ department/team/agents/test-persona, logging in as the persona, and
224
+ validating a multi-turn conversation's turns, transfers, artifacts,
225
+ notifications, and activity.
226
+
26
227
  ## Configuration
27
228
 
28
229
  | Option | Description |
29
230
  | --- | --- |
30
231
  | `environment` | `"dev"` \| `"uat"` \| `"prod"` — resolves the AMS base URL (`{env-}amsservices.health.cloud/api/ams`, no prefix for `prod`). |
31
- | `tenantId` | Optional default tenant ID for future methods. |
32
- | `accessToken` | Optional bearer token for future authenticated methods. |
232
+ | `tenantId` | Optional default tenant ID, used by `connectAgentChat` when no `tenantId` is passed per-call. |
233
+ | `accessToken` | Optional Tenant Admin bearer token for authenticated REST methods. |
33
234
  | `baseUrlOverride` | Overrides the resolved AMS base URL (e.g. for local/staging testing). |
34
235
  | `timeout` | Request timeout in milliseconds. Defaults to 30000. |
35
-
36
- ## Scope
37
-
38
- This is an initial, minimal package: it currently ships only `AmsClient.getAgentsForTenant`. Real-time (WebSocket) agent endpoints are intentionally out of scope for this release.