[agent_builder] Package-owned agent management and access control (AB-001-006)

Adds the package-managed agent surface:
- AB-001: AgentBuilderManagementSetup create/update/delete for package agents
- AB-003/004: managed_by_package labels + readonly enforcement, honored through
  agent update paths and persisted through the agent type
- AB-005: caller-request skill registry path; reap stale package-owned skills
- AB-006: validate REPLACE_WITH_FLEET_AGENT_* against installed agents

Extracted as a feature-scoped net-diff squash from the SDLC visibility-platform
dogfood branch (excludes WF-009 structured-output drift and fleet agent-asset
install steps, which belong to their own rungs).

Verified on fresh origin/main: 0 type_check errors in agent_builder,
authorization.test 10/10, action_utils.test 11/11.

Author: patrykkopycinski

x-pack/platform/packages/shared/agent-builder/agent-builder-common/agents/crud.ts

@@ -25,13 +25,24 @@ export type AgentCreateRequest = Omit<
    */
   type?: string;
   access_control?: Pick<AgentAccessControl, 'access_mode'>;
+  /**
+   * AB-004: when true the agent is created readonly (package-managed).
+   * Fleet package installs set this so UI edits warn/block, mirroring the
+   * managed workflow pattern. Carried on update so package upgrades keep it.
+   */
+  readonly?: boolean;
 };
 
 export type AgentUpdateRequest = Partial<
   Pick<AgentDefinition, 'name' | 'description' | 'labels' | 'avatar_color' | 'avatar_symbol'>
 > & {
   access_control?: Pick<AgentAccessControl, 'access_mode'>;
   configuration?: Partial<AgentConfiguration>;
+  /**
+   * AB-004: package upgrades re-assert the managed flag; a reinstall must not
+   * silently downgrade a package agent to an editable user agent.
+   */
+  readonly?: boolean;
 };
 
 export type AgentDeleteRequest = Pick<AgentDefinition, 'id'>;

x-pack/platform/packages/shared/agent-builder/agent-builder-common/agents/definition.ts

