@serenity-star/sdk 2.8.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-star/sdk",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "The Serenity Star JavaScript SDK provides a convenient way to interact with the Serenity Star API, enabling you to build custom applications.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/readme.md

@@ -25,6 +25,8 @@ The Serenity Star JS/TS SDK provides a comprehensive interface for interacting w
     - [Submit feedback](#submit-feedback)
     - [Remove feedback](#remove-feedback)
   - [Connector Status](#connector-status)
+  - [Tool approvals](#tool-approvals)
+  - [User choices](#user-choices)
 - [Activities](#activities)
   - [Execute an activity](#execute-an-activity)
   - [Stream responses with SSE](#stream-responses-with-sse)
@@ -42,6 +44,7 @@ The Serenity Star JS/TS SDK provides a comprehensive interface for interacting w
   - [Task events](#task-events)
   - [Citations](#citations)
     - [Citations on stored messages](#citations-on-stored-messages)
+    - [Downloading a cited knowledge file](#downloading-a-cited-knowledge-file)
   - [Upload Files (Volatile Knowledge)](#upload-files-volatile-knowledge)
   - [Audio Input](#audio-input)
     - [Send Audio Messages (Assistants/Copilots)](#send-audio-messages-assistantscopilots)
@@ -533,6 +536,75 @@ Notes:
   finishes, so an approval raised on the very first turn is resolvable.
 - A resumed turn can itself raise another approval; keep handling `pending_actions` until it is empty.
 
+## User choices
+
+When the agent needs input before it can continue, it stops and asks. The result carries a
+`user_choice` pending action holding one or more questions, each with the options the agent
+proposes.
+
+Detect it on the result (or on the `stop` payload when streaming) and answer with
+`streamUserChoices` / `sendUserChoices`. The resume turn carries **no user message** — the answers
+are the whole turn — and continues the same conversation, so the answer arrives as the rest of the
+same assistant response.
+
+```tsx
+import SerenityClient from '@serenity-star/sdk';
+
+const client = new SerenityClient({
+  apiKey: '<SERENITY_API_KEY>',
+});
+
+const conversation = await client.agents.assistants.createConversation("chef-assistant");
+
+const response = await conversation.streamMessage("Plan dinner for me tonight.");
+
+const choice = response.pending_actions?.find((action) => action.type === "user_choice");
+
+if (choice) {
+  for (const question of choice.questions) {
+    console.log(question.header);        // "Cuisine" — short label, frequently absent
+    console.log(question.text);          // "What kind of food are you in the mood for?"
+    console.log(question.is_multiselect) // false — pick one, or many when true
+    console.log(question.options);       // [{ id, title, description? }, ...]
+  }
+
+  // Ask the user, then echo each question id back with the option ids they picked.
+  const continuation = await conversation.streamUserChoices(
+    choice.questions.map((question) => ({
+      questionId: question.id,
+      selectedOptionIds: [question.options![0].id],
+    })),
+  );
+
+  console.log(continuation.content); // the rest of the answer
+}
+```
+
+When none of the options fit, send the user's own words in `other` instead — with or without
+selected options:
+
+```tsx
+await conversation.sendUserChoices([
+  { questionId: question.id, selectedOptionIds: [], other: "Something vegetarian" },
+]);
+```
+
+Notes:
+
+- `questionId` must match a question's `id`, and every id in `selectedOptionIds` must match one of
+  that question's `options`. `header`, `text` and `description` are informational.
+- Answer members are camelCase (`questionId`, `selectedOptionIds`, `other?`). `other` is optional,
+  trimmed, and omitted from the request when empty.
+- Answer every question in the set. `selectedOptionIds` may be empty only when `other` carries the
+  answer instead.
+- Unlike approvals, nothing is held server-side: the answers are folded into the text of the next
+  user message. An unanswered set never expires, so it can be answered on a later turn, and a plain
+  `sendMessage` / `streamMessage` also works if the user would rather just reply in their own words.
+- User choices can only be answered on an existing conversation — both methods throw when
+  `conversation.conversationId` is not set yet. It is populated as soon as the first execution
+  finishes, so a question raised on the very first turn is answerable.
+- A resumed turn can itself raise another question; keep handling `pending_actions` until it is empty.
+
 ---
 
 # Activities
@@ -1056,6 +1128,8 @@ type CitationSource =
       section_id?: string;
       file_name?: string;
       page_range?: string;
+      is_downloadable?: boolean; // Whether the cited file can be downloaded by authorized users
+      download_url?: string;     // Absolute download endpoint, or absent when not downloadable
     }
   | {
       type: "knowledge_website";
@@ -1104,6 +1178,40 @@ for (const message of conversation.messages) {
 }
 ```
 
+### Downloading a cited knowledge file
+
+When an agent's knowledge file is configured as available for download, its citations carry a
+`download_url` alongside `is_downloadable`. The URL points at the platform's download endpoint but
+**carries no credentials** — a plain `<a href>` will not work. Use `downloadKnowledgeFile` so the
+SDK attaches the client's API key or bearer token:
+
+```tsx
+for (const citation of response.citations ?? []) {
+  const source = citation.source;
+  if (source?.type !== "knowledge_file" || !source.download_url) continue;
+
+  const blob = await conversation.downloadKnowledgeFile(source.download_url);
+
+  // In the browser, hand the blob to the user
+  const objectUrl = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = objectUrl;
+  link.download = source.file_name ?? "download";
+  link.click();
+  URL.revokeObjectURL(objectUrl);
+}
+```
+
+Notes:
+
+- Branch on `download_url` alone. The server derives `is_downloadable` from the URL, so the two
+  can never disagree, and a missing URL already covers non-downloadable files and draft versions.
+- The URL's origin must match the client's `baseUrl`. A mismatch throws before any request is
+  made, so the credential never reaches an origin you did not configure.
+- Private, deleted, or missing files all answer `404` — deliberately indistinguishable.
+- Citations loaded from history via [Get conversation by id](#get-conversation-by-id) do **not**
+  currently include `download_url`.
+
 ## Upload Files (Volatile Knowledge)
 
 Upload files to be used as context in your agent executions. This feature is available for all agent types: **Assistants**, **Copilots**, **Activities**, **Proxies**, and **Chat Completions**. Files are agent-scoped automatically and are included in the next message or execution.