@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-coded-apps/references/sdk/governance-traces.md

@@ -0,0 +1,186 @@
+# Agent Governance Decisions (Insights RTM)
+
+> Requires `@uipath/uipath-typescript` **≥ 1.5.1**. Scopes: `Insights Insights.RealTimeData OR.Folders.Read` (all in `DASHBOARD_SCOPES`). Subpath: `@uipath/uipath-typescript/traces` (the `AgentTraces` service).
+> **Org-admin required.** Both methods 403 for non-admin callers (SDK throws `AuthorizationError`). On 403: tell the user their account lacks governance access, render the widget's EmptyState, build the rest of the dashboard. Do not retry.
+
+First-class Insights endpoints for **agentic runtime governance** — every policy check an agent run went through (allow/deny per hook) plus an aggregated posture summary. These widgets honor the dashboard time range like any other metric.
+
+> **GATE — propose these ONLY on an EXPLICIT runtime-compliance signal:** a standard/pack reference
+> ("standard(s)", "pack", `ISO` + clause e.g. `ISO 42001` / `A.8.4`, or a named pack), an explicit **rule/policy
+> violation** ask ("rule(s) violated/fired", "runtime violations"), or runtime-governance terms ("runtime
+> compliance/governance", hook names, `enforce`/`audit` mode). Generic "governance / policy / denials / blocked
+> actions / allow-deny / enforcement" routes to `policy-denials` / `governance-verdicts` (`sdk/governance.md`) —
+> a different domain (platform policy enforcement). When unsure which the user means, ASK. Never add these
+> widgets to a plain agent-health/ops dashboard.
+
+```typescript
+import { AgentTraces, AgentGovernanceVerdict, AgentGovernanceSection } from '@uipath/uipath-typescript/traces'
+const svc = new AgentTraces(sdk)
+```
+
+Both methods take a **required positional `startTime: Date`** first (same convention as `Governance.getPolicyTraces`); everything else lives in options.
+
+## getGovernanceSummary(startTime, options?) — breakdowns in ONE call
+
+Returns a **single object — not an array**. Options: `{ endTime?, topN?, packName?, sections? }`.
+
+**Example response** (grounded in SDK test fixtures):
+
+```json
+{
+  "total": 26, "violations": 3,
+  "byHook":   [{ "key": "BEFORE_MODEL", "name": null, "count": 12, "violationCount": 2 }],
+  "byAgent":  [{ "key": "af12…", "name": "customer-care-assistant-for-acmecare", "count": 20, "violationCount": 1 }],
+  "byPolicy": [{ "key": "ISO42001-guardrail-prompt-injection", "name": "AI system impact assessment", "count": 2, "violationCount": 0 }],
+  "byPack":   [{ "key": "ISO/IEC 42001:2023 Runtime", "name": null, "count": 26, "violationCount": 3 }],
+  "byAction": [], "byMode": []
+}
+```
+
+Semantics:
+- `violations` / `violationCount` = **Deny verdicts**; `count`/`total` = all checks. Violation widgets read `violationCount`; all-checks widgets read `count`.
+- **`byAction` and `byMode` are EMPTY unless opted in** via `sections: [AgentGovernanceSection.Action]` / `[…Mode]`. Forgetting `sections` is the compiles-green-renders-empty trap here.
+- `name` is populated for `byPolicy`/`byAgent`; render `name ?? key`.
+- `topN` caps each breakdown; `packName` scopes totals + breakdowns to one pack.
+
+## getGovernanceDecisions(startTime, options?) — the record grain
+
+One row per policy check. Paginated; rows on `.items`. Options: `{ endTime?, hook?, evaluatorResult?, policyId?, agentId?, violationsOnly?, pageSize?, cursor? }`.
+
+**Example response** (`.items` — grounded in SDK test fixtures):
+
+```json
+{
+  "items": [{
+    "startTime": "2026-06-28T14:03:22Z", "endTime": "2026-06-28T14:03:24Z",
+    "traceId": "3f9c…", "jobKey": "8a1d…", "folderKey": "f-1001", "source": "10",
+    "policyId": "ISO42001-guardrail-prompt-injection", "policyName": "AI system impact assessment",
+    "packName": "ISO/IEC 42001:2023 Runtime", "hook": "BEFORE_MODEL",
+    "mode": "ENFORCE", "actionApplied": "BLOCK", "evaluatorResult": "DENY",
+    "reason": "Prompt injection was detected with a probability of 0.97.",
+    "agentId": "af12…", "agentName": "customer-care-assistant-for-acmecare"
+  }]
+}
+```
+
+Semantics — the traps:
+- **`evaluatorResult === AgentGovernanceVerdict.Deny` IS the violation.** `mode` (`AUDIT`/`ENFORCE`) says whether it was enforced; `actionApplied` is the enforcement action string (`null` in audit mode). Compare enum fields with the imported enums — `d.evaluatorResult === 'DENY'` is a tsc error.
+- **No server-side `traceId` filter.** Per-run views fetch the window and filter client-side on the row's `traceId`. `agentId` (agent project key) IS a server-side filter.
+- `violationsOnly: true` → Deny rows only. Use for violation tables and violation drill-downs.
+- One agent run = one `traceId` (with its `jobKey`); group rows by `traceId` for run-level rollups.
+- Rows are TS interfaces — project with `.map(x => ({ ...x }))`, never `as` casts.
+- User vocabulary maps onto the response fields: "rule" → **policy** (`policyId`/`policyName`), "standard" → **pack** (`packName`), "violation" → **Deny verdict**, "enforcement action" → **actionApplied**, "audit vs enforce" → **mode**.
+
+## Module patterns
+
+```typescript
+// agent-governance-violations (kpi-card with delta): summary twice — window + prior window
+import type { MetricFn } from '@/lib/metric-contract'
+import { THIRTY_DAYS_AGO, NOW, priorWindow } from '@/lib/time'
+
+export const fetchData: MetricFn = async (sdk) => {
+  const { AgentTraces } = await import('@uipath/uipath-typescript/traces')
+  const svc = new AgentTraces(sdk)
+  const [prevStart, prevEnd] = priorWindow(THIRTY_DAYS_AGO, NOW)
+  const [cur, prev] = await Promise.all([
+    svc.getGovernanceSummary(THIRTY_DAYS_AGO, { endTime: NOW }),
+    svc.getGovernanceSummary(prevStart, { endTime: prevEnd }),
+  ])
+  return [{ value: cur.violations, previous: prev.violations }]
+}
+
+// fetchDetail — the Deny decisions behind the count (record-grain drill-down)
+export const fetchDetail: MetricFn = async (sdk) => {
+  const { AgentTraces } = await import('@uipath/uipath-typescript/traces')
+  const page = await new AgentTraces(sdk).getGovernanceDecisions(THIRTY_DAYS_AGO, { endTime: NOW, violationsOnly: true })
+  return (page?.items ?? []).map(x => ({ ...x }))
+}
+```
+
+```typescript
+// Breakdown donuts / ranked tables: ONE summary call, pick the section
+// violations-by-standard → byPack · violations-by-rule → byPolicy · violations-by-hook → byHook
+// agents-by-violations → byAgent · matched-rules-by-action → byAction (sections opt-in!)
+const { AgentTraces, AgentGovernanceSection } = await import('@uipath/uipath-typescript/traces')
+const s = await new AgentTraces(sdk).getGovernanceSummary(THIRTY_DAYS_AGO, {
+  endTime: NOW,
+  sections: [AgentGovernanceSection.Action],   // ONLY when reading byAction/byMode
+})
+return s.byPack.map(p => ({ name: p.name ?? p.key ?? 'Unknown', value: p.violationCount }))
+```
+
+```typescript
+// rule-evaluations-by-outcome (donut): Allow vs Deny across all checks
+const s = await new AgentTraces(sdk).getGovernanceSummary(THIRTY_DAYS_AGO, { endTime: NOW })
+return [
+  { name: 'Allow', value: s.total - s.violations },
+  { name: 'Deny', value: s.violations },
+]
+```
+
+```typescript
+// recent-violations (data-table): the raw Deny rows
+const page = await new AgentTraces(sdk).getGovernanceDecisions(THIRTY_DAYS_AGO, { endTime: NOW, violationsOnly: true })
+return (page?.items ?? []).map(x => ({ ...x }))
+```
+
+## `agent-compliance-report` — one row per run + rowLink drill-down
+
+Group decisions by `traceId` (one run = one trace). Keep the row keys the registry columns expect: `runKey`, `agentName`, `startTime`, `evaluated`, `matched`, `finalAction`.
+
+```typescript
+import type { MetricFn, MetricDetailByKeyFn } from '@/lib/metric-contract'
+import { THIRTY_DAYS_AGO, NOW } from '@/lib/time'
+
+type RunRow = { runKey: string; agentName: string; startTime: string; evaluated: number; matched: number; finalAction: string }
+
+export const fetchData: MetricFn = async (sdk) => {
+  const { AgentTraces, AgentGovernanceVerdict, AgentGovernanceMode } = await import('@uipath/uipath-typescript/traces')
+  const rows = (await new AgentTraces(sdk).getGovernanceDecisions(THIRTY_DAYS_AGO, { endTime: NOW }))?.items ?? []
+  const byRun = new Map<string, RunRow>()
+  for (const d of rows) {
+    if (!d.traceId) continue
+    const run = byRun.get(d.traceId) ?? { runKey: d.traceId, agentName: d.agentName ?? '—', startTime: d.startTime, evaluated: 0, matched: 0, finalAction: 'allow' }
+    run.evaluated += 1
+    if (d.evaluatorResult === AgentGovernanceVerdict.Deny) {
+      run.matched += 1
+      run.finalAction = d.mode === AgentGovernanceMode.Enforce ? (d.actionApplied ?? 'enforced') : 'audit'
+    }
+    byRun.set(d.traceId, run)
+  }
+  return [...byRun.values()].sort((a, b) => b.startTime.localeCompare(a.startTime)).map(r => ({ ...r }))
+}
+
+// Drill-down: same window, filtered client-side to the clicked run (no server traceId filter).
+// Returns the named-source map the registry detailView expects.
+export const fetchDetailByKey: MetricDetailByKeyFn = async (sdk, key) => {
+  const { AgentTraces, AgentGovernanceVerdict } = await import('@uipath/uipath-typescript/traces')
+  const all = (await new AgentTraces(sdk).getGovernanceDecisions(THIRTY_DAYS_AGO, { endTime: NOW }))?.items ?? []
+  const rows = all.filter(d => d.traceId === key).map(x => ({ ...x }))
+  const denies = rows.filter(d => d.evaluatorResult === AgentGovernanceVerdict.Deny)
+  const count = (list: typeof rows, pick: (d: (typeof rows)[number]) => string) => {
+    const acc: Record<string, number> = {}
+    for (const d of list) { const k = pick(d); acc[k] = (acc[k] ?? 0) + 1 }
+    return Object.entries(acc).map(([name, value]) => ({ name, value })).sort((a, b) => b.value - a.value)
+  }
+  const hooks = [...new Set(rows.map(d => String(d.hook ?? 'UNKNOWN')))]
+  return {
+    rows,
+    byOutcomeByHook: hooks.map(h => ({
+      hook: h,
+      Allow: rows.filter(d => String(d.hook ?? 'UNKNOWN') === h && d.evaluatorResult !== AgentGovernanceVerdict.Deny).length,
+      Deny: rows.filter(d => String(d.hook ?? 'UNKNOWN') === h && d.evaluatorResult === AgentGovernanceVerdict.Deny).length,
+    })),
+    byAction: count(denies, d => String(d.actionApplied ?? 'none')),
+    byPolicy: count(denies, d => String(d.policyName ?? d.policyId ?? 'Unknown')),
+  }
+}
+```
+
+When the metric declares `detailView`, the detail fetch returns a **named-source map** (`{ rows, byOutcomeByHook, byAction, byPolicy }`) whose keys match each sub-widget's `source`. See `primitives/detail-views.md § Rich detail views`.
+
+## Robustness
+
+- Violation widgets on a passing fleet render an EmptyState ("No violations in this window — checks are passing"). For runtime-compliance requests ALSO offer an all-checks widget (`rule-evaluations-by-outcome`, `rule-evaluations-by-hook`, `rule-compliance`) so a compliant fleet is visible — an empty violations donut is indistinguishable from "no governance data".
+- UiPath currently ships ONE governance pack — `violations-by-standard` (byPack) is usually a single slice. Prefer by-hook / by-action / by-policy / by-agent groupings; propose by-standard only when >1 pack exists.
+- 403 → org-admin missing (see the header note). Never fabricate data — surface the access gap and build the rest.

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

@@ -0,0 +1,72 @@
+# Governance (Insights RTM) Reference
+
+> Requires `@uipath/uipath-typescript` **≥ 1.4.1**. Scopes: `Insights Insights.RealTimeData`. Governance endpoints expect an **elevated (org-admin) caller** — `fullOrganization: true` returns 403 without org-admin rights; if a tenant-scoped call 403s, tell the user their account lacks governance access.
+
+```typescript
+import { Governance, PolicyEvaluationResult } from '@uipath/uipath-typescript/governance';
+const svc = new Governance(sdk)
+```
+
+Both methods take a **required positional `startTime: Date`** first; everything else lives in the options object.
+
+## getPolicyTraces(startTime: Date, options?)
+
+Per-policy enforcement decisions, one row per policy verdict per event (one user action can yield multiple rows). Ordered by event start time desc. Returns `NonPaginatedResponse<GovernancePolicyTrace>` (or paginated). **Rows are on `.items`.**
+
+Options (`GovernancePolicyTraceGetAllOptions`): `endTime?: Date`, `fullOrganization?: boolean`, `evaluationResult?: PolicyEvaluationResult[]`, `policyId?: string[]`, `actorProcessId?: string[]`, `actorProcessType?: string[]`, `actorIdentityId?: string[]`, `resourceId?: string[]`, `resourceType?: string[]`, `traceId?: string[]` + pagination. Filters AND across fields, OR within an array.
+
+`PolicyEvaluationResult` enum: `Allow`, `Deny`, `SimulatedAllow`, `SimulatedDeny`.
+
+`GovernancePolicyTrace` fields: `tenantId`, `startTime`, `finalEnforcement`, `policyId`, `policyEnforcement`, `policyEvaluationResult`, `policyName`, `policyStatus`, `policyEvaluationDetails`, `actorProcessId`, `actorProcessType`, `actorIdentityId`, `resourceId`, `resourceType`, `folderKey`, `traceId`, `processKey`, `jobKey`. All optional except `startTime`.
+
+**Example response** (`.items` — shape from SDK test fixtures):
+
+```json
+{
+  "items": [
+    {
+      "tenantId": "t-2298", "startTime": "2026-06-10T14:03:22Z",
+      "finalEnforcement": "Deny", "policyId": "pol-7f3a", "policyEnforcement": "Deny",
+      "policyEvaluationResult": "Deny", "policyName": "Block external LLM calls",
+      "policyStatus": "Active", "actorProcessId": "InvoiceTriageAgent",
+      "actorProcessType": "CodedAgent", "actorIdentityId": "user-91",
+      "resourceId": "openai.com", "resourceType": "ExternalService",
+      "folderKey": "f-1001", "traceId": "tr-...", "processKey": "p-0088", "jobKey": "j-..."
+    }
+  ],
+  "count": 1
+}
+```
+
+## getOperationSummary(startTime: Date, options?)
+
+Aggregate enforcement counts for the window. Options: `{ endTime?: Date, fullOrganization?: boolean }`. Returns a **single object — not an array**:
+
+```json
+{ "totalEvaluations": 1240, "allowedCount": 1180, "deniedCount": 42, "noOpCount": 18 }
+```
+
+> **Semantics:** the SDK maps raw `allow`/`deny`/`noOp` → `allowedCount`/`deniedCount`/`noOpCount`. For a kpi-card or donut, the `fnBody` must wrap/transform the object into a row array (see patterns). No policy UUID is required — this summarizes all policies.
+
+## fnBody patterns
+
+```typescript
+// Denied actions (data-table)
+const { Governance, PolicyEvaluationResult } = await import('@uipath/uipath-typescript/governance')
+const result = await new Governance(sdk).getPolicyTraces(SEVEN_DAYS_AGO, {
+  endTime: NOW,
+  evaluationResult: [PolicyEvaluationResult.Deny, PolicyEvaluationResult.SimulatedDeny],
+})
+return (result?.items ?? []).map(x => ({ ...x }))
+```
+
+```typescript
+// Allow / Deny / NoOp breakdown (donut-chart: xKey name, yKey value)
+const { Governance } = await import('@uipath/uipath-typescript/governance')
+const s = await new Governance(sdk).getOperationSummary(SEVEN_DAYS_AGO, { endTime: NOW })
+return [
+  { name: 'Allowed', value: s.allowedCount },
+  { name: 'Denied', value: s.deniedCount },
+  { name: 'Simulated', value: s.noOpCount },
+]
+```

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

@@ -17,6 +17,10 @@ Read this when writing TypeScript code that imports classes, types, or options f
 | `@uipath/uipath-typescript/processes` | `Processes` |
 | `@uipath/uipath-typescript/jobs` | `Jobs` |
 | `@uipath/uipath-typescript/attachments` | `Attachments` |
+| `@uipath/uipath-typescript/agents` | `Agents`, `AgentListSortColumn`, `AgentErrorSortColumn` (Insights RTM — SDK ≥ 1.4.1) |
+| `@uipath/uipath-typescript/traces` | `AgentTraces`, `AgentTraceExecutionType`, `Traces` (generic spans — `Traces.getById(traceId)`) (Insights RTM — SDK ≥ 1.4.1) |
+| `@uipath/uipath-typescript/agent-memory` | `AgentMemory`, `AgentMemoryExecutionType` (SDK ≥ 1.4.1) |
+| `@uipath/uipath-typescript/governance` | `Governance`, `PolicyEvaluationResult` (SDK ≥ 1.4.1) |
 | `@uipath/uipath-typescript/conversational-agent` | `ConversationalAgent`, `Exchanges`, `Messages` |
 | `@uipath/uipath-typescript/feedback` | `Feedback` |
 

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

@@ -272,6 +272,21 @@ Returned by `getAll()` and `getById()` on each `ProcessInstanceGetResponse`:
 
 Returns `Promise<CaseGetAllResponse[]>`. Each case has: `processKey`, `packageId`, `name`, `folderKey`, `folderName`, `packageVersions`, `versionCount`, plus instance count fields (same as MaestroProcesses).
 
+**Example response** — a **bare top-level array** (no `.items` wrapper):
+
+```json
+[
+  {
+    "name": "Loan Processing", "processKey": "case-proc-uuid",
+    "folderKey": "f-1001", "folderName": "Lending", "versionCount": 2,
+    "pendingCount": 5, "runningCount": 3, "completedCount": 125,
+    "faultedCount": 1, "pausedCount": 0, "cancelledCount": 2
+  }
+]
+```
+
+> **Semantics:** same shape as `MaestroProcesses.getAll` — bare array, counts pre-aggregated per case process. Chart `runningCount` / `completedCount` / `faultedCount` directly.
+
 ### Analytics / Insights methods
 
 Same signatures and scope as the MaestroProcesses analytics methods above (`Insights.RealTimeData Insights OR.Folders.Read`), but scoped to cases:
@@ -389,3 +404,102 @@ function InstanceDashboard() {
   );
 }
 ```
+
+## Maestro Insights — RTM (SDK ≥ 1.4.x)
+
+> Scopes: Top/timeline/element methods need `Insights Insights.RealTimeData OR.Folders.Read`; the SLA methods additionally need **`PIMS`**. These use the Insights RTM host (NOT PIMS) — contrast with `Cases.getAll`/`CaseInstances.getAll`. Surface a 403 as a permissions message (the External App may lack the scopes in this environment).
+
+`Cases` (`@uipath/uipath-typescript/cases`) and `MaestroProcesses` (`@uipath/uipath-typescript/maestro-processes`) expose the **same six methods** with identical signatures. `CaseInstances` (`@uipath/uipath-typescript/cases`) adds the two SLA methods.
+
+**Positional `Date` args** (`start, end`) for the six analytics methods; `getSlaSummary` takes an **options object**. All return a **bare array** except `getSlaSummary` (rows on `.items`).
+
+| Method | Returns (bare array of) | Notes |
+|--------|------------------------|-------|
+| `getTopRunCount(start, end, options?)` | `{ packageId, processKey, runCount, name }` | ≤5, ranked. `options`: `{ packageId?, processKey?, version? }` |
+| `getTopFaultedCount(start, end, options?)` | `{ packageId, processKey, faultedCount, name }` | ≤10, ranked |
+| `getTopExecutionDuration(start, end, options?)` | `{ packageId, processKey, duration, name }` | ≤5, `duration` in ms |
+| `getTopElementFailedCount(start, end, options?)` | `{ elementName, elementType, processKey, failedCount }` | ≤10, BPMN elements |
+| `getInstanceStatusTimeline(start, end, options?)` | `{ startTime, status, count }` | `status` ∈ `Completed`/`Faulted`/`Cancelled`; `startTime` is a LOCALE string; `options`: `{ groupBy?: TimeInterval }` (HOUR/DAY/WEEK, default DAY) |
+| `getElementStats(processKey, packageId, start, end, packageVersion)` | `{ elementId, successCount, failCount, terminatedCount, pausedCount, inProgressCount, minDurationMs, maxDurationMs, avgDurationMs, p50DurationMs, p95DurationMs, p99DurationMs }` | all positional args |
+
+For Cases, `name` is derived from `packageId` (CaseManagement prefix stripped); for MaestroProcesses, `name === packageId`. Both present on every row.
+
+`CaseInstances` SLA methods:
+
+| Method | Returns | Row shape |
+|--------|---------|-----------|
+| `getSlaSummary(options?)` | `{ items: SlaSummaryResponse[] }` (default top 50) or paginated | `{ caseInstanceId, folderKey, name, externalId, caseSummary, processKey, slaDueTime (ISO UTC), slaStatus, escalationRuleIndex, escalationRuleType, instanceStatus, lastModifiedTime }`. `options`: `{ caseInstanceId?, startTimeUtc?: Date, endTimeUtc?: Date }` + pagination |
+| `getStagesSlaSummary(options?)` | **bare** `{ caseInstanceId, stages: Stage[] }[]` | `Stage = { elementId, name, latestStatus, slaDueTime, slaStatus, escalationRuleIndex, escalationRuleType }`. `options`: `{ caseInstanceId? }` |
+
+`slaStatus` string values: `'On Track'`, `'At Risk'`, `'Overdue'`, `'Completed'`, `'Unknown'`. **Compare as strings — do not import the enum** (avoids TS narrowing errors; values are stable).
+
+### Module patterns
+
+```ts
+// Top processes by run count (ranked-table) — native shape, return as-is
+import type { MetricFn } from '@/lib/metric-contract'
+import { THIRTY_DAYS_AGO, NOW } from '@/lib/time'
+
+export const fetchData: MetricFn = async (sdk) => {
+  const { MaestroProcesses } = await import('@uipath/uipath-typescript/maestro-processes')
+  const processes = await new MaestroProcesses(sdk).getTopRunCount(THIRTY_DAYS_AGO, NOW)
+  return processes.map(x => ({ ...x }))
+}
+```
+
+```ts
+// Process instance status over time (multi-line-chart) — pivot long→wide, seed all series
+export const fetchData: MetricFn = async (sdk) => {
+  const { MaestroProcesses } = await import('@uipath/uipath-typescript/maestro-processes')
+  const points = await new MaestroProcesses(sdk).getInstanceStatusTimeline(THIRTY_DAYS_AGO, NOW)
+  const byDate: Record<string, Record<string, unknown>> = {}
+  for (const p of points) {
+    const d = String(p.startTime)
+    byDate[d] = byDate[d] ?? { date: d, Completed: 0, Faulted: 0, Cancelled: 0 }
+    byDate[d][String(p.status)] = p.count
+  }
+  return Object.values(byDate)
+}
+```
+
+```ts
+// SLA status breakdown (donut-chart) — group by status string
+export const fetchData: MetricFn = async (sdk) => {
+  const { CaseInstances } = await import('@uipath/uipath-typescript/cases')
+  const { fetchAll } = await import('@/lib/paginate')
+  const rows = await fetchAll(cursor => new CaseInstances(sdk).getSlaSummary({ pageSize: 200, cursor }))
+  const by: Record<string, number> = {}
+  for (const r of rows) { const k = String(r.slaStatus); by[k] = (by[k] ?? 0) + 1 }
+  return Object.entries(by).map(([name, value]) => ({ name, value }))
+}
+```
+
+```ts
+// Cases at SLA risk (data-table) — filter At Risk / Overdue
+export const fetchData: MetricFn = async (sdk) => {
+  const { CaseInstances } = await import('@uipath/uipath-typescript/cases')
+  const { fetchAll } = await import('@/lib/paginate')
+  const rows = await fetchAll(cursor => new CaseInstances(sdk).getSlaSummary({ pageSize: 200, cursor }))
+  return rows.filter(r => { const s = String(r.slaStatus); return s === 'At Risk' || s === 'Overdue' })
+}
+```
+
+```ts
+// Stage-level SLA (data-table) — flatten stages
+export const fetchData: MetricFn = async (sdk) => {
+  const { CaseInstances } = await import('@uipath/uipath-typescript/cases')
+  const data = await new CaseInstances(sdk).getStagesSlaSummary()
+  return data.flatMap(d => d.stages.map(s => ({
+    caseInstanceId: d.caseInstanceId, stage: s.name, slaStatus: s.slaStatus, slaDueTime: s.slaDueTime, latestStatus: s.latestStatus,
+  })))
+}
+```
+
+```ts
+// Element latency stats (T2 — identifiers baked in at authoring time)
+export const fetchData: MetricFn = async (sdk) => {
+  const { MaestroProcesses } = await import('@uipath/uipath-typescript/maestro-processes')
+  const stats = await new MaestroProcesses(sdk).getElementStats('<processKey>', '<packageId>', THIRTY_DAYS_AGO, NOW, '<version>')
+  return stats.map(x => ({ ...x }))
+}
+```

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

@@ -213,7 +213,31 @@ Returns `Promise<ProcessStartResponse[]>`. The `request` must include either `pr
 
 ### getAll(options?: JobGetAllOptions)
 
