@serenity-star/sdk 2.6.7 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-star/sdk",
-  "version": "2.6.7",
+  "version": "2.8.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

@@ -39,6 +39,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)
@@ -485,6 +486,53 @@ const newResponse = await conversation.sendMessage("I need a summary of my lates
 console.log(newResponse.content); // Summary of the meeting notes
 ```
 
+## Tool approvals
+
+When a skill is configured as *Requires approval*, the run pauses instead of invoking it. The result
+carries an `approval` pending action, and the conversation stays blocked until you send a decision:
+any further message on it returns HTTP 400 with `errors["tool_approval_pending"]`.
+
+Detect the request on the result (or on the `stop` payload when streaming) and resolve it with
+`streamToolApprovals` / `sendToolApprovals`. The resume turn carries **no user message** — the
+decision is 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("What are the trending recipes this week?");
+
+const approval = response.pending_actions?.find((action) => action.type === "approval");
+
+if (approval) {
+  console.log(approval.skill_code); // "web-search" — the skill awaiting approval
+
+  // Ask the user, then echo the request id back with their decision.
+  const continuation = await conversation.streamToolApprovals([
+    { requestId: approval.request_id, approved: true },
+  ]);
+
+  console.log(continuation.content); // the rest of the answer
+}
+```
+
+Notes:
+
+- `request_id` is the only value that must be echoed back. `call_id`, `skill_type`, `tool` and
+  `arguments` are informational.
+- Decision members are camelCase (`requestId`, `approved`, `reason?`). `reason` is optional and
+  omitted from the request when empty.
+- Approvals can only be resolved 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 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.
+
 ---
 
 # Activities
@@ -869,6 +917,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.