@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-coded-apps/references/oauth-client-setup.md

@@ -507,7 +507,7 @@ cd ~/.uipath-skills/playwright && node ./uipath-oauth.mjs \
 
 > **Use the shortest substring that matches both the dropdown label and the attached-list label** as the key (e.g. `"Orchestrator"`, not `"Orchestrator API Access"`). See the [mapping reference](#scope--resource-mapping-reference) for the safe key per resource.
 
-On success, stdout: `{"status":"ok","op":"create","clientId":"<uuid>"}` — write this `clientId` into `.env` as `VITE_UIPATH_CLIENT_ID` (and into `uipath.json`).
+On success, stdout: `{"status":"ok","op":"create","clientId":"<uuid>"}` — write this `clientId` into `uipath.json` as the `clientId` field.
 
 ### Operation: add-redirects
 
@@ -539,7 +539,7 @@ cd ~/.uipath-skills/playwright && node ./uipath-oauth.mjs \
 
 > Use the shortest substring key (e.g. `"Orchestrator"`) — see the [mapping reference](#scope--resource-mapping-reference). Passing the long dropdown label (`"Orchestrator API Access"`) only works when the resource is *not yet attached*; if it's already on the app, the substring won't match the attached-list label (`UiPath.Orchestrator`) and the script will take the wrong code path.
 
-On success, stdout: `{"status":"ok","op":"add-scopes","added":{...}}`. After this, also update `VITE_UIPATH_SCOPE` in `.env` to include the new scopes — both the External App and the env config must list them.
+On success, stdout: `{"status":"ok","op":"add-scopes","added":{...}}`. After this, also update the `scope` field in `uipath.json` to include the new scopes — both the External App and `uipath.json` must list them.
 
 > **Resource label vs scope name:** The keys in `--scopes-by-resource` must match the portal's dropdown labels exactly (e.g. `"Orchestrator API Access"`, `"Maestro API Access"`), not the scope names. The values are the scope names. See the [Scope → Resource Mapping Reference](#scope--resource-mapping-reference) below.
 
@@ -633,7 +633,7 @@ If Playwright automation is not possible (Chrome missing, portal UI changed, scr
 ### Adding Redirect URIs to an Existing App
 
 1. Go to `https://{cloudHost}/{orgName}/portal_/admin/external-apps/oauth`
-2. Paste the first 8 characters of your Client ID (from `.env` → `VITE_UIPATH_CLIENT_ID`) into the search box to filter the list. Use a **prefix**, not the full UUID — the Application ID column is truncated, so full-UUID matching fails. Filtering by Client-ID prefix is also the only reliable disambiguator when multiple apps share the same display name.
+2. Paste the first 8 characters of your Client ID (from `uipath.json` → `clientId`) into the search box to filter the list. Use a **prefix**, not the full UUID — the Application ID column is truncated, so full-UUID matching fails. Filtering by Client-ID prefix is also the only reliable disambiguator when multiple apps share the same display name.
 3. Click the **pencil Edit icon** at the right of the row (clicking the row text itself does not open the edit form)
 4. In the **Redirect URL** field, enter each new URI (with and without trailing slash) and press Enter after each
 5. Click **"Save"**
@@ -649,7 +649,7 @@ If Playwright automation is not possible (Chrome missing, portal UI changed, scr
    - **If the resource is not yet listed**: click **"Add scopes"**, select the resource from the dropdown (see mapping table below), check the required scopes, click the confirm button.
 5. Repeat for each resource category
 6. Click **"Save"** on the app form
-7. **Also update `VITE_UIPATH_SCOPE` in `.env`** to include the new scopes — both sides must match
+7. **Also update the `scope` field in `uipath.json`** to include the new scopes — both sides must match
 8. Clear browser storage and re-test
 
 ### Scope → Resource Mapping Reference
@@ -663,7 +663,7 @@ If Playwright automation is not possible (Chrome missing, portal UI changed, scr
 | `Traces.Api` | **Traces API Access** | varies | `Traces` |
 
 > **Three different label spaces — pick the right one for the right place:**
-> - The **scope** (column 1) is what goes into `VITE_UIPATH_SCOPE` in `.env`.
+> - The **scope** (column 1) is what goes into the `scope` field of `uipath.json`.
 > - The **dropdown label** (column 2) is what you click in the portal's "Add scopes" resource selector.
 > - The **attached-list label** (column 3) is what the portal shows on the row of an *already-attached* resource inside the app's edit view.
 > - The **`--scopes-by-resource` key** (column 4) is what you pass to the script. Use the **shortest substring that matches both the dropdown label and the attached-list label** — that way the script can locate the row whether the resource is being added fresh (matches the dropdown) or already attached (matches the attached-list label). The script also has a first-word fallback if the literal key doesn't match.

package/skills/uipath-coded-apps/references/oauth-scopes.md

@@ -3,12 +3,12 @@
 Required OAuth scopes for each `@uipath/uipath-typescript` SDK service and method.
 
 Use this reference to:
-1. Determine which scopes to include in `VITE_UIPATH_SCOPE` (`.env`)
+1. Determine which scopes to include in the `scope` field of `uipath.json`
 2. Determine which scopes to add to the UiPath External Application
 
 **Note:** Broader scopes cover granular ones (e.g., `OR.Assets` covers `OR.Assets.Read`). Use the most specific scope that satisfies the operations the app performs.
 
-> **Update scopes WHEN you add the feature.** Any new service call — a write op (`insertRecordById`, `updateRecordById`, `deleteRecordById`), an action-causing method (`Jobs.stop`/`resume`/`restart`, `Tasks.complete`/`assign`, `ProcessInstances.cancel`, `Exchanges.createFeedback`, etc.), or a call to a service the app hasn't used before — may need a scope broader than what the current `VITE_UIPATH_SCOPE` in `.env` carries. Check the tables below before shipping the feature. The External Application registration must also allow the scope; if not, the token request is rejected entirely (see [oauth-client-setup.md](oauth-client-setup.md)).
+> **Update scopes WHEN you add the feature.** Any new service call — a write op (`insertRecordById`, `updateRecordById`, `deleteRecordById`), an action-causing method (`Jobs.stop`/`resume`/`restart`, `Tasks.complete`/`assign`, `ProcessInstances.cancel`, `Exchanges.createFeedback`, etc.), or a call to a service the app hasn't used before — may need a scope broader than what the current `scope` field in `uipath.json` carries. Check the tables below before shipping the feature. The External Application registration must also allow the scope; if not, the token request is rejected entirely (see [oauth-client-setup.md](oauth-client-setup.md)).
 
 ---
 
@@ -230,6 +230,66 @@ Combined scopes required: `OR.Execution` · `OR.Folders` · `OR.Jobs` · `Conver
 
 ---
 
+## Widgets
+
+Scopes required by `@uipath/ui-widgets-*` React components. The widget's own runtime API calls are listed here — add scopes from the sections above for any additional SDK calls the host app makes.
+
+### Validation Station (`@uipath/ui-widgets-validation-station`)
+
+| Required Scope | Why |
+|----------------|-----|
+| `OR.Buckets` | Widget reads the document and extraction artifacts from a storage bucket and uploads the validated payload during save. Read-only `OR.Buckets.Read` is insufficient — the upload step requires write. |
+| `OR.Tasks` or `OR.Tasks.Write` | Required when the host app calls `task.complete()` in `onSaveComplete` (action apps, and web apps that complete the task on save). |
+
+See [widgets/validation-station.md](widgets/validation-station.md) for the full integration guide.
+
+> **TODO:** Document scopes for the remaining widgets when their integration guides land in `references/widgets/`:
+> - `@uipath/ui-widgets-conversational-agent-chat`
+> - `@uipath/ui-widgets-datatable`
+> - `@uipath/ui-widgets-multi-file-upload`
+
+---
+
+## Agents — Insights RTM (SDK ≥ 1.4.1)
+
+| Method | Required Scope |
+|--------|----------------|
+| `Agents.getAll()` / `getErrors()` | `Insights` and `Insights.RealTimeData` |
+| `Agents.getErrorsTimeline()` / `getConsumptionTimeline()` / `getLatencyTimeline()` | `Insights` and `Insights.RealTimeData` |
+
+## Agent Traces (SDK ≥ 1.4.1)
+
+| Method | Required Scope |
+|--------|----------------|
+| `AgentTraces.getErrorsTimeline()` / `getLatencyTimeline()` / `getUnitConsumption()` | `Insights` and `Insights.RealTimeData` |
+| `AgentTraces.getSpansByTraceId()` / `getSpansByReference()` | `Insights` and `Insights.RealTimeData` |
+| `Traces.getById()` / `getSpansByIds()` (generic spans — governance traces) | `Traces.Api` (+ `Insights` and `Insights.RealTimeData`) |
+
+## Agent Memory (SDK ≥ 1.4.1)
+
+| Method | Required Scope |
+|--------|----------------|
+| `AgentMemory.getTimeline()` / `getCallsTimeline()` / `getTopSpaces()` | `Insights` and `Insights.RealTimeData` |
+
+## Governance (SDK ≥ 1.4.1)
+
+| Method | Required Scope |
+|--------|----------------|
+| `Governance.getPolicyTraces()` / `getOperationSummary()` | `Insights` and `Insights.RealTimeData` — caller needs elevated (org-admin) access; `fullOrganization: true` returns 403 without org-admin |
+
+## Maestro Insights — RTM (SDK ≥ 1.4.x)
+
+These use the Insights RTM host (`INSIGHTS_RTM_BASE`). The SLA methods also touch PIMS-backed case data and require `PIMS` on top of the Insights scopes.
+
+| Method | Required Scope |
+|--------|----------------|
+| `Cases` / `MaestroProcesses` `.getTopRunCount()` / `getTopFaultedCount()` / `getTopExecutionDuration()` / `getTopElementFailedCount()` / `getInstanceStatusTimeline()` / `getElementStats()` | `Insights` · `Insights.RealTimeData` · `OR.Folders.Read` |
+| `CaseInstances.getSlaSummary()` / `getStagesSlaSummary()` | `Insights` · `Insights.RealTimeData` · `OR.Folders.Read` · **`PIMS`** |
+
+> All Insights RTM methods (Agents, Agent Traces, Agent Memory, Governance, Maestro Insights above) also require `OR.Folders.Read` — covered by the granted `OR.Folders`. `Cases.getAll` / `CaseInstances.getAll` (PIMS host, not Insights) require `PIMS` — see the Maestro sections above.
+
+---
+
 ## Common Scope Bundles
 
 | App uses... | Minimum scopes needed |
@@ -242,3 +302,5 @@ Combined scopes required: `OR.Execution` · `OR.Folders` · `OR.Jobs` · `Conver
 | Maestro full access | `PIMS OR.Execution.Read` |
 | Maestro analytics / insights dashboards (top run/fault/duration counts, status timelines, SLA) | add `Insights.RealTimeData Insights OR.Folders.Read` (SLA summaries also need `PIMS`) |
 | Conversational Agent | `OR.Execution OR.Folders OR.Jobs ConversationalAgents Traces.Api` (add `OR.Users` for user-settings read/write) |
+| Insights RTM (Agents, Agent Traces, Agent Memory, Governance, Maestro Insights) | `Insights Insights.RealTimeData OR.Folders.Read` |
+| Maestro SLA (CaseInstances SLA summary) | `Insights Insights.RealTimeData OR.Folders.Read PIMS` |

package/skills/uipath-coded-apps/references/pack-publish-deploy.md

@@ -123,13 +123,17 @@ uip codedapp publish -n my-webapp --version 1.0.0
 | `Web` | Standard web app accessible via browser URL (default) |
 | `Action` | Action app triggered by UiPath automation workflows |
 
+> **Action apps — always pass `--type Action`.** `publish` defaults to `--type Web`. An action app published without `--type Action` registers as a Web app and will **not** bind to Action Center tasks. Pass `--type Action` on **every** publish of an action app — first deploy and every version update. Never omit it, never rely on the default.
+
 ### What Happens Internally
 
 1. Selects the `.nupkg` file (auto-select, by name, or interactive)
-2. Uploads the package to Orchestrator via the OData API
-3. Registers the coded app with the UiPath Apps service
+2. Uploads the package to Orchestrator via the OData API — needs Orchestrator scopes (`OR.Folders`, `OR.Execution`, `OR.Administration`, or `OR.Default`)
+3. Registers the coded app with the UiPath Apps service — needs `Apps.Read Apps.Write`
 4. Creates `.uipath/app.config.json` with registration metadata
 
+> **Steps 2 and 3 hit different services with different scope requirements.** The `uip login` session `--scope` must cover **both**. If it has only Orchestrator scopes, step 2 succeeds and step 3 silently 401s ("Registering coded app" fails). Interactive `uip login` grants a broad default that includes both; client-credentials logins must list `Apps.Read Apps.Write` explicitly. These are the *CLI session* scopes — separate from the runtime OAuth scopes in `uipath.json`.
+
 ### App Config File
 
 After publish, `.uipath/app.config.json` stores the registration:
@@ -182,7 +186,7 @@ uip codedapp deploy -n my-webapp
 | Option | Description | Default |
 |--------|-------------|---------|
 | `-n, --name <name>` | App name | From `app.config.json` or prompted |
-| `-v, --version <version>` | Target a **specific published version** to deploy (different semantic from `pack`/`publish`'s `-v`, which is the package version) | Latest |
+| `-v, --version <version>` | Target a **specific published version** (different semantic from `pack`/`publish`'s `-v`). **Prefer omitting it** — let it default to Latest. Passing a version that the catalog hasn't finished indexing yields a misleading `"...has not been published yet"` error. | Latest |
 | `--folder-key <key>` | UiPath folder **key** (GUID, not the name). **Always pass explicitly** — see below. | From `UIPATH_FOLDER_KEY` env var, else interactive (avoid) |
 | `--org-name <name>` | Organization name (for app URL) | From `.env` |
 
@@ -306,8 +310,11 @@ uip codedapp deploy
 ### CI/CD Pipeline
 
 ```bash
-# Non-interactive flow with explicit options — every flag passed, no prompts
-uip login --client-id $CLIENT_ID --client-secret $CLIENT_SECRET
+# Non-interactive flow with explicit options — every flag passed, no prompts.
+# --scope MUST include Apps.Read Apps.Write, or publish's "Registering coded app"
+# step 401s even though the package upload succeeds (see publish internals above).
+uip login --client-id $CLIENT_ID --client-secret $CLIENT_SECRET \
+  --scope "OR.Folders OR.Execution OR.Administration Apps.Read Apps.Write"
 npm run build
 uip codedapp pack dist -n my-webapp --version $VERSION
 uip codedapp publish -n my-webapp --version $VERSION

package/skills/uipath-coded-apps/references/patterns.md

@@ -569,7 +569,7 @@ Use these to render any value cleanly — primitives as text, objects/arrays as
 
 ```typescript
 /** Renders a typed value from globalVariables */
-function FormattedValue({ value, type }: { value: any; type: string }) {
+function FormattedValue({ value, type }: { value: unknown; type: string }) {
   if (value === null || value === undefined) {
     return <span className="text-gray-400 italic">—</span>;
   }
@@ -880,7 +880,7 @@ https://cloud.uipath.com/embed_/{orgName}/{tenantName}/actions_/current-task/tas
 
 ### API-to-Cloud URL mapping
 
-**CRITICAL:** The API base URL (`VITE_UIPATH_BASE_URL`) and the cloud UI URL use different hostnames. You must map correctly when constructing task URLs:
+**CRITICAL:** The API base URL (read from the `<meta name="uipath:base-url">` tag) and the cloud UI URL use different hostnames. You must map correctly when constructing task URLs:
 
 | API URL | Cloud UI URL |
 |---------|-------------|
@@ -929,11 +929,16 @@ export const getEmbedTaskUrl = (taskUrl: string): string => {
   }
 };
 
+/** Reads a value from a <meta name="uipath:*"> tag injected at runtime. */
+function readUipathMeta(key: string): string {
+  return document.querySelector(`meta[name="uipath:${key}"]`)?.getAttribute('content') ?? '';
+}
+
 /** Constructs a standard Action Center task URL from components */
 export function buildTaskUrl(taskId: number | string): string {
-  const baseUrl = import.meta.env.VITE_UIPATH_BASE_URL || '';
-  const org = import.meta.env.VITE_UIPATH_ORG_NAME || '';
-  const tenant = import.meta.env.VITE_UIPATH_TENANT_NAME || '';
+  const baseUrl = readUipathMeta('base-url');
+  const org = readUipathMeta('org-name');
+  const tenant = readUipathMeta('tenant-name');
   const cloudHost = apiToCloudUrl(baseUrl);
   return `${cloudHost}/${org}/${tenant}/actions_/current-task/tasks/${taskId}`;
 }

package/skills/uipath-coded-apps/references/sdk/action-center.md

@@ -42,7 +42,7 @@ import type {
 
 ```typescript
 import {
-  TaskType,          // Form = 'FormTask', External = 'ExternalTask', App = 'AppTask'
+  TaskType,          // Form, External, App, DocumentValidation, DocumentClassification, DataLabeling
   TaskPriority,      // Low, Medium, High, Critical
   TaskStatus,        // Unassigned, Pending, Completed
   TaskSlaStatus,     // OverdueLater, OverdueSoon, Overdue, CompletedInTime
@@ -52,6 +52,17 @@ import {
 } from '@uipath/uipath-typescript/tasks';
 ```
 
+`TaskType` string values:
+
+| Member | API string | Notes |
+|--------|------------|-------|
+| `TaskType.Form` | `'FormTask'` | Renders a UiPath form layout |
+| `TaskType.External` | `'ExternalTask'` | Externally managed task |
+| `TaskType.App` | `'AppTask'` | Powered by a UiPath App |
+| `TaskType.DocumentValidation` | `'DocumentValidationTask'` | DU validation — owned by the Validation Station widget. See [../widgets/validation-station.md](../widgets/validation-station.md) |
+| `TaskType.DocumentClassification` | `'DocumentClassificationTask'` | DU classification task |
+| `TaskType.DataLabeling` | `'DataLabelingTask'` | Training-data annotation task |
+
 ## Tasks Service
 
 ### create(options: TaskCreateOptions, folderId: number)
@@ -66,9 +77,18 @@ Returns `NonPaginatedResponse<TaskGetResponse>` or `PaginatedResponse<TaskGetRes
 
 ### getById(id: number, options?: TaskGetByIdOptions, folderId?: number)
 
-Returns `Promise<TaskGetResponse>` with attached methods. For form tasks, `folderId` is required.
+Returns `Promise<TaskGetResponse>` with attached methods.
+
+`TaskGetByIdOptions.taskType` is an optimization. Without it, the SDK issues a generic GET, inspects `type`, then issues a second type-specific GET. With it, the SDK skips the discovery call and goes straight to the type-specific endpoint — **`folderId` then becomes required** (throws `ValidationError` otherwise). Use for any non-`External` task when you already know the type:
+
+```typescript
+// Faster — single round-trip. Required pattern for Validation Station hydration.
+const dvTask = await tasks.getById(taskId, { taskType: TaskType.DocumentValidation }, folderId);
+```
 
-`TaskGetResponse` key fields: `id`, `title`, `status`, `type`, `priority`, `folderId`, `key`, `data`, `isDeleted`, `isCompleted`, `createdTime`, `assignedToUser`, `formLayout` (for form tasks), `taskAssignments`, `activities`, `tags`, `taskSource`, `parentOperationId`, `externalTag`.
+For `TaskType.Form`, the SDK auto-adds `expandOnFormLayout: true` so `formLayout` is populated.
+
+`TaskGetResponse` key fields: `id`, `title`, `status`, `type`, `priority`, `folderId`, `key`, `data`, `isDeleted`, `isCompleted`, `createdTime`, `assignedToUser`, `formLayout` (form tasks), `taskAssignments`, `activities`, `tags`, `taskSource`, `parentOperationId`, `externalTag`.
 
 **OData filtering:** `TaskGetAllOptions` supports `filter` (OData `$filter` string) and `orderby` for server-side filtering and sorting. Examples:
 - Pending tasks only: `filter: "Status ne 'Completed'"`
@@ -95,9 +115,10 @@ Returns `Promise<OperationResponse<{ taskId: number }[] | TaskAssignmentResponse
 
 Returns `Promise<OperationResponse<TaskCompletionOptions>>`. The `folderId` is required.
 
-`TaskCompletionOptions` is a discriminated union:
-- For `TaskType.External`: `{ type: TaskType.External, taskId: number, data?: any, action?: string }`
-- For other types: `{ type: TaskType.Form | TaskType.App, taskId: number, data: any, action: string }`
+`TaskCompletionOptions` is a discriminated union on `type`:
+- `External`, `DocumentValidation`, `DocumentClassification`, `DataLabeling`: `{ type, taskId, data?, action? }` — both `data` and `action` optional. Routes to the generic complete endpoint.
+- `Form`: `{ type: TaskType.Form, taskId, data, action }` — both required. Routes to the form-task endpoint.
+- `App`: `{ type: TaskType.App, taskId, data, action }` — both required. Routes to the app-task endpoint.
 
 ## Task-Attached Methods (TaskMethods)
 
@@ -173,11 +194,16 @@ The `type` field determines which other fields are required:
 | Task Type | `data` | `action` | Example |
 |-----------|--------|----------|---------|
 | `TaskType.External` | Optional | Optional | `{ type: TaskType.External, action: 'Approve' }` |
+| `TaskType.DocumentValidation` | Optional | Optional | `{ type: TaskType.DocumentValidation, action: 'Completed' }` |
+| `TaskType.DocumentClassification` | Optional | Optional | `{ type: TaskType.DocumentClassification, action: 'Completed' }` |
+| `TaskType.DataLabeling` | Optional | Optional | `{ type: TaskType.DataLabeling, action: 'Completed' }` |
 | `TaskType.Form` | **Required** | **Required** | `{ type: TaskType.Form, action: 'Submit', data: formData }` |
 | `TaskType.App` | **Required** | **Required** | `{ type: TaskType.App, action: 'Approve', data: {} }` |
 
 For Maestro HITL tasks (approve/reject flows), tasks are typically `TaskType.App` or `TaskType.External`. Pass `data: {}` (empty object) for App tasks when there's no form data to submit.
 
+For `TaskType.DocumentValidation`, the Validation Station widget owns the data contract — call `task.complete({ type: TaskType.DocumentValidation, action: 'Completed' })` from `onSaveComplete`. Do NOT pass `data` yourself; the widget already uploaded the validated payload to the bucket before firing the callback. See [../widgets/validation-station.md](../widgets/validation-station.md).
+
 ### Action strings
 
 The `action` parameter is a free-form string that maps to the workflow's expected action. Common patterns:

package/skills/uipath-coded-apps/references/sdk/agents.md

@@ -0,0 +1,241 @@
+# Agents & Agent Memory (Insights RTM) Reference
+
+> Requires `@uipath/uipath-typescript` **≥ 1.4.1**. Scopes: `Insights Insights.RealTimeData`.
+
+Two services, **two different calling conventions** — do not mix them up:
+
+| Service | Subpath | Convention |
+|---------|---------|------------|
+| `Agents` | `@uipath/uipath-typescript/agents` | **Positional `Date` args**: `getAll(startTime, endTime, options?)` |
+| `AgentMemory` | `@uipath/uipath-typescript/agent-memory` | **Options object**: `getTimeline({ startTime?, endTime?, ... })` — dates inside the object |
+
+## Agents Service
+
+```typescript
+import { Agents, AgentListSortColumn } from '@uipath/uipath-typescript/agents';
+const agents = new Agents(sdk)
+```
+
+### getAll(startTime: Date, endTime: Date, options?: AgentListOptions)
+
+The agent list with consumption + health metadata aggregated over the window. Returns `NonPaginatedResponse<AgentListItem>` (or `PaginatedResponse` with pagination options). **Rows are on `.items`.**
+
+`AgentListOptions`: `folderKeys?: string[]`, `agentNames?: string[]`, `projectKeys?: string[]`, `agentId?: string`, `processVersion?: string`, `orderBy?: { column: AgentListSortColumn, desc?: boolean }` + pagination (`pageSize`, `cursor`, `jumpToPage`).
+
+`AgentListSortColumn`: `AgentName`, `ParentProcess`, `LastRun`, `HealthScore`, `LastIncident`, `FolderName`, `QuantityAGU`, `QuantityPLTU`, `FolderPath`.
+
+`AgentListItem` fields: `agentId`, `agentName`, `parentProcess`, `folderKey`, `folderName`, `folderPath`, `lastRun`, `processKey`, `processVersion`, `healthScore` (0–100), `lastIncidentType`, `unitsQuantity`, `unitsName`, `quantityAGU`, `quantityPLTU`. Nullable: `parentProcess`, `folderKey/Name/Path`, `processKey`, `processVersion`, `lastIncidentType`, `unitsName` (may be `null` or `""`).
+
+**Example response** (`.items` — field names exact, values illustrative):
+
+```json
+{
+  "items": [
+    {
+      "agentId": "ag-0001", "agentName": "InvoiceTriageAgent",
+      "parentProcess": "InvoiceFlow", "folderKey": "f-1001", "folderName": "Finance",
+      "folderPath": "Finance", "lastRun": "2026-06-10T18:22:00Z",
+      "processKey": "p-0088", "processVersion": "1.2.0",
+      "healthScore": 92, "lastIncidentType": null,
+      "unitsQuantity": 340, "unitsName": "AGU", "quantityAGU": 340, "quantityPLTU": 0
+    },
+    {
+      "agentId": "ag-0002", "agentName": "ContractReviewAgent",
+      "parentProcess": null, "folderKey": "f-1001", "folderName": "Finance",
+      "folderPath": "Finance", "lastRun": "2026-06-10T16:05:00Z",
+      "processKey": null, "processVersion": null,
+      "healthScore": 58, "lastIncidentType": "Error",
+      "unitsQuantity": 1210, "unitsName": "AGU", "quantityAGU": 1210, "quantityPLTU": 12
+    }
+  ],
+  "count": 2
+}
+```
+
+> **Semantics:** `getAll` returns per-agent totals (`quantityAGU`, `healthScore`, `lastIncidentType`) — good for KPIs and ranked tables. For *time-series* (error / latency / consumption trends) use the dedicated timeline methods below — all added in SDK 1.4.1. There is still **no invocation-count timeline** and **no per-percentile method other than `getLatencyTimeline`**.
+
+### getErrors(startTime: Date, endTime: Date, options?: AgentGetErrorsOptions)
+
+Agent error classes (incidents) observed in the window, ranked. Returns `NonPaginatedResponse<AgentError>` (or `PaginatedResponse` with pagination options). **Rows are on `.items`.**
+
+`AgentGetErrorsOptions`: filters (`folderKeys`, `agentNames`, `projectKeys`, `agentId`, `processVersion`) + `orderBy?: { column: AgentErrorSortColumn, desc?: boolean }` + pagination. `AgentErrorSortColumn`: `ExecutionCount`, `ErrorTitle`, `Type`, … (import from `@uipath/uipath-typescript/agents`).
+
+`AgentError` fields: `type`, `description`, `agentId`, `agentName`, `jobKey`, `parentProcess`, `firstSeen`, `folderKey`, `folderName`, `folderPath`, `count`, `firstSeenJob`, `lastSeenJob`.
+
+```json
+{ "items": [
+  { "type": "ToolError", "description": "Tool 'search' timed out", "agentId": "ag-0002", "agentName": "ContractReviewAgent", "count": 14, "firstSeen": "2026-06-02T09:11:00Z", "folderName": "Finance" }
+], "count": 1 }
+```
+
+### getErrorsTimeline(startTime: Date, endTime: Date, options?)
+
+Time-series of error counts grouped by agent. Returns a **bare array** `[{ name, value, date }]` — `name` is the agent name, `value` the error count, `date` the bucket. Options: filters + `limit?` (top-N agents, default 10).
+
+```json
+[ { "name": "ContractReviewAgent", "value": 6, "date": "2026-06-02" },
+  { "name": "InvoiceTriageAgent", "value": 1, "date": "2026-06-02" } ]
+```
+
+### getConsumptionTimeline(startTime: Date, endTime: Date, options?)
+
+Time-series of AGU consumption. Returns a **bare array** `[{ timeSlice, aguConsumption }]` — native chart shape. Options: filters.
+
+```json
+[ { "timeSlice": "2026-06-01T00:00:00Z", "aguConsumption": 120 },
+  { "timeSlice": "2026-06-02T00:00:00Z", "aguConsumption": 340 } ]
+```
+
+### getLatencyTimeline(startTime: Date, endTime: Date, options?)
+
+Time-series of agent latency per percentile. Returns a **bare array** `[{ name, value, date }]` — `name` is the percentile (`"P50"` / `"P95"`), `value` is **milliseconds**, `date` the bucket. Options: filters.
+
+```json
+[ { "name": "P50", "value": 820, "date": "2026-06-02" },
+  { "name": "P95", "value": 2400, "date": "2026-06-02" } ]
+```
+
+> **Convention:** all four timeline methods take **positional `Date` args** (`start, end`) like `getAll` — NOT an options object. Filters go in the optional third arg. Contrast with `AgentMemory` (options object) and `AgentTraces` (options object). For trace-level error/latency/consumption, see `sdk/traces.md`.
+
+### Insights aggregates (SDK ≥ 1.5.0)
+
+Purpose-built aggregate endpoints — all **positional `Date` args** `(startTime, endTime, options?)`, same as `getAll`. Prefer these over hand-rolling aggregates from `getAll`.
+
+| Method | Returns | Use for |
+|---|---|---|
+| `getTopErrorCount(start, end, { limit?, folderKeys? })` | `{ totalErrors, data: [{ name, count, agentId, … }] }` | Agents ranked by error count (`agents-by-errors`) |
+| `getTopConsumption(start, end, { limit?, healthy?, agentTypes? })` | `{ totalConsumed, totalAGUConsumed, …, agents: [{ agentName, consumedQuantity, consumedAGUQuantity, consumedPLTUQuantity }] }` | Agents ranked by consumption (`agent-consumption`) |
+| `getIncidentDistribution(start, end, { folderKeys? })` | `{ errorCount, escalationCount, policyCount }` | Incident breakdown donut (`agent-incident-distribution`) |
+| `getSummary(start, end, { lookbackPeriodAnalysis?, executionType?, … })` | `{ currentPeriodSummary: { totalJobs, successfulJobs, successRate, averageDurationSeconds, agents:[…] }, lookbackPeriodSummary? }` | Success-rate / job-volume KPIs with vs-previous delta (`agent-success-rate`) |
+| `getUnitConsumptionSummary(start, end, { lookbackPeriodAnalysis?, … })` | `{ currentPeriodSummary: { totalAgentUnitConsumption: { completeJobs, incompleteJobs }, totalPlatformUnitConsumption: {…} }, lookbackPeriodSummary? }` | Aggregate AGU/PLTU KPI with delta (`agent-unit-consumption-summary`) |
+
+> **Delta from one call.** `getSummary` / `getUnitConsumptionSummary` with `{ lookbackPeriodAnalysis: true }` return the prior equal-length window as `lookbackPeriodSummary` — feed it straight into a kpi-card's `previous`. No second call, no `priorWindow()`.
+> **`executionType`** (`AgentExecutionType.Runtime` / `.Debug`) and **`agentTypes`** (`AgentType.Autonomous | .Conversational | .Coded`) are enums exported from `@uipath/uipath-typescript/agents`.
+
+### fnBody patterns
+
+```typescript
+// Count of active agents (kpi-card)
+const { Agents } = await import('@uipath/uipath-typescript/agents')
+const result = await new Agents(sdk).getAll(THIRTY_DAYS_AGO, NOW)
+return [{ count: result?.items?.length ?? 0 }]
+```
+
+```typescript
+// Agents ranked by AGU consumption (ranked-table)
+const { Agents, AgentListSortColumn } = await import('@uipath/uipath-typescript/agents')
+const result = await new Agents(sdk).getAll(THIRTY_DAYS_AGO, NOW, {
+  orderBy: { column: AgentListSortColumn.QuantityAGU, desc: true },
+})
+return (result?.items ?? []).map(agent => ({ ...agent }))
+```
+
+```typescript
+// Agent errors over time — total across agents (area-chart: xKey date, yKey value)
+const { Agents } = await import('@uipath/uipath-typescript/agents')
+const points = await new Agents(sdk).getErrorsTimeline(THIRTY_DAYS_AGO, NOW)
+const byDate: Record<string, number> = {}
+for (const point of points) byDate[point.date] = (byDate[point.date] ?? 0) + point.value
+return Object.entries(byDate).sort().map(([date, value]) => ({ date, value }))
+```
+
+```typescript
+// Agent latency P50/P95 over time — pivot long→wide (multi-line-chart: xKey date, series P50/P95)
+const { Agents } = await import('@uipath/uipath-typescript/agents')
+const points = await new Agents(sdk).getLatencyTimeline(THIRTY_DAYS_AGO, NOW)
+const byDate: Record<string, Record<string, unknown>> = {}
+for (const point of points) {
+  byDate[point.date] = byDate[point.date] ?? { date: point.date }
+  byDate[point.date][point.name] = point.value
+}
+return Object.values(byDate).sort((a, b) => String(a.date).localeCompare(String(b.date)))
+```
+
+```typescript
+// AGU consumption over time (area-chart: xKey timeSlice, yKey aguConsumption)
+const { Agents } = await import('@uipath/uipath-typescript/agents')
+const series = await new Agents(sdk).getConsumptionTimeline(THIRTY_DAYS_AGO, NOW)
+return series.map(point => ({ ...point }))
+```
+
+```typescript
+// Top agent errors ranked by occurrence (ranked-table)
+const { Agents, AgentErrorSortColumn } = await import('@uipath/uipath-typescript/agents')
+const result = await new Agents(sdk).getErrors(THIRTY_DAYS_AGO, NOW, {
+  orderBy: { column: AgentErrorSortColumn.ExecutionCount, desc: true },
+})
+return (result?.items ?? []).map(agent => ({ ...agent }))
+```
+
+```typescript
+// Agents ranked by error count (ranked-table) — ≥ 1.5.0
+const { Agents } = await import('@uipath/uipath-typescript/agents')
+const result = await new Agents(sdk).getTopErrorCount(THIRTY_DAYS_AGO, NOW, { limit: 10 })
+return result.data.map(agent => ({ name: agent.name, value: agent.count }))
+```
+
+```typescript
+// Agents ranked by consumption (ranked-table) — ≥ 1.5.0
+const { Agents } = await import('@uipath/uipath-typescript/agents')
+return (await new Agents(sdk).getTopConsumption(THIRTY_DAYS_AGO, NOW, { limit: 10 })).agents.map(agent => ({ ...agent }))
+```
+
+```typescript
+// Incident distribution (donut) — ≥ 1.5.0: flat response → chart rows
+const { Agents } = await import('@uipath/uipath-typescript/agents')
+const distribution = await new Agents(sdk).getIncidentDistribution(THIRTY_DAYS_AGO, NOW)
+return [
+  { name: 'Errors', value: distribution.errorCount },
+  { name: 'Escalations', value: distribution.escalationCount },
+  { name: 'Policy', value: distribution.policyCount },
+]
+```
+
+```typescript
+// Success-rate KPI with vs-previous delta (kpi-card) — ≥ 1.5.0
+const { Agents } = await import('@uipath/uipath-typescript/agents')
+const summary = await new Agents(sdk).getSummary(THIRTY_DAYS_AGO, NOW, { lookbackPeriodAnalysis: true })
+return [{ value: summary.currentPeriodSummary.successRate, previous: summary.lookbackPeriodSummary?.successRate }]
+```
+
+```typescript
+// Total Agent Units consumed, with delta (kpi-card) — ≥ 1.5.0
+const { Agents } = await import('@uipath/uipath-typescript/agents')
+const summary = await new Agents(sdk).getUnitConsumptionSummary(THIRTY_DAYS_AGO, NOW, { lookbackPeriodAnalysis: true })
+const current = summary.currentPeriodSummary.totalAgentUnitConsumption
+const prior = summary.lookbackPeriodSummary?.totalAgentUnitConsumption
+return [{ value: current.completeJobs + current.incompleteJobs, previous: prior ? prior.completeJobs + prior.incompleteJobs : undefined }]
+```
+
+## AgentMemory Service
+
+```typescript
+import { AgentMemory, AgentMemoryExecutionType } from '@uipath/uipath-typescript/agent-memory';
+const memory = new AgentMemory(sdk)
+```
+
+All three methods take ONE optional options object — `{ startTime?: Date, endTime?: Date, agentId?, agentVersion?, folderKeys?, executionType? }` (`AgentMemoryExecutionType.Debug | Runtime`; omit for both). Window defaults to the **last 24 hours**. All three return a **bare array** — no `.items` / `.data` unwrapping needed.
+
+| Method | Returns (bare array of) | Use for |
+|--------|------------------------|---------|
+| `getTimeline(options?)` | `{ timeSlice, inMemoryCount, notInMemoryCount, totalCount, enabledMemoryCount, disabledMemoryCount }` | Memory state over time (line/area chart) |
+| `getCallsTimeline(options?)` | `{ timeSlice, memoryCallsCount }` | Memory access volume over time |
+| `getTopSpaces(options?)` | `{ memorySpaceId, memorySpaceName, memoryCount, enabledMemoryCount, disabledMemoryCount }` | Top memory spaces (ranked; `limit?` option, default 5) |
+
+**Example response** — `getTimeline()` (values from SDK test fixtures):
+
+```json
+[
+  { "timeSlice": "2026-06-10T00:00:00Z", "inMemoryCount": 3, "notInMemoryCount": 1, "totalCount": 4, "enabledMemoryCount": 2, "disabledMemoryCount": 2 },
+  { "timeSlice": "2026-06-10T01:00:00Z", "inMemoryCount": 5, "notInMemoryCount": 0, "totalCount": 5, "enabledMemoryCount": 5, "disabledMemoryCount": 0 }
+]
+```
+
+### fnBody pattern
+
+```typescript
+// Memory calls over the last 7 days (area-chart: xKey timeSlice, yKey memoryCallsCount)
+const { AgentMemory } = await import('@uipath/uipath-typescript/agent-memory')
+const series = await new AgentMemory(sdk).getCallsTimeline({ startTime: SEVEN_DAYS_AGO, endTime: NOW })
+return series.map(point => ({ ...point }))
+```