add workspace schema versioning

Author: pgayvallet

x-pack/platform/plugins/shared/agent_builder/server/services/execution/filesystem/filesystem_service.test.ts

@@ -60,9 +60,6 @@ describe('FilesystemService', () => {
 
   it('loads persisted workspace files on init when workspaceId is set', async () => {
     workspaceClient.load.mockResolvedValueOnce({
-      workspace_id: 'ws-1',
-      created_at: '2025-01-01T00:00:00.000Z',
-      updated_at: '2025-01-01T00:00:00.000Z',
       files: {
         '/workspace/persisted.txt': {
           content: Buffer.from('saved').toString('base64'),

x-pack/platform/plugins/shared/agent_builder/server/services/execution/filesystem/workspace_volume.test.ts

@@ -5,20 +5,15 @@
  * 2.0.
  */
 
-import type { IWorkspaceClient, WorkspaceDocument } from '../../workspaces';
+import type { IWorkspaceClient, WorkspaceFile, WorkspaceSnapshot } from '../../workspaces';
 import { WorkspaceVolume } from './workspace_volume';
 
 const mockWorkspaceClient = (): jest.Mocked<IWorkspaceClient> => ({
   load: jest.fn().mockResolvedValue(undefined),
   save: jest.fn().mockResolvedValue(undefined),
 });
 
-const persistedDoc = (files: WorkspaceDocument['files']): WorkspaceDocument => ({
-  workspace_id: 'ws-test',
-  created_at: '2025-01-01T00:00:00.000Z',
-  updated_at: '2025-01-01T00:00:00.000Z',
-  files,
-});
+const persistedDoc = (files: Record<string, WorkspaceFile>): WorkspaceSnapshot => ({ files });
 
 describe('WorkspaceVolume', () => {
   describe('getOrCreateWorkspaceId', () => {

x-pack/platform/plugins/shared/agent_builder/server/services/workspaces/client/storage.ts

@@ -18,6 +18,7 @@ const storageSettings = {
   schema: {
     properties: {
       workspace_id: types.keyword({}),
+      schema_version: types.long({}),
       created_at: types.date({}),
       updated_at: types.date({}),
       // Never queried - Disable dynamic mapping to avoid explosions from arbitrary path keys

x-pack/platform/plugins/shared/agent_builder/server/services/workspaces/client/workspace_client.test.ts

@@ -7,7 +7,7 @@
 
 import type { WorkspaceStorage } from './storage';
 import { WorkspaceClient } from './workspace_client';
-import type { WorkspaceDocument } from '../types';
+import { WORKSPACE_SCHEMA_VERSION, type WorkspaceDocument } from '../types';
 
 const createMockStorage = () => {
   const get = jest.fn();
@@ -21,23 +21,26 @@ const createMockStorage = () => {
 
 describe('WorkspaceClient', () => {
   describe('load', () => {
-    it('returns the document when it exists', async () => {
+    it('returns the workspace snapshot when the document exists', async () => {
       const { storage, get } = createMockStorage();
+      const files = {
+        '/workspace/a.txt': {
+          content: 'aGVsbG8=',
+          mode: 0o644,
+          mtime: '2025-01-01T00:00:00.000Z',
+        },
+      };
       const doc: WorkspaceDocument = {
         workspace_id: 'ws-1',
+        schema_version: WORKSPACE_SCHEMA_VERSION,
         created_at: '2025-01-01T00:00:00.000Z',
         updated_at: '2025-01-01T00:00:00.000Z',
-        files: {
-          '/workspace/a.txt': {
-            content: 'aGVsbG8=',
-            mode: 0o644,
-            mtime: '2025-01-01T00:00:00.000Z',
-          },
-        },
+        files,
       };
       get.mockResolvedValue({ _source: doc });
       const client = new WorkspaceClient({ storage });
-      expect(await client.load('ws-1')).toEqual(doc);
+      // load() returns the public snapshot shape (no schema_version/timestamps).
+      expect(await client.load('ws-1')).toEqual({ files });
       expect(get).toHaveBeenCalledWith({ id: 'ws-1' });
     });
 
@@ -75,6 +78,7 @@ describe('WorkspaceClient', () => {
       const arg = index.mock.calls[0][0];
       expect(arg.id).toBe('ws-2');
       expect(arg.document.workspace_id).toBe('ws-2');
+      expect(arg.document.schema_version).toBe(WORKSPACE_SCHEMA_VERSION);
       expect(arg.document.files).toEqual(files);
       expect(typeof arg.document.updated_at).toBe('string');
       expect(typeof arg.document.created_at).toBe('string');
@@ -86,6 +90,7 @@ describe('WorkspaceClient', () => {
       get.mockResolvedValue({
         _source: {
           workspace_id: 'ws-3',
+          schema_version: WORKSPACE_SCHEMA_VERSION,
           created_at: originalCreated,
           updated_at: '2024-12-25T00:00:00.000Z',
           files: {},

x-pack/platform/plugins/shared/agent_builder/server/services/workspaces/client/workspace_client.ts

@@ -6,10 +6,15 @@
  */
 
 import type { WorkspaceStorage } from './storage';
-import type { WorkspaceDocument, WorkspaceFile } from '../types';
+import {
+  WORKSPACE_SCHEMA_VERSION,
+  type WorkspaceDocument,
+  type WorkspaceFile,
+  type WorkspaceSnapshot,
+} from '../types';
 
 export interface IWorkspaceClient {
-  load(workspaceId: string): Promise<WorkspaceDocument | undefined>;
+  load(workspaceId: string): Promise<WorkspaceSnapshot | undefined>;
   save(workspaceId: string, files: Record<string, WorkspaceFile>): Promise<void>;
 }
 
@@ -20,27 +25,35 @@ export class WorkspaceClient implements IWorkspaceClient {
     this.storage = storage;
   }
 
-  async load(workspaceId: string): Promise<WorkspaceDocument | undefined> {
-    try {
-      const response = await this.storage.getClient().get({ id: workspaceId });
-      return response._source as WorkspaceDocument | undefined;
-    } catch (err) {
-      if ((err as { statusCode?: number }).statusCode === 404) {
-        return undefined;
-      }
-      throw err;
-    }
+  async load(workspaceId: string): Promise<WorkspaceSnapshot | undefined> {
+    const doc = await this.loadDocument(workspaceId);
+    if (!doc) return undefined;
+    return { files: doc.files };
   }
 
   async save(workspaceId: string, files: Record<string, WorkspaceFile>): Promise<void> {
     const now = new Date().toISOString();
-    const existing = await this.load(workspaceId);
+    const existing = await this.loadDocument(workspaceId);
     const document: WorkspaceDocument = {
       workspace_id: workspaceId,
+      schema_version: WORKSPACE_SCHEMA_VERSION,
       created_at: existing?.created_at ?? now,
       updated_at: now,
       files,
     };
     await this.storage.getClient().index({ id: workspaceId, document });
   }
+
+  /** Internal — full document fetch including metadata. */
+  private async loadDocument(workspaceId: string): Promise<WorkspaceDocument | undefined> {
+    try {
+      const response = await this.storage.getClient().get({ id: workspaceId });
+      return response._source as WorkspaceDocument | undefined;
+    } catch (err) {
+      if ((err as { statusCode?: number }).statusCode === 404) {
+        return undefined;
+      }
+      throw err;
+    }
+  }
 }

x-pack/platform/plugins/shared/agent_builder/server/services/workspaces/index.ts

@@ -7,4 +7,4 @@
 
 export { WorkspaceClient, type IWorkspaceClient } from './client/workspace_client';
 export { createStorage as createWorkspaceStorage, workspaceIndexName } from './client/storage';
-export type { WorkspaceDocument, WorkspaceFile } from './types';
+export type { WorkspaceFile, WorkspaceSnapshot } from './types';

x-pack/platform/plugins/shared/agent_builder/server/services/workspaces/types.ts

@@ -16,12 +16,22 @@ export interface WorkspaceFile {
 }
 
 /**
- * A workspace document persisted in `chatSystemIndex('workspaces')`.
+ * Public-facing view of a loaded workspace
+ */
+export interface WorkspaceSnapshot {
+  files: Record<string, WorkspaceFile>;
+}
+
+/**
+ * Internal — the ES document shape persisted in the workspaces index.
  * `files` keys are absolute paths within `/workspace` (e.g. `/workspace/notes.txt`).
  */
 export interface WorkspaceDocument {
   workspace_id: string;
+  schema_version: number;
   created_at: string;
   updated_at: string;
   files: Record<string, WorkspaceFile>;
 }
+
+export const WORKSPACE_SCHEMA_VERSION = 1;