Onboard getIncidentsTimeline method on MaestroProcesses and Cases services

[ninja-shreyash]

Summary

Onboard a new SDK method getIncidentsTimeline on both MaestroProcesses and Cases services, backed by the existing IncidentsByTimeWindow Insights API. Follow the same pattern as getInstanceStatusTimeline and extend the shared TimelineOptions type to expose the process-level filters the backend already supports — for both methods.

Motivation

The current SDK has no way to retrieve incident counts over time. getIncidents(processKey, folderKey) returns full incident records for a single process, and getInstanceStatusTimeline returns instance status counts over time — neither answers "how many incidents happened per hour/day/week?"

This is the timeline chart data shape (e.g., "Incidents over the last 30 days") that drives monitoring dashboards.

Backend API

Endpoint: POST /AgenticInstanceStatus/IncidentsByTimeWindow
Insights-monitoring controller: AgenticInstanceStatusController.GetIncidentsByTimeWindow
SQL: AgenticOrchestrationQuery.IncidentsByTimeWindowQuery

Request

{
  "commonParams": {
    "startTime": <epoch ms>,
    "endTime": <epoch ms>,
    "packageId": "...",       // optional filter
    "version": "...",         // optional filter
    "processKey": "...",      // optional filter
    "processKeys": ["..."],   // optional allowlist filter
    "isCaseManagement": false // true for Cases, false for MaestroProcesses
  },
  "timeSliceUnit": "HOUR" | "DAY" | "WEEK",
  "timezoneOffset": <minutes from UTC, optional>
}

Response

{
  "dataPoints": [
    { "count": 0,   "startTime": "2026-04-27T00:00:00", "endTime": "2026-05-04T00:00:00" },
    { "count": 26,  "startTime": "2026-05-04T00:00:00", "endTime": "2026-05-11T00:00:00" },
    { "count": 129, "startTime": "2026-05-11T00:00:00", "endTime": "2026-05-18T00:00:00" }
    // … all buckets in range, zero-padded
  ]
}

Why expose on both MaestroProcesses and Cases?

The backend already accepts an isCaseManagement flag and uses it to filter PROCESSRUNS.CASEINSTANCEID IS NOT NULL/NULL — same pattern as TopProcessesByRunCount, TopProcessesByDuration, InstanceStatusByDate. So this method can be cleanly type-pure on both services:

• MaestroProcesses.getIncidentsTimeline(...) → sends isCaseManagement: false
• Cases.getIncidentsTimeline(...) → sends isCaseManagement: true

SDK design

Method signature

Match getInstanceStatusTimeline exactly for symmetry:

```ts
getIncidentsTimeline(
startTime: Date,
endTime: Date,
options?: TimelineOptions,
): Promise<IncidentTimelinePoint[]>;
```

Response type (new)

/**
 * Incident count within a specific time bucket.
 */
export interface IncidentTimelinePoint {
  /** Start of the time bucket (ISO timestamp) */
  startTime: string;
  /** End of the time bucket (ISO timestamp) */
  endTime: string;
  /** Number of incidents in this bucket */
  count: number;
}

Note: endTime is technically derivable from startTime + groupBy, but the backend returns it explicitly to handle DST / timezone edge cases cleanly. We pass it through.

Extend TimelineOptions (shared with getInstanceStatusTimeline)

Both backend endpoints (InstanceStatusByDate and IncidentsByTimeWindow) accept the identical filter set, but the SDK's TimelineOptions currently only exposes groupBy. Extend it once so both methods benefit:

```ts
export interface TimelineOptions {
/**

• How to group data points on the time axis.
• @default TimeInterval.Day
  */
  groupBy?: TimeInterval;

/** Filter by package ID */
packageId?: string;

/** Filter by package version */
version?: string;

/** Filter by process key */
processKey?: string;

/** Filter by a list of process keys (allowlist) */
processKeys?: string[];
}
```

Wiring this through fetchInstanceStatusTimeline (and the new fetchIncidentsTimeline) is straightforward — they just pass these fields into commonParams.

Service-level model

• New file: src/models/maestro/incidents-timeline.types.ts (or co-locate in insights.types.ts next to InstanceStatusTimelineResponse)
• Add getIncidentsTimeline to both MaestroProcessesServiceModel and CasesServiceModel
• Implement in src/services/maestro/insights.ts as fetchIncidentsTimeline(), mirroring the existing fetchInstanceStatusTimeline()
• Both processes.ts and cases.ts services delegate to it, supplying isCaseManagement