@@ -82,6 +82,7 @@ export interface AgentDefinition {
    * Optional labels used to organize or filter agents
    */
   labels?: string[];
+  /** True when the agent is managed by a package and must not be edited by users. */
   /**
    * Optional avatar eui icon for built-in agents
    */

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

@@ -7,7 +7,11 @@
 
 import type { ZodObject } from '@kbn/zod/v4';
 import type { KibanaRequest } from '@kbn/core-http-server';
-import type { AgentCreateRequest, ConversationTemplate } from '@kbn/agent-builder-common';
+import type {
+  AgentCreateRequest,
+  ConversationTemplate,
+  PersistedSkillCreateRequest,
+} from '@kbn/agent-builder-common';
 import type { ConversationPublicClient } from './conversations';
 import type { StaticToolRegistration, ToolRegistry } from './tools';
 import type { AttachmentTypeDefinition } from './attachments';
@@ -238,11 +242,36 @@ export interface TopSnippetsConfig {
 /**
  * Setup contract of the agentBuilder plugin.
  */
+
+/**
+ * Internal management API for package-owned persisted agents and skills
+ * (e.g. Fleet package install/uninstall).
+ */
+export interface AgentBuilderManagementSetup {
+  /** Read a single agent, or null when it does not exist. Used to enrich Fleet asset listings. */
+  getAgent(agentId: string, request: KibanaRequest): Promise<unknown>;
+  createOrUpdateAgent(params: AgentCreateRequest, request: KibanaRequest): Promise<unknown>;
+  deletePackageManagedAgent(agentId: string, spaceId: string): Promise<boolean>;
+  createOrUpdateSkill(params: PersistedSkillCreateRequest, request: KibanaRequest): Promise<unknown>;
+  deletePackageManagedSkill(skillId: string, spaceId: string): Promise<boolean>;
+  /**
+   * List the skills a package owns, so install can reap the ones the current
+   * archive no longer produces. Package-managed skills are readonly, so an
+   * orphan left behind by an id-scheme change is otherwise undeletable.
+   */
+  listPackageManagedSkills(
+    pluginId: string,
+    spaceId: string
+  ): Promise<Array<{ id: string; plugin_id?: string }>>;
+}
+
 export interface AgentBuilderPluginSetup {
   /**
    * Agents setup contract, which can be used to register built-in agents.
    */
   agents: AgentsSetup;
+  /** Internal management API for programmatic agent/skill CRUD (Fleet package install). */
+  management: AgentBuilderManagementSetup;
   /**
    * Tools setup contract, which can be used to register built-in tools.
    */

x-pack/platform/plugins/shared/agent_builder/common/agents.ts

@@ -28,6 +28,11 @@ export type AgentCreateRequest = Omit<
    */
   type?: string;
   access_control?: Pick<AgentAccessControl, 'access_mode'>;
+  /**
+   * AB-004: when true the agent is created readonly (package-managed).
+   * Fleet package installs set this so UI edits warn/block.
+   */
+  readonly?: boolean;
 };
 
 export type AgentUpdateRequest = Partial<

x-pack/platform/plugins/shared/agent_builder/server/api/agent_builder_management_api.ts

@@ -0,0 +1,223 @@
+/*
+ * 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 { CoreSetup, KibanaRequest, Logger } from '@kbn/core/server';
+import type {
+  AgentCreateRequest,
+  AgentUpdateRequest,
+  PersistedSkillCreateRequest,
+} from '@kbn/agent-builder-common';
+import { skillIndexName } from '../services/skills/persisted/client/storage';
+
+import { agentsIndexName } from '../services/agents/persisted/client/storage';
+import type { AgentBuilderPluginStart, AgentBuilderStartDependencies } from '../types';
+
+export class AgentBuilderManagementApi {
+  constructor(
+    private readonly getStartServices: CoreSetup<
+      AgentBuilderStartDependencies,
+      AgentBuilderPluginStart
+    >['getStartServices'],
+    private readonly logger: Logger
+  ) {}
+
+  private async getAgentsService() {
+    const [, , pluginStart] = await this.getStartServices();
+    if (!pluginStart?.agents) {
+      throw new Error('agentBuilder plugin is not available');
+    }
+    return pluginStart.agents;
+  }
+
+  public async getAgent(agentId: string, request: KibanaRequest) {
+    const agents = await this.getAgentsService();
+    const registry = await agents.getRegistry({ request });
+    if (!(await registry.has(agentId))) {
+      return null;
+    }
+    return registry.get(agentId);
+  }
+
+  public async createOrUpdateAgent(params: AgentCreateRequest, request: KibanaRequest) {
+    const agents = await this.getAgentsService();
+    const registry = await agents.getRegistry({ request });
+
+    if (await registry.has(params.id)) {
+      const update: AgentUpdateRequest = {
+        name: params.name,
+        description: params.description,
+        labels: params.labels,
+        // AB-004: carry the managed flag on upgrades too, otherwise a reinstall
+        // silently downgrades a package agent to an editable user agent.
+        readonly: params.readonly,
+        avatar_color: params.avatar_color,
+        avatar_symbol: params.avatar_symbol,
+        configuration: params.configuration,
+      };
+      return registry.update(params.id, update);
+    }
+
+    return registry.create(params); // AB-004: params may carry readonly=true (fleet package agent)
+  }
+
+  public async deleteAgent(agentId: string, request: KibanaRequest): Promise<boolean> {
+    const agents = await this.getAgentsService();
+    const registry = await agents.getRegistry({ request });
+    return registry.delete({ id: agentId });
+  }
+
+  /**
+   * System-level delete for Fleet package uninstall (no end-user request context).
+   */
+  public async deletePackageManagedAgent(agentId: string, spaceId: string): Promise<boolean> {
+    const [coreStart] = await this.getStartServices();
+    const esClient = coreStart.elasticsearch.client.asInternalUser;
+
+    try {
+      const searchResult = await esClient.search<{ id: string; space: string }>({
+        index: agentsIndexName,
+        query: {
+          bool: {
+            filter: [{ term: { id: agentId } }, { term: { space: spaceId } }],
+          },
+        },
+        size: 1,
+      });
+
+      const documentId = searchResult.hits.hits[0]?._id;
+      if (!documentId) {
+        return false;
+      }
+
+      const deleteResponse = await esClient.delete({
+        index: agentsIndexName,
+        id: documentId,
+      });
+      return deleteResponse.result === 'deleted';
+    } catch (error) {
+      this.logger.warn(
+        `Failed to delete package-managed agent ${agentId} in space ${spaceId}: ${
+          (error as Error).message
+        }`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * AB-005: create or update a package-managed persisted skill
+   * (system context; plugin_id makes it readonly in the UI).
+   */
+  public async createOrUpdateSkill(params: PersistedSkillCreateRequest, request: KibanaRequest) {
+    const [, , pluginStart] = await this.getStartServices();
+    if (!pluginStart?.skills) {
+      throw new Error('agentBuilder skills service is not available');
+    }
+    // Use the caller request: the skills registry runs an ES privilege check,
+    // which fails with a synthetic credential-less request.
+    const registry = await pluginStart.skills.getRegistry({ request });
+    if (!(await registry.has(params.id))) {
+      return registry.create(params);
+    }
+    // The registry blocks direct updates of plugin-managed skills (a guard meant for
+    // end users). Package reinstall/upgrade must still refresh its own skill, so write
+    // the document through the internal client instead.
+    const [coreStart] = await this.getStartServices();
+    const esClient = coreStart.elasticsearch.client.asInternalUser;
+    const existing = await esClient.search<Record<string, unknown>>({
+      index: skillIndexName,
+      query: { term: { id: params.id } },
+      size: 1,
+    });
+    const hit = existing.hits.hits[0];
+    if (!hit?._id) {
+      return registry.create(params);
+    }
+    const updatedDocument = {
+      ...(hit._source ?? {}),
+      name: params.name,
+      description: params.description,
+      content: params.content,
+      tool_ids: params.tool_ids,
+      updated_at: new Date().toISOString(),
+    };
+    await esClient.index({ index: skillIndexName, id: hit._id, document: updatedDocument, refresh: true });
+    return registry.get(params.id);
+  }
+
+  /**
+   * AB-005: system-level delete for Fleet package uninstall.
+   * The user-context registry blocks deletes of plugin-managed skills,
+   * so bypass it with an internal ES query by id + space.
+   */
+  public async deletePackageManagedSkill(skillId: string, spaceId: string): Promise<boolean> {
+    const [coreStart] = await this.getStartServices();
+    const esClient = coreStart.elasticsearch.client.asInternalUser;
+    try {
+      const searchResult = await esClient.search<{ id: string; space: string }>({
+        index: skillIndexName,
+        query: {
+          bool: {
+            filter: [{ term: { id: skillId } }, { term: { space: spaceId } }],
+          },
+        },
+        size: 1,
+      });
+      const documentId = searchResult.hits.hits[0]?._id;
+      if (!documentId) {
+        return false;
+      }
+      const deleteResponse = await esClient.delete({ index: skillIndexName, id: documentId });
+      return deleteResponse.result === 'deleted';
+    } catch (error) {
+      this.logger.warn(
+        `Failed to delete package-managed skill ${skillId} in space ${spaceId}: ${
+          (error as Error).message
+        }`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * AB-005: list the skills owned by a Fleet package in a space.
+   *
+   * Package-managed skills are readonly, so neither the user nor package
+   * uninstall can remove one whose id is absent from the package asset refs.
+   * Install uses this to reap its own stale skills; it reads through the
+   * internal client because the user-context registry hides plugin-managed
+   * skills by default.
+   */
+  public async listPackageManagedSkills(
+    pluginId: string,
+    spaceId: string
+  ): Promise<Array<{ id: string; plugin_id?: string }>> {
+    const [coreStart] = await this.getStartServices();
+    const esClient = coreStart.elasticsearch.client.asInternalUser;
+    try {
+      const searchResult = await esClient.search<{ id: string; plugin_id?: string }>({
+        index: skillIndexName,
+        query: {
+          bool: {
+            filter: [{ term: { plugin_id: pluginId } }, { term: { space: spaceId } }],
+          },
+        },
+        size: 1000,
+      });
+      return searchResult.hits.hits
+        .map((hit) => hit._source)
+        .filter((source): source is { id: string; plugin_id?: string } => Boolean(source?.id));
+    } catch (error) {
+      this.logger.warn(
+        `Failed to list package-managed skills for ${pluginId} in space ${spaceId}: ${
+          (error as Error).message
+        }`
+      );
+      return [];
+    }
+  }
+}

x-pack/platform/plugins/shared/agent_builder/server/mocks.ts

@@ -26,6 +26,14 @@ const createSetupContractMock = (): AgentBuilderPluginSetupMock => {
     tools: {
       register: jest.fn(),
     },
+    management: {
+      getAgent: jest.fn(),
+      createOrUpdateAgent: jest.fn(),
+      deletePackageManagedAgent: jest.fn(),
+      createOrUpdateSkill: jest.fn(),
+      deletePackageManagedSkill: jest.fn(),
+      listPackageManagedSkills: jest.fn().mockResolvedValue([]),
+    },
     attachments: {
       registerType: jest.fn(),
     },

x-pack/platform/plugins/shared/agent_builder/server/plugin.ts

@@ -14,6 +14,7 @@ import type {
 } from '@kbn/core/server';
 import type { Logger } from '@kbn/logging';
 import { AGENT_BUILDER_EXPERIMENTAL_FEATURES_SETTING_ID } from '@kbn/management-settings-ids';
+import { AgentBuilderManagementApi } from './api/agent_builder_management_api';
 import type { UsageCounter } from '@kbn/usage-collection-plugin/server';
 import type { HomeServerPluginSetup } from '@kbn/home-plugin/server';
 import {
@@ -278,6 +279,9 @@ export class AgentBuilderPlugin
         ),
       },
       topSnippets: this.config.topSnippets,
+      // AB-004/AB-005: Fleet package installs create/update package-managed
+      // agents and skills through this system-level management surface.
+      management: new AgentBuilderManagementApi(coreSetup.getStartServices, this.logger),
     };
   }
 

x-pack/platform/plugins/shared/agent_builder/server/services/agents/access_control/authorization.test.ts

@@ -58,13 +58,31 @@ describe('agent access-control authorization', () => {
       expect(
         isAgentOwner({
           owner: { id: 'owner-id', username: 'alice' },
-          currentUser: { username: 'alice' },
+          currentUser: { id: 'different-id', username: 'alice' },
         })
       ).toBe(false);
+      // Profile-uid owners never accept a username-only current user.
       expect(
         isAgentOwner({
           owner: { id: 'owner-id', username: 'alice' },
-          currentUser: { id: 'different-id', username: 'alice' },
+          currentUser: { username: 'alice' },
+        })
+      ).toBe(false);
+    });
+
+    it('accepts the realm-encoded username when the current user id is unresolvable', () => {
+      // Kibana authc can omit authentication_realm, leaving currentUser.id undefined. The owner
+      // must still be recognised, but only via the username encoded in its own realm id.
+      expect(
+        isAgentOwner({
+          owner: { id: 'realm:["reserved","reserved","elastic"]', username: 'elastic' },
+          currentUser: { username: 'elastic' },
+        })
+      ).toBe(true);
+      expect(
+        isAgentOwner({
+          owner: { id: 'realm:["reserved","reserved","elastic"]', username: 'elastic' },
+          currentUser: { username: 'mallory' },
         })
       ).toBe(false);
     });