-Returns `NonPaginatedResponse<JobGetResponse>` or `PaginatedResponse<JobGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`. Supports `filter`, `orderby`, `expand`, `select`.
+Returns `NonPaginatedResponse<JobGetResponse>` or `PaginatedResponse<JobGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`. Supports `filter`, `orderby`, `expand`, `select`. Rows are on `.items`.
+
+**Example response** (`.items`) — an agent job next to a standard RPA job. The agent job is `packageType: "Agent"` (the SDK maps raw `ProcessType` → `packageType`). Note `sourceType` is the *trigger origin* (here both happen to differ) and does NOT identify an agent — see § Job classification:
+
+```json
+{
+  "items": [
+    {
+      "id": 4012, "key": "a1b2c3d4-0000-0000-0000-000000000001",
+      "state": "Successful", "packageType": "Agent", "sourceType": "Manual",
+      "processName": "InvoiceTriageAgent",
+      "startTime": "2026-06-09T10:01:22Z", "endTime": "2026-06-09T10:01:48Z",
+      "createdTime": "2026-06-09T10:01:20Z", "hostMachineName": "AGENT-RUNTIME-3"
+    },
+    {
+      "id": 4011, "key": "a1b2c3d4-0000-0000-0000-000000000002",
+      "state": "Faulted", "packageType": "Process", "sourceType": "Schedule",
+      "processName": "DailyReconcile",
+      "startTime": "2026-06-09T09:40:00Z", "endTime": "2026-06-09T09:41:12Z",
+      "createdTime": "2026-06-09T09:39:58Z", "hostMachineName": "BOT-07"
+    }
+  ],
+  "count": 2
+}
+```
 
 ### getById(id: string, folderId: number, options?: JobGetByIdOptions)
 