Endpoint constant

Add to src/utils/constants/endpoints/maestro.ts:

```ts
INCIDENTS_BY_TIME_WINDOW: \${INSIGHTS_RTM_BASE}/agenticInstanceStatus/IncidentsByTimeWindow,
```

Notable design decisions

• No timezoneOffset exposed (initially) — matches getInstanceStatusTimeline precedent. Can be added later under TimelineOptions for both methods if demanded.
• Pass through endTime in the response — backend includes it, costs little, avoids DST math on the consumer side.
• @track('MaestroProcesses.GetIncidentsTimeline') and @track('Cases.GetIncidentsTimeline') on the public methods.
• Integration test for both services in tests/integration/shared/maestro/.
• Unit tests in tests/unit/services/maestro/processes/ and tests/unit/services/maestro/cases/.
• Update docs/oauth-scopes.md with the new method's scopes.

Out of scope

• topInstancesSummary onboarding (deferred — see internal notes; needs backend isCaseManagement filter first).
• Adding timezoneOffset to TimelineOptions — defer until there's a concrete consumer need.

References

• Insights-monitoring controller: RealtimeMonitoring/RealTimeDashboards/src/Controllers/AgenticInstanceStatusController.cs (lines 909–957)
• SQL: RealtimeMonitoring/RealTimeDashboards/src/DataAccessor/Queries/AgenticOrchestrationQuery.ProcessAndInstances.cs (IncidentsByTimeWindowQuery, lines 479+)
• Existing precedent: getInstanceStatusTimeline on both services

[minion-workers]

Minion Worker activated!

Spinning up an autonomous Claude Code agent to work on this issue.

Setting	Value
Model	opus
Max turns	25
Timeout	30 min
Output	Draft PR

Track progress in the workflow runs.

A draft PR will be created when done.

[minion-workers]

Minion Agent completed ✅

Metric	Value
Model	unknown
Turns	76
Cost	$unknown
Workflow Run	Run 83

Agent Summary

I've completed the implementation of issue #485. Here's a summary of what was done.

Summary

Onboarded a new getIncidentsTimeline method on both MaestroProcesses and Cases services, backed by the IncidentsByTimeWindow Insights API, mirroring the existing getInstanceStatusTimeline pattern.

Source changes

• src/models/maestro/insights.types.ts — Extended TimelineOptions with the four process-level filters (packageId, version, processKey, processKeys) the backend already supports (these now benefit both timeline methods). Added the new IncidentTimelinePoint response interface.
• src/utils/constants/endpoints/maestro.ts — Added INCIDENTS_BY_TIME_WINDOW endpoint constant.
• src/services/maestro/insights.ts — Added fetchIncidentsTimeline() and extracted a shared buildTimelineCommonParams() helper now used by both fetch functions (wiring the new filters through commonParams). Handles the differing response shape: IncidentsByTimeWindow returns { dataPoints: [...] }, unlike InstanceStatusByDate which returns an array directly.
• processes.ts / cases.ts — Added getIncidentsTimeline() delegating to the shared fetcher with isCaseManagement false/true, decorated with @track('MaestroProcesses.GetIncidentsTimeline') / @track('Cases.GetIncidentsTimeline').
• processes.models.ts / cases.models.ts — Added the method signatures with full JSDoc (@param, @returns {@link IncidentTimelinePoint}, two @example blocks each).

Tests & docs

• Unit tests: full coverage on processes (success, filter wiring, null/empty, error) + delegation test on cases; new mock factory createMockIncidentTimelinePoint and test constants.
• Integration: shared testGetIncidentsTimeline helper + describe.skip blocks on both services (insightsrtm_ requires OAuth, not PAT — consistent with existing precedent).
• docs/oauth-scopes.md — added the new method's scope rows for both services.

Verification

• ✅ npm run typecheck — clean
• ✅ npm run lint (oxlint) — 0 warnings/errors
• ✅ npm run test:unit — all 1683 tests pass
• ✅ npm run build — succeeds with NODE_OPTIONS=--max-old-space-size=6144 (the default-heap OOM is environmental, not a code issue); IncidentTimelinePoint and getIncidentsTimeline confirmed present in both generated .d.ts files.

One note: the build requires a larger Node heap in this environment than the default — the rollup build OOMs otherwise. The code itself compiles and bundles cleanly.

[minion-workers]

Minion Worker completed! PR created: #486

Please review and mark 'Ready for review' when satisfied.