[Sig Events] Add significant events management skill and tools

Author: mykolaharmash

x-pack/platform/packages/shared/agent-builder/agent-builder-common/tools/constants.ts

@@ -52,6 +52,9 @@ export const platformStreamsSigEventsTools = {
   searchKnowledgeIndicators: `${internalNamespaces.platformStreams}.sig_events.ki_search`,
   createFeatureKnowledgeIndicator: `${internalNamespaces.platformStreams}.sig_events.ki_feature_create`,
   createQueryKnowledgeIndicator: `${internalNamespaces.platformStreams}.sig_events.ki_query_create`,
+  searchEvent: `${internalNamespaces.platformStreams}.sig_events.event_search`,
+  createEvent: `${internalNamespaces.platformStreams}.sig_events.event_create`,
+  updateEventVerdict: `${internalNamespaces.platformStreams}.sig_events.event_verdict_update`,
 } as const;
 
 export const attachmentTools = {

x-pack/platform/packages/shared/agent-builder/agent-builder-server/allow_lists.ts

@@ -125,6 +125,7 @@ export const AGENT_BUILDER_BUILTIN_SKILLS = [
   // Platform – Streams
   'streams-management',
   'significant-events-memory',
+  'significant-events-management',
   'knowledge-indicators-management',
   'ki-identification-management',
 

x-pack/platform/packages/shared/kbn-streams-schema/index.ts

@@ -302,8 +302,14 @@ export {
   type Discovery,
   verdictSchema,
   type Verdict,
+  SIG_EVENT_VERDICT_OPTIONS,
+  SIG_EVENT_IMPACT_OPTIONS,
   sigEventSchema,
+  sigEventVerdictSchema,
+  sigEventImpactSchema,
   type SigEvent,
+  type SigEventVerdict,
+  type SigEventImpact,
 } from './src/sig_events';
 export type { OnboardingResult } from './src/onboarding';
 export { OnboardingStep } from './src/onboarding';

x-pack/platform/packages/shared/kbn-streams-schema/src/sig_events/events/index.ts

@@ -13,25 +13,33 @@ import {
   evidenceSchema,
 } from '../common_schemas';
 
+export const SIG_EVENT_VERDICT_OPTIONS = ['promoted', 'acknowledged', 'demoted'] as const;
+export const sigEventVerdictSchema = z.enum(SIG_EVENT_VERDICT_OPTIONS);
+export type SigEventVerdict = z.infer<typeof sigEventVerdictSchema>;
+
+export const SIG_EVENT_IMPACT_OPTIONS = ['critical', 'high', 'medium', 'low'] as const;
+export const sigEventImpactSchema = z.enum(SIG_EVENT_IMPACT_OPTIONS);
+export type SigEventImpact = z.infer<typeof sigEventImpactSchema>;
+
 export const sigEventSchema = z.object({
   '@timestamp': z.iso.datetime(),
   created_at: z.iso.datetime(),
   event_id: z.string(),
-  discovery_id: z.string(),
+  discovery_id: z.string().optional(),
   discovery_slug: z.string(),
   previous_event_id: z.string().optional(),
-  verdict: z.string(),
-  verdict_id: z.string(),
-  workflow_execution_id: z.string(),
-  rule_names: z.array(z.string()),
+  verdict: sigEventVerdictSchema,
+  verdict_id: z.string().optional(),
+  workflow_execution_id: z.string().optional(),
+  rule_names: z.array(z.string()).optional(),
   stream_names: z.array(z.string()),
   title: z.string(),
   summary: z.string(),
   root_cause: z.string(),
   criticality: z.number(),
   confidence: z.number(),
   recommended_action: z.string(),
-  impact: z.string(),
+  impact: sigEventImpactSchema,
   recommendations: z.array(z.string()),
   dependency_edges: z.array(dependencyEdgeSchema).optional(),
   infra_components: z.array(infraComponentSchema).optional(),

x-pack/platform/packages/shared/kbn-streams-schema/src/sig_events/index.ts

@@ -8,4 +8,13 @@
 export { detectionSchema, type Detection } from './detections';
 export { discoverySchema, type Discovery } from './discoveries';
 export { verdictSchema, type Verdict } from './verdicts';
-export { sigEventSchema, type SigEvent } from './events';
+export {
+  SIG_EVENT_VERDICT_OPTIONS,
+  SIG_EVENT_IMPACT_OPTIONS,
+  sigEventSchema,
+  sigEventVerdictSchema,
+  sigEventImpactSchema,
+  type SigEvent,
+  type SigEventVerdict,
+  type SigEventImpact,
+} from './events';

x-pack/platform/plugins/shared/streams/server/agent_builder/skills/register_skills.ts

@@ -11,6 +11,7 @@ import type { GetScopedClients } from '../../routes/types';
 import { streamsManagementSkill } from './streams_management_skill';
 import { knowledgeIndicatorsManagementSkill } from './knowledge_indicators_management';
 import { createKiIdentificationManagementSkill } from './ki_identification_management';
+import { sigEventsManagementSkill } from './sig_events_management';
 
 export const registerAgentBuilderSkills = ({
   agentBuilder,
@@ -28,6 +29,7 @@ export const registerAgentBuilderSkills = ({
   const streamsSkills = [
     streamsManagementSkill,
     knowledgeIndicatorsManagementSkill,
+    sigEventsManagementSkill,
     createKiIdentificationManagementSkill({ getScopedClients, telemetry }),
   ];
 

x-pack/platform/plugins/shared/streams/server/agent_builder/skills/sig_events_management/description.text

@@ -0,0 +1 @@
+Search, create, and update significant events for Streams, with guidance to avoid duplicates and keep event lifecycle state accurate.

x-pack/platform/plugins/shared/streams/server/agent_builder/skills/sig_events_management/index.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { defineSkillType } from '@kbn/agent-builder-server/skills/type_definition';
+import {
+  STREAMS_CREATE_EVENT_TOOL_ID,
+  STREAMS_EVENT_VERDICT_UPDATE_TOOL_ID,
+  STREAMS_SEARCH_EVENTS_TOOL_ID,
+} from '../../tools/register_tools';
+import description from './description.text';
+import content from './skill.md.text';
+
+export const sigEventsManagementSkill = defineSkillType({
+  id: 'significant-events-management',
+  name: 'significant-events-management',
+  basePath: 'skills/platform/streams',
+  description,
+  content,
+  getRegistryTools: () => [
+    STREAMS_SEARCH_EVENTS_TOOL_ID,
+    STREAMS_CREATE_EVENT_TOOL_ID,
+    STREAMS_EVENT_VERDICT_UPDATE_TOOL_ID,
+  ],
+});

x-pack/platform/plugins/shared/streams/server/agent_builder/skills/sig_events_management/skill.md.text

@@ -0,0 +1,167 @@
+You manage Significant Events (SigEvents) for Streams.
+
+<significant_events_concept>
+What a Significant Event is:
+- A SigEvent is a durable incident-level summary of an important operational issue.
+- It captures what happened, why it happened, impact, confidence/criticality, and supporting context.
+- SigEvents should be actionable and non-duplicative.
+
+Examples of conversation signals that may indicate a SigEvent:
+- Recurring service degradation with clear customer/user impact.
+- Security or compliance risk with confirmed evidence.
+- Cross-stream failures that share a common root cause.
+- Repeated alerting patterns that represent a known incident class.
+</significant_events_concept>
+
+<available_tools>
+You have 3 SigEvents tools in this skill:
+
+- `event_search`
+  Use this first to find existing similar significant events.
+  `query` is optional; if omitted (or empty), search uses optional stream and verdict filters only.
+  `stream_name` is optional; omit it for cross-stream searches.
+
+- `event_create`
+  Use this only after confirming there is no similar existing event.
+  The system generates internal identifiers and timestamps automatically.
+
+- `event_verdict_update`
+  Use this to update an existing event verdict to one of: `promoted`, `acknowledged`, `demoted`.
+  If an event already has the requested verdict or is missing, update is ignored.
+
+Additional globally-available helper guidance:
+- `ki_search` can be used to gather existing Knowledge Indicators (KIs) for context.
+- `execute_esql` can be used to confirm the event and collect evidence rows.
+</available_tools>
+
+<required_workflow>
+Always follow this workflow:
+1. Detect potential significant-event signals from the conversation.
+2. Search existing events with `event_search` using optional stream scope and optional query.
+3. Compare returned events for semantic similarity (same issue class/root cause/impact).
+4. If a similar event exists, do not create a duplicate; reference the existing event.
+5. If no similar event exists, investigate and validate:
+   - Use `ki_search` to collect related Feature and Query KIs.
+   - Use `execute_esql` to confirm the issue and gather supporting facts.
+6. Create a new event with `event_create` using complete, high-quality event properties.
+
+Verdict update workflow:
+1. Gather evidence supporting the target event state.
+2. Choose verdict based on intent:
+   - `promoted`: incident-worthy and active.
+   - `acknowledged`: known and actively tracked.
+   - `demoted`: no longer incident-worthy.
+3. Call `event_verdict_update` with the event id and target verdict.
+4. Treat `{ updated: 0, ignored: 1 }` as expected when event is missing or already in the requested verdict.
+</required_workflow>
+
+<proactive_behavior>
+Be proactive.
+
+When conversation context and evidence strongly suggest a new significant event, suggest creating one.
+
+Proactive pattern:
+1. State why current signals indicate a likely new significant event.
+2. Run `event_search` to check for similar existing events.
+3. If no similar event exists, recommend creating a new event and proceed with investigation/evidence collection.
+4. Use `event_create` with a complete payload.
+</proactive_behavior>
+
+<ki_and_evidence_guidance>
+Using KIs for context:
+- Prefer KI context before writing root cause and impact.
+- Reuse KI terminology in `summary`, `root_cause`, and `impact` when relevant.
+
+Using ES|QL for confirmation:
+- Run focused ES|QL queries that directly test the suspected issue.
+- Capture concise evidence in narrative form inside `summary`, `root_cause`, and `impact`.
+- If detailed evidence structures are needed, ensure tool support exists before attempting to submit them.
+</ki_and_evidence_guidance>
+
+<sig_event_property_guidance>
+Populate event properties with care:
+
+- `verdict`:
+  - For new events, default to `promoted` unless user intent says otherwise.
+
+- `title`:
+  - Short, specific, human-readable incident title.
+
+- `summary`:
+  - Brief narrative: what happened, where, and key signal.
+
+- `root_cause`:
+  - Best-known causal explanation; avoid vague language.
+
+- `stream_names`:
+  - Include all affected streams.
+
+- `criticality`:
+  - Number in range 0..100 indicating system criticality.
+  - Suggested scale:
+    - 0-30 low
+    - 31-60 medium
+    - 61-80 high
+    - 81-100 critical
+
+- `confidence`:
+  - Required. Float in range 0..1 indicating confidence in the event assessment.
+
+- `impact`:
+  - Always set to exactly one of: `critical`, `high`, `medium`, `low`.
+
+- `recommended_action`:
+  - Required. Short next operator action, ideally a single word (for example: `escalate`).
+
+- `recommendations`:
+  - Required. List of descriptive, detailed mitigation steps.
+</sig_event_property_guidance>
+
+<tool_examples>
+Example: search existing events first
+Tool: `event_search`
+{
+  "query": "checkout latency spike with timeout burst",
+  "stream_name": "logs.checkout",
+  "verdict": ["promoted", "acknowledged"]
+}
+
+Example: filter-only search (no query text)
+Tool: `event_search`
+{
+  "stream_name": "logs.checkout",
+  "verdict": ["promoted", "acknowledged"]
+}
+
+Example: cross-stream search (no stream_name)
+Tool: `event_search`
+{
+  "query": "timeout burst",
+  "verdict": ["promoted", "acknowledged"]
+}
+
+Example: create a new significant event
+Tool: `event_create`
+{
+  "verdict": "promoted",
+  "title": "Checkout timeout spike under upstream latency",
+  "summary": "Checkout experienced a sustained timeout spike correlated with upstream latency increase.",
+  "root_cause": "Upstream dependency latency exceeded service timeout budget during peak load.",
+  "stream_names": ["logs.checkout", "logs.payment"],
+  "criticality": 86,
+  "confidence": 0.84,
+  "impact": "high",
+  "recommended_action": "Scale checkout pods and increase upstream timeout budget temporarily.",
+  "recommendations": [
+    "Add alert on upstream latency threshold breach",
+    "Review timeout configuration for checkout service"
+  ]
+}
+
+Example: update an existing significant event verdict
+Tool: `event_verdict_update`
+{
+  "event_id": "9c4d04a1-86fe-45c2-b1dd-00891a8ba9f1",
+  "verdict": "acknowledged"
+}
+</tool_examples>

x-pack/platform/plugins/shared/streams/server/agent_builder/tools/event_create/handler.test.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { createEventToolHandler } from './handler';
+
+describe('createEventToolHandler', () => {
+  it('creates a single event', async () => {
+    const eventClient = {
+      bulkCreate: jest.fn().mockResolvedValue({}),
+    };
+
+    const result = await createEventToolHandler({
+      eventClient: eventClient as never,
+      eventInput: {
+        title: 'T',
+        summary: 'S',
+        root_cause: 'R',
+        stream_names: ['logs.a'],
+        criticality: 60,
+        impact: 'high',
+        confidence: 0.7,
+        recommended_action: 'escalate',
+        recommendations: ['create incident'],
+      },
+    });
+
+    expect(eventClient.bulkCreate).toHaveBeenCalledTimes(1);
+    expect(eventClient.bulkCreate).toHaveBeenCalledWith([
+      expect.objectContaining({
+        discovery_slug: expect.stringMatching(/^agent-event-[a-f0-9]{8}$/),
+      }),
+    ]);
+    expect(result.acknowledged).toBe(true);
+    expect(result.event_id).toBeTruthy();
+  });
+});