@@ -235,7 +259,55 @@ Returns `Promise<void>`. Resumes a job currently in `Suspended` state. `JobResum
 
 Returns `Promise<JobGetResponse>` — a **new** job with a new `key`, in `Pending` state. The original job must be in a final state (`Successful`, `Faulted`, or `Stopped`). Inputs are inherited from the original.
 
-`JobGetResponse` fields: `key`, `id`, `state`, `createdTime`, `startTime`, `endTime`, `lastModifiedTime`, `resumeTime`, `processName`, `entryPointPath`, `processVersionId`, `hostMachineName`, `inputArguments`, `outputArguments`, `environmentVariables`, `type`, `packageType`, `runtimeType`, `serverlessJobType`, `jobPriority`, `specificPriorityValue`, `stopStrategy`, `remoteControlAccess`, `batchExecutionKey`, `parentJobKey`, `traceId`, `parentSpanId`, `errorCode`, `jobError`, `subState`, `machine`, `robot`, `process`. The `machine`, `robot`, and `process` fields are populated only when requested via `expand`.
+`JobGetResponse` fields: `key`, `id`, `state`, `createdTime`, `startTime`, `endTime`, `lastModifiedTime`, `resumeTime`, `processName`, `entryPointPath`, `processVersionId`, `hostMachineName`, `inputArguments`, `outputArguments`, `environmentVariables`, `type`, `sourceType`, `packageType`, `runtimeType`, `serverlessJobType`, `jobPriority`, `specificPriorityValue`, `stopStrategy`, `remoteControlAccess`, `batchExecutionKey`, `parentJobKey`, `traceId`, `parentSpanId`, `errorCode`, `jobError`, `subState`, `machine`, `robot`, `process`. The `machine`, `robot`, and `process` fields are populated only when requested via `expand`.
+
+### Job classification — agent vs process vs app
+
+An agent job is identified by **`packageType === 'Agent'`** on the SDK response object. The SDK's `JobMap` renames the raw API field `ProcessType → packageType`, so a raw job with `ProcessType: "Agent"` arrives as `packageType: "Agent"`.
+
+| Where | Field | Agent job value |
+|-------|-------|-----------------|
+| SDK response object (`fnBody` reads this) | `packageType` | `"Agent"` |
+| OData server-side `filter` string (raw API name) | `ProcessType` | `"Agent"` |
+
+> **Do NOT use `sourceType` to find agent jobs.** `sourceType` (raw `Source` / `JobSourceType`) is the **trigger origin** — `Manual`, `Schedule`, `Queue`, `Agent`, `Apps`, `HttpTrigger`, … An agent job can be triggered manually (`sourceType: "Manual"`), and `sourceType: "Agent"` only means "started by an agent source," which is a different thing. Filtering on `sourceType === 'Agent'` is wrong in both directions.
+
+Field mappings (raw → SDK, from `JobMap`): `releaseName → processName`, `creationTime → createdTime`, `organizationUnitId → folderId`. Job latency ← `endTime − startTime` (both timestamps; `endTime` is null while `Running`).
+
+Server-side filters (use the raw field name `ProcessType` in the OData string):
+- Agent jobs: `getAll({ filter: "ProcessType eq 'Agent'", orderby: 'CreationTime desc' })`
+- Faulted agent jobs: `getAll({ filter: "State eq 'Faulted' and ProcessType eq 'Agent'" })`
+- Reading results: `result.items.filter(j => j.packageType === 'Agent')` (client-side, mapped field name)
+
+#### Filterable vs read-only Job fields
+
+A field appearing in the response does **NOT** make it valid in an OData `$filter`. The SDK's mapped (renamed) response fields are **read-only** — filtering on them throws `Invalid OData query options … Could not find a property named '<field>'` at request time (invisible to `tsc`).
+
+| Read-only (response only — NEVER in `$filter`) | Filter on the raw field instead |
+|---|---|
+| `processName` (← `releaseName`) | match **client-side**: `items.filter(j => j.processName === name)` |
+| `createdTime` (← `creationTime`) | `CreationTime` (e.g. `orderby: 'CreationTime desc'`) |
+| `folderId` (← `organizationUnitId`) | folder is scoped via header, not `$filter` |
+| `packageType` (← `ProcessType`) | `ProcessType` |
+
+Safe `$filter` fields: **`ProcessType`**, **`State`**, **`CreationTime`**, **`StartTime`**. To find a specific agent's jobs, filter `ProcessType eq 'Agent'` and match the name **client-side** on `processName` — there is no server-side name filter.
+
+#### Recipe — jobs for a named agent → its most-recent trace's spans
+
+The bridge from a clicked agent to its spans (e.g. a `rowLink` table's `fetchDetailByKey`):
+
+```ts
+import type { MetricDetailByKeyFn } from '@/lib/metric-contract'
+
+export const fetchDetailByKey: MetricDetailByKeyFn = async (sdk, agentName) => {
+  const { Jobs } = await import('@uipath/uipath-typescript/jobs')
+  const { AgentTraces } = await import('@uipath/uipath-typescript/traces')
+  const jobs = (await new Jobs(sdk).getAll({ filter: "ProcessType eq 'Agent'", orderby: 'CreationTime desc' }))?.items ?? []
+  const job = jobs.find(j => j.processName === agentName)   // client-side match — processName is read-only
+  if (!job?.traceId) return []
+  return await new AgentTraces(sdk).getSpansByTraceId(job.traceId)   // Job carries traceId (see traces.md)
+}
+```
 
 ## Job-Attached Methods (JobMethods)
 
@@ -259,14 +331,18 @@ if (completed) {
 
 ## Attachments Service (Scopes: `OR.Folders` or `OR.Folders.Read`)
 
-Standalone service for retrieving Orchestrator attachment metadata and a signed URL for downloading the blob. `Jobs.getOutput()` uses this internally to resolve file-type output arguments — most app code will not need to call it directly, but if you call `Jobs.getOutput()` you must add `OR.Folders` (or `OR.Folders.Read`) to the app's scopes in addition to `OR.Jobs`.
+Standalone service for retrieving an Orchestrator attachment's metadata and a signed URL for downloading the blob. Coded Action Apps use this to resolve a `type: "file"` input — the file reference handed in by the automation (Maestro / Agent / RPA) — into downloadable bytes. `Jobs.getOutput()` also uses it internally to resolve file-type output arguments — if you call `Jobs.getOutput()` you must add `OR.Folders` (or `OR.Folders.Read`) to the app's scopes in addition to `OR.Jobs`.
+
+This service exposes **only** `getById` — there is no `getAll`, no create, and no delete.
 
 ### getById(id: string, options?: AttachmentGetByIdOptions)
 
-Returns `Promise<AttachmentResponse>`. Options support OData `expand` / `select`.
+Returns `Promise<AttachmentResponse>`. `id` is the attachment **UUID** (string) — not a number. Throws `ValidationError` if `id` is empty. `AttachmentGetByIdOptions` supports OData `expand` / `select`.
 
 `AttachmentResponse` fields: `id`, `name`, `jobKey?`, `attachmentCategory?`, `lastModifiedTime?`, `lastModifierUserId?`, `createdTime?`, `creatorUserId?`, `blobFileAccess: BucketGetUriResponse` (the signed URL + headers — `{ uri, httpMethod, requiresAuth, headers }`).
 
+Resolve a `file`-typed input to its bytes. Respect `requiresAuth` — when `true`, pass `headers` on the download request:
+
 ```typescript
 import { Attachments } from '@uipath/uipath-typescript/attachments';
 

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

