@serenity-star/sdk 2.7.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-star/sdk",
-  "version": "2.7.0",
+  "version": "2.9.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)
@@ -39,6 +41,7 @@ The Serenity Star JS/TS SDK provides a comprehensive interface for interacting w
   - [Download Attached Files](#download-attached-files)
   - [Stop Streaming Response](#stop-streaming-response)
   - [Reasoning (Chain-of-Thought)](#reasoning-chain-of-thought)
+  - [Task events](#task-events)
   - [Citations](#citations)
     - [Citations on stored messages](#citations-on-stored-messages)
   - [Upload Files (Volatile Knowledge)](#upload-files-volatile-knowledge)
@@ -532,6 +535,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
@@ -916,6 +988,83 @@ conversation
 await conversation.streamMessage("Plan a three-course vegetarian dinner");
 ```
 
+## Task events
+
+While an agent streams, it reports the internal work it performs through the `task_start` / `task_stop` event pair. A **task** is any discrete step the agent runs on its way to an answer — a skill execution, a tool call, and whatever step types the platform adds later. The SDK forwards every task frame it receives without filtering, so new task types reach your handlers as soon as the platform starts emitting them.
+
+Use them to reflect the agent's progress in your UI while it works, or to time, trace and log what the agent actually did.
+
+These events only exist on **streamed** executions (`streamMessage` / `stream`). A non-streamed call returns the final result only.
+
+Each task carries a `task_key` identifying what ran and a `metadata` object describing it. Both are task-type specific: match on `task_key` for the types you care about and ignore the rest, rather than assuming a single shape.
+
+```tsx
+import SerenityClient from '@serenity-star/sdk';
+
+const client = new SerenityClient({
+  apiKey: '<SERENITY_API_KEY>',
+});
+
+const conversation = await client.agents.assistants.createConversation("sales-assistant");
+
+conversation
+  .on("task_start", (task) => console.log("started", task.task, task.task_key))
+  .on("task_stop", (task) =>
+    console.log("finished", task.task_key, task.duration, task.success)
+  )
+  .on("content", (chunk) => process.stdout.write(chunk));
+
+await conversation.streamMessage("What do we have in stock for vintage guitars?");
+```
+
+### `task_start` payload
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type` | `string` | The event name, `task_start`. |
+| `task` | `string` | Human-readable description of the task, safe to show in a UI. |
+| `task_key` | `string` | Identifier of what ran. Its format depends on the task type. |
+| `metadata` | `object` | Extra details about the task. Contents depend on the task type. |
+| `start_time_utc` | `string` | When the task started (UTC). |
+| `input` | `object` | The arguments the task was invoked with. Shape depends on the task. |
+
+### `task_stop` payload
+
+Same envelope as `task_start`, plus:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `end_time_utc` | `string` | When the task finished (UTC). |
+| `duration` | `string` | Elapsed time as a timespan string, e.g. `00:00:00.0002104`. |
+| `success` | `boolean` | Whether the task completed successfully. |
+| `output` | `any` | The task's result. Shape depends on the task. |
+
+Unknown fields the server may add in the future are preserved on the payload — both types carry an index signature.
+
+### Recognising a task type
+
+Skill executions are one task type. Their `task_key` follows the `skills_<SkillCode>_execute` convention, and the skill is described under `metadata.skill`:
+
+```json
+{
+  "type": "task_start",
+  "task": "Executing Skill: GetProductInfo",
+  "task_key": "skills_GetProductInfo_execute",
+  "metadata": { "skill": { "type": "Prompt", "code": "GetProductInfo" } },
+  "start_time_utc": "2026-08-24T10:22:54.1822224Z",
+  "input": { "categoryName": "Music instruments from the 1960s" }
+}
+```
+
+```tsx
+conversation.on("task_start", (task) => {
+  const skillCode = task.metadata?.skill?.code;
+  if (skillCode) {
+    showSpinner(`Running ${skillCode}…`);
+  }
+});
+```
+
 ## Citations
 
 When an agent grounds its response in knowledge sources (knowledge files or websites), it returns **citations** that map spans of the generated message back to the source passages they came from. Citations are available across all agent types that support knowledge grounding.