@@ -19,6 +19,8 @@
 > ```
 >
 > Code that does `result.items.length` after a single call is almost always a bug — it returns at most the page size, not the total. Use `totalCount` for cardinality, the cursor loop for full retrieval. If the source has fewer rows than the default cap (e.g., 30 of a 100-cap), a single call works but you cannot rely on that as data grows.
+>
+> **Dashboard widgets:** don't hand-write this loop in `fnBody` — the dashboard scaffold ships a typed helper: `const { fetchAll } = await import('@/lib/paginate')` then `const items = await fetchAll(cursor => svc.getAll({ pageSize: 200, cursor }))` and return `items.map(x => ({ ...x }))` (project SDK rows into `Row` objects).
 
 ## Imports
 

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

@@ -0,0 +1,89 @@
+# Agent Traces (Insights RTM) Reference
+
+> Requires `@uipath/uipath-typescript` **≥ 1.4.1**. Scope: `Insights Insights.RealTimeData` (same as Agents/Agent Memory). Subpath: `@uipath/uipath-typescript/traces`.
+
+Trace-level (span-level) view of agent execution — errors, latency, unit consumption, and raw spans. Distinct from the `Agents` service (`sdk/agents.md`), which aggregates per agent. Use traces when the request is about *spans*, *trace-level* timelines, or per-(agent, version, folder) unit breakdowns.
+
+```typescript
+import { AgentTraces, AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';
+const svc = new AgentTraces(sdk)
+```
+
+**Convention:** every method takes ONE optional options object — `{ startTime?: Date, endTime?: Date, folderKeys?, agentId?, agentVersion?, executionType? }`. Dates go INSIDE the object (unlike `Agents`, which uses positional Dates). Window defaults to the **last 1 year** server-side. `executionType`: `AgentTraceExecutionType.Debug | Runtime` (omit for both). Exception: the two governance methods take a **required positional `startTime: Date`** first (options second) and are GATED — full contract, gate, and module patterns in [`sdk/governance-traces.md`](governance-traces.md).
+
+The three timeline/consumption methods return a **bare array** — no `.items` / `.data` unwrapping. The span methods are listed for completeness but are record-grain (not dashboard metrics).
+
+| Method | Returns (bare array of) | Use for |
+|--------|------------------------|---------|
+| `getErrorsTimeline(options?)` | `{ name, value, date }` (`name` = error name) | Trace error volume over time |
+| `getLatencyTimeline(options?)` | `{ name, value, date }` (`value` = **seconds**) | Trace latency over time |
+| `getUnitConsumption(options?)` | `{ agentId, folderKey, agentVersion, agentUnitsConsumed, platformUnitsConsumed }` | Per-agent AGU/PLTU totals (ranked table) |
+| `getSpansByTraceId(traceId)` | `AgentSpanGetResponse[]` | All spans of one trace (drill-down, not a metric) |
+| `getSpansByReference(referenceId, options?)` | paginated `AgentSpanGetResponse` | Spans under a reference id (drill-down, not a metric) |
+| `getGovernanceDecisions(startTime, options?)` **(≥ 1.5.1, org-admin)** | paginated `.items` decision rows | Runtime-governance policy checks — see `sdk/governance-traces.md` |
+| `getGovernanceSummary(startTime, options?)` **(≥ 1.5.1, org-admin)** | single summary object | Governance posture breakdowns — see `sdk/governance-traces.md` |
+
+## getErrorsTimeline
+
+```json
+[ { "name": "ToolTimeout", "value": 4, "date": "2026-06-02" },
+  { "name": "ValidationError", "value": 1, "date": "2026-06-02" } ]
+```
+
+`name` is the **error name/category** (not an agent name — contrast with `Agents.getErrorsTimeline`).
+
+## getLatencyTimeline
+
+```json
+[ { "name": "P50", "value": 0.82, "date": "2026-06-02" },
+  { "name": "P95", "value": 2.40, "date": "2026-06-02" } ]
+```
+
+`value` is **decimal seconds**. `name` is a series/grouping label — the exact values are not guaranteed to be `P50`/`P95`. For a robust default, average `value` per `date` into a single series; inspect live `name` values before plotting distinct series with a `multi-line-chart`.
+
+## getUnitConsumption
+
+```json
+[ { "agentId": "ag-0001", "folderKey": "f-1001", "agentVersion": "1.2.0", "agentUnitsConsumed": 340, "platformUnitsConsumed": 0 },
+  { "agentId": "ag-0002", "folderKey": "f-1001", "agentVersion": "1.0.0", "agentUnitsConsumed": 1210, "platformUnitsConsumed": 12 } ]
+```
+
+## Module patterns
+
+```typescript
+// Trace errors over time — total across error names (area-chart: xKey date, yKey value)
+import type { MetricFn } from '@/lib/metric-contract'
+import { THIRTY_DAYS_AGO, NOW } from '@/lib/time'
+
+export const fetchData: MetricFn = async (sdk) => {
+  const { AgentTraces } = await import('@uipath/uipath-typescript/traces')
+  const points = await new AgentTraces(sdk).getErrorsTimeline({ startTime: THIRTY_DAYS_AGO, endTime: NOW })
+  const byDate: Record<string, number> = {}
+  for (const p of points) byDate[p.date] = (byDate[p.date] ?? 0) + p.value
+  return Object.entries(byDate).sort().map(([date, value]) => ({ date, value }))
+}
+```
+
+```typescript
+// Trace latency over time — average per date (area-chart: xKey date, yKey value, seconds)
+const { AgentTraces } = await import('@uipath/uipath-typescript/traces')
+const points = await new AgentTraces(sdk).getLatencyTimeline({ startTime: THIRTY_DAYS_AGO, endTime: NOW })
+const acc: Record<string, { sum: number; n: number }> = {}
+for (const p of points) {
+  acc[p.date] = acc[p.date] ?? { sum: 0, n: 0 }
+  acc[p.date].sum += p.value
+  acc[p.date].n += 1
+}
+return Object.entries(acc).sort().map(([date, { sum, n }]) => ({ date, value: n ? sum / n : 0 }))
+```
+
+```typescript
+// Per-agent unit consumption (ranked-table)
+const { AgentTraces } = await import('@uipath/uipath-typescript/traces')
+const consumption = await new AgentTraces(sdk).getUnitConsumption({ startTime: THIRTY_DAYS_AGO, endTime: NOW })
+return consumption.map(x => ({ ...x }))
+```
+
+## Spans (drill-down only)
+
+`getSpansByTraceId(traceId)` and `getSpansByReference(referenceId, options?)` return raw span records (`AgentSpanGetResponse`: `id`, `traceId`, `parentId`, `name`, `startTime`, `endTime`, `attributes`, `status`, `spanType`, `jobKey`, `referenceId`, …). These are record-grain trace inspection, not aggregate dashboard metrics — use them for a `fetchDetail` drill-down, not a top-level widget. `getSpansByReference` is paginated (use `fetchAll`).