agentxjs 2.9.0-dev-20260317060607 → 2.9.0-dev-20260317112104

package/src/handlers/__tests__/workspace-handler.test.ts

@@ -1,7 +1,7 @@
 /**
- * Workspace RPC Handler Tests
+ * OS RPC Handler Tests
  *
- * Verifies the server-side workspace.list/read/write handlers
+ * Verifies the server-side os.list/read/write handlers
  * work correctly through the RpcHandlerRegistry.
  */
 
@@ -10,23 +10,23 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { RpcHandlerRegistry } from "../../RpcHandlerRegistry";
-import { registerWorkspaceHandlers } from "../workspace";
+import { registerOSHandlers } from "../workspace";
 
 let tempDir: string;
 let registry: RpcHandlerRegistry;
 
-// Minimal runtime mock with real workspace
-function createMockRuntime(workspacesDir: string) {
-  const { LocalWorkspaceProvider } = require("@agentxjs/node-platform/workspace");
-  const workspaceProvider = new LocalWorkspaceProvider(workspacesDir);
+// Minimal runtime mock with real OS
+function createMockRuntime(basePath: string) {
+  const { LocalOSProvider } = require("@agentxjs/node-platform");
+  const osProvider = new LocalOSProvider(basePath);
 
   return {
     platform: {
-      workspaceProvider,
+      osProvider,
       imageRepository: {
         findImageById: async (imageId: string) => {
           if (imageId === "img_test") {
-            return { imageId: "img_test", workspaceId: "ws_test" };
+            return { imageId: "img_test", osId: "os_test" };
           }
           return null;
         },
@@ -36,26 +36,26 @@ function createMockRuntime(workspacesDir: string) {
 }
 
 beforeEach(async () => {
-  tempDir = await mkdtemp(join(tmpdir(), "agentx-ws-handler-test-"));
+  tempDir = await mkdtemp(join(tmpdir(), "agentx-os-handler-test-"));
   registry = new RpcHandlerRegistry();
-  registerWorkspaceHandlers(registry);
+  registerOSHandlers(registry);
 });
 
 afterEach(async () => {
   await rm(tempDir, { recursive: true, force: true });
 });
 
-describe("workspace.list RPC handler", () => {
-  test("returns files from workspace directory", async () => {
-    // Create workspace dir and files
-    const wsDir = join(tempDir, "ws_test");
+describe("os.list RPC handler", () => {
+  test("returns files from OS directory", async () => {
+    // Create OS dir and files
+    const osDir = join(tempDir, "os_test");
     const { mkdir } = await import("node:fs/promises");
-    await mkdir(wsDir, { recursive: true });
-    await writeFile(join(wsDir, "hello.txt"), "world");
-    await writeFile(join(wsDir, "test.js"), "console.log('hi')");
+    await mkdir(osDir, { recursive: true });
+    await writeFile(join(osDir, "hello.txt"), "world");
+    await writeFile(join(osDir, "test.js"), "console.log('hi')");
 
     const runtime = createMockRuntime(tempDir);
-    const result = await registry.handle(runtime, "workspace.list", {
+    const result = await registry.handle(runtime, "os.list", {
       imageId: "img_test",
       path: ".",
     });
@@ -69,13 +69,13 @@ describe("workspace.list RPC handler", () => {
     }
   });
 
-  test("returns empty array for empty workspace", async () => {
-    const wsDir = join(tempDir, "ws_test");
+  test("returns empty array for empty OS directory", async () => {
+    const osDir = join(tempDir, "os_test");
     const { mkdir } = await import("node:fs/promises");
-    await mkdir(wsDir, { recursive: true });
+    await mkdir(osDir, { recursive: true });
 
     const runtime = createMockRuntime(tempDir);
-    const result = await registry.handle(runtime, "workspace.list", {
+    const result = await registry.handle(runtime, "os.list", {
       imageId: "img_test",
     });
 
@@ -87,7 +87,7 @@ describe("workspace.list RPC handler", () => {
 
   test("returns error for unknown imageId", async () => {
     const runtime = createMockRuntime(tempDir);
-    const result = await registry.handle(runtime, "workspace.list", {
+    const result = await registry.handle(runtime, "os.list", {
       imageId: "img_unknown",
     });
 
@@ -95,15 +95,15 @@ describe("workspace.list RPC handler", () => {
   });
 });
 
-describe("workspace.read RPC handler", () => {
+describe("os.read RPC handler", () => {
   test("reads file content", async () => {
-    const wsDir = join(tempDir, "ws_test");
+    const osDir = join(tempDir, "os_test");
     const { mkdir } = await import("node:fs/promises");
-    await mkdir(wsDir, { recursive: true });
-    await writeFile(join(wsDir, "data.txt"), "hello world");
+    await mkdir(osDir, { recursive: true });
+    await writeFile(join(osDir, "data.txt"), "hello world");
 
     const runtime = createMockRuntime(tempDir);
-    const result = await registry.handle(runtime, "workspace.read", {
+    const result = await registry.handle(runtime, "os.read", {
       imageId: "img_test",
       path: "data.txt",
     });
@@ -115,16 +115,16 @@ describe("workspace.read RPC handler", () => {
   });
 });
 
-describe("workspace.write RPC handler", () => {
+describe("os.write RPC handler", () => {
   test("writes file and can read it back", async () => {
-    const wsDir = join(tempDir, "ws_test");
+    const osDir = join(tempDir, "os_test");
     const { mkdir } = await import("node:fs/promises");
-    await mkdir(wsDir, { recursive: true });
+    await mkdir(osDir, { recursive: true });
 
     const runtime = createMockRuntime(tempDir);
 
     // Write
-    const writeResult = await registry.handle(runtime, "workspace.write", {
+    const writeResult = await registry.handle(runtime, "os.write", {
       imageId: "img_test",
       path: "output.txt",
       content: "written via RPC",
@@ -132,7 +132,7 @@ describe("workspace.write RPC handler", () => {
     expect(writeResult.success).toBe(true);
 
     // Read back
-    const readResult = await registry.handle(runtime, "workspace.read", {
+    const readResult = await registry.handle(runtime, "os.read", {
       imageId: "img_test",
       path: "output.txt",
     });

package/src/handlers/index.ts

@@ -12,7 +12,7 @@ import { registerImageHandlers } from "./image";
 import { registerInstanceHandlers } from "./instance";
 import { registerLLMHandlers } from "./llm";
 import { registerMessageHandlers } from "./message";
-import { registerWorkspaceHandlers } from "./workspace";
+import { registerOSHandlers } from "./workspace";
 
 /**
  * Register all RPC handlers on the registry
@@ -22,5 +22,5 @@ export function registerAll(registry: RpcHandlerRegistry): void {
   registerInstanceHandlers(registry);
   registerMessageHandlers(registry);
   registerLLMHandlers(registry);
-  registerWorkspaceHandlers(registry);
+  registerOSHandlers(registry);
 }

package/src/handlers/workspace.ts

@@ -1,47 +1,47 @@
 /**
- * Workspace RPC Handlers
+ * OS RPC Handlers — exposes AgentOS file operations via RPC
  */
 
 import type { RpcHandlerRegistry } from "../RpcHandlerRegistry";
 import { err, ok } from "../RpcHandlerRegistry";
 
-export function registerWorkspaceHandlers(registry: RpcHandlerRegistry): void {
-  registry.register("workspace.read", async (runtime, params) => {
+export function registerOSHandlers(registry: RpcHandlerRegistry): void {
+  registry.register("os.read", async (runtime, params) => {
     const { imageId, path } = params as { imageId: string; path: string };
-    const wp = runtime.platform.workspaceProvider;
-    if (!wp) return err(-32000, "Workspace not available");
+    const op = runtime.platform.osProvider;
+    if (!op) return err(-32000, "OS not available");
 
     const img = await runtime.platform.imageRepository.findImageById(imageId);
-    if (!img?.workspaceId) return err(404, "Image has no workspace");
+    if (!img?.osId) return err(404, "Image has no OS");
 
-    const ws = await wp.create(img.workspaceId);
-    const content = await ws.read(path);
+    const os = await op.create(img.osId);
+    const content = await os.fs.read(path);
     return ok({ content });
   });
 
-  registry.register("workspace.list", async (runtime, params) => {
+  registry.register("os.list", async (runtime, params) => {
     const { imageId, path } = params as { imageId: string; path?: string };
-    const wp = runtime.platform.workspaceProvider;
-    if (!wp) return err(-32000, "Workspace not available");
+    const op = runtime.platform.osProvider;
+    if (!op) return err(-32000, "OS not available");
 
     const img = await runtime.platform.imageRepository.findImageById(imageId);
-    if (!img?.workspaceId) return err(404, "Image has no workspace");
+    if (!img?.osId) return err(404, "Image has no OS");
 
-    const ws = await wp.create(img.workspaceId);
-    const files = await ws.list(path ?? ".");
+    const os = await op.create(img.osId);
+    const files = await os.fs.list(path ?? ".");
     return ok({ files });
   });
 
-  registry.register("workspace.write", async (runtime, params) => {
+  registry.register("os.write", async (runtime, params) => {
     const { imageId, path, content } = params as { imageId: string; path: string; content: string };
-    const wp = runtime.platform.workspaceProvider;
-    if (!wp) return err(-32000, "Workspace not available");
+    const op = runtime.platform.osProvider;
+    if (!op) return err(-32000, "OS not available");
 
     const img = await runtime.platform.imageRepository.findImageById(imageId);
-    if (!img?.workspaceId) return err(404, "Image has no workspace");
+    if (!img?.osId) return err(404, "Image has no OS");
 
-    const ws = await wp.create(img.workspaceId);
-    await ws.write(path, content);
+    const os = await op.create(img.osId);
+    await os.fs.write(path, content);
     return ok({ success: true });
   });
 }

package/src/index.ts

@@ -227,16 +227,16 @@ export type {
   FileBlock,
   FileTreeEntry,
   ImageBlock,
+  OS,
+  OSState,
   PresentationMetrics,
   PresentationOptions,
+  PresentationOS,
   PresentationState,
-  PresentationWorkspace,
   TextBlock,
   ThinkingBlock,
   ToolBlock,
   UserConversation,
-  Workspace,
-  WorkspaceState,
 } from "./presentation";
 export {
   addUserConversation,

package/src/namespaces/presentations.ts

@@ -7,19 +7,19 @@
  */
 
 import { messagesToConversations, Presentation, type PresentationOptions } from "../presentation";
-import type { PresentationWorkspace } from "../presentation/types";
+import type { PresentationOS } from "../presentation/types";
 import type { AgentX, PresentationNamespace, SessionNamespace } from "../types";
 
 /**
- * Workspace resolver — given an imageId, returns a PresentationWorkspace or null.
+ * OS resolver — given an imageId, returns a PresentationOS or null.
  * Provided by the client (local or remote) to decouple from runtime internals.
  */
-export type WorkspaceResolver = (imageId: string) => Promise<PresentationWorkspace | null>;
+export type OSResolver = (imageId: string) => Promise<PresentationOS | null>;
 
 export function createPresentations(
   agentx: AgentX,
   sessionNs: SessionNamespace,
-  workspaceResolver?: WorkspaceResolver
+  osResolver?: OSResolver
 ): PresentationNamespace {
   const instances = new Map<string, Presentation>();
 
@@ -34,13 +34,13 @@ export function createPresentations(
         return existing;
       }
 
-      // Resolve workspace for this image
-      const workspace = workspaceResolver ? await workspaceResolver(imageId) : null;
+      // Resolve OS for this image
+      const os = osResolver ? await osResolver(imageId) : null;
 
       // Create new from history
       const messages = await sessionNs.getMessages(imageId);
       const conversations = messagesToConversations(messages);
-      const presentation = new Presentation(agentx, imageId, options, conversations, workspace);
+      const presentation = new Presentation(agentx, imageId, options, conversations, os);
 
       instances.set(imageId, presentation);
 

package/src/presentation/Presentation.ts

@@ -9,7 +9,7 @@
  * // Read state
  * pres.conversations  // message history
  * pres.status         // "idle" | "submitted" | "thinking" | "responding" | "executing"
- * pres.workspace      // { files, read, write, list } or null
+ * pres.os             // { files, read, write, list } or null
  *
  * // Subscribe (works with useSyncExternalStore)
  * const unsub = pres.subscribe(() => rerender());
@@ -30,8 +30,8 @@ import type {
   ConnectionState,
   Conversation,
   PresentationMetrics,
+  PresentationOS,
   PresentationState,
-  PresentationWorkspace,
 } from "./types";
 import { initialPresentationState } from "./types";
 
@@ -40,9 +40,9 @@ import { initialPresentationState } from "./types";
 // ============================================================================
 
 /**
- * Workspace — file tree + operations, unified.
+ * OS view — file tree + operations, unified.
  */
-export interface Workspace {
+export interface OS {
   /** Current file tree (real-time updates) */
   readonly files: readonly import("./types").FileTreeEntry[];
   /** Read file content */
@@ -72,18 +72,18 @@ export class Presentation {
   private _listeners = new Set<() => void>();
   private _legacyHandlers = new Set<(state: PresentationState) => void>();
   private _eventUnsubscribe: (() => void) | null = null;
-  private _workspaceOps: PresentationWorkspace | null;
+  private _osOps: PresentationOS | null;
 
   constructor(
     agentx: AgentX,
     instanceId: string,
     options?: PresentationOptions,
     initialConversations?: Conversation[],
-    workspace?: PresentationWorkspace | null
+    os?: PresentationOS | null
   ) {
     this._agentx = agentx;
     this._instanceId = instanceId;
-    this._workspaceOps = workspace ?? null;
+    this._osOps = os ?? null;
     this._state = initialConversations?.length
       ? { ...initialPresentationState, conversations: initialConversations }
       : createInitialState();
@@ -97,9 +97,9 @@ export class Presentation {
     this._subscribeToEvents();
 
     // Load initial workspace file tree
-    if (this._workspaceOps) {
-      this._workspaceOps.list(".").then((files) => {
-        this._state = { ...this._state, workspace: { files } };
+    if (this._osOps) {
+      this._osOps.list(".").then((files) => {
+        this._state = { ...this._state, os: { files } };
         this._notify();
       });
     }
@@ -127,14 +127,14 @@ export class Presentation {
     return this._state.metrics;
   }
 
-  /** Workspace — file tree + operations. null if agent has no workspace. */
-  get workspace(): Workspace | null {
-    if (!this._workspaceOps) return null;
-    const ops = this._workspaceOps;
-    const wsState = this._state.workspace;
+  /** OS — file tree + operations. null if agent has no OS. */
+  get os(): OS | null {
+    if (!this._osOps) return null;
+    const ops = this._osOps;
+    const osState = this._state.os;
     return {
       get files() {
-        return wsState?.files ?? [];
+        return osState?.files ?? [];
       },
       read: (path: string) => ops.read(path),
       write: (path: string, content: string) => ops.write(path, content),

package/src/presentation/__tests__/workspace-init.test.ts

@@ -1,10 +1,10 @@
 /**
- * Workspace Initialization Tests — New Presentation API
+ * OS Initialization Tests — New Presentation API
  */
 
 import { describe, expect, mock, test } from "bun:test";
 import { Presentation } from "../Presentation";
-import type { PresentationWorkspace } from "../types";
+import type { PresentationOS } from "../types";
 
 function createMockAgentX() {
   return {
@@ -19,41 +19,41 @@ function createMockAgentX() {
   } as any;
 }
 
-describe("Workspace initialization in Presentation", () => {
-  test("constructor calls workspace.list('.') and populates workspace.files", async () => {
+describe("OS initialization in Presentation", () => {
+  test("constructor calls os.list('.') and populates os.files", async () => {
     const mockFiles = [
       { name: "src", path: "src", type: "directory" as const },
       { name: "package.json", path: "package.json", type: "file" as const },
     ];
 
-    const mockWorkspace: PresentationWorkspace = {
+    const mockOS: PresentationOS = {
       read: mock(() => Promise.resolve("")),
       write: mock(() => Promise.resolve()),
       list: mock(() => Promise.resolve(mockFiles)),
     };
 
     const ax = createMockAgentX();
-    const pres = new Presentation(ax, "img_test", undefined, undefined, mockWorkspace);
+    const pres = new Presentation(ax, "img_test", undefined, undefined, mockOS);
 
     await new Promise((resolve) => setTimeout(resolve, 50));
 
-    expect(mockWorkspace.list).toHaveBeenCalledWith(".");
-    expect(pres.workspace).not.toBeNull();
-    expect(pres.workspace!.files).toEqual(mockFiles);
+    expect(mockOS.list).toHaveBeenCalledWith(".");
+    expect(pres.os).not.toBeNull();
+    expect(pres.os!.files).toEqual(mockFiles);
   });
 
-  test("workspace is null when no workspace provided", async () => {
+  test("os is null when no OS provided", async () => {
     const ax = createMockAgentX();
     const pres = new Presentation(ax, "img_test", undefined, undefined, null);
 
     await new Promise((resolve) => setTimeout(resolve, 50));
 
-    expect(pres.workspace).toBeNull();
+    expect(pres.os).toBeNull();
   });
 
-  test("subscribe fires on workspace update", async () => {
+  test("subscribe fires on OS update", async () => {
     const mockFiles = [{ name: "test.txt", path: "test.txt", type: "file" as const }];
-    const mockWorkspace: PresentationWorkspace = {
+    const mockOS: PresentationOS = {
       read: mock(() => Promise.resolve("")),
       write: mock(() => Promise.resolve()),
       list: mock(() => Promise.resolve(mockFiles)),
@@ -61,7 +61,7 @@ describe("Workspace initialization in Presentation", () => {
 
     let notified = false;
     const ax = createMockAgentX();
-    const pres = new Presentation(ax, "img_test", undefined, undefined, mockWorkspace);
+    const pres = new Presentation(ax, "img_test", undefined, undefined, mockOS);
     pres.subscribe(() => {
       notified = true;
     });
@@ -69,12 +69,12 @@ describe("Workspace initialization in Presentation", () => {
     await new Promise((resolve) => setTimeout(resolve, 50));
 
     expect(notified).toBe(true);
-    expect(pres.workspace!.files).toEqual(mockFiles);
+    expect(pres.os!.files).toEqual(mockFiles);
   });
 
-  test("workspace_tree event updates workspace.files", async () => {
+  test("workspace_tree event updates os.files", async () => {
     const initialFiles = [{ name: "init.txt", path: "init.txt", type: "file" as const }];
-    const mockWorkspace: PresentationWorkspace = {
+    const mockOS: PresentationOS = {
       read: mock(() => Promise.resolve("")),
       write: mock(() => Promise.resolve()),
       list: mock(() => Promise.resolve(initialFiles)),
@@ -87,10 +87,10 @@ describe("Workspace initialization in Presentation", () => {
       return () => {};
     });
 
-    const pres = new Presentation(ax, "img_test", undefined, undefined, mockWorkspace);
+    const pres = new Presentation(ax, "img_test", undefined, undefined, mockOS);
     await new Promise((resolve) => setTimeout(resolve, 50));
 
-    expect(pres.workspace!.files).toEqual(initialFiles);
+    expect(pres.os!.files).toEqual(initialFiles);
 
     // Simulate workspace_tree event
     const updatedFiles = [
@@ -99,6 +99,6 @@ describe("Workspace initialization in Presentation", () => {
     ];
     eventHandler!({ type: "workspace_tree", timestamp: Date.now(), data: { files: updatedFiles } });
 
-    expect(pres.workspace!.files).toEqual(updatedFiles);
+    expect(pres.os!.files).toEqual(updatedFiles);
   });
 });

package/src/presentation/__tests__/workspace.test.ts

@@ -1,10 +1,10 @@
 /**
- * Presentation Workspace Tests
+ * Presentation OS Tests
  *
- * Tests the workspace integration in the Presentation layer:
- * 1. Reducer handles workspace_tree events → updates PresentationState.workspace
- * 2. PresentationWorkspace operations (read/write/list)
- * 3. Initial state has workspace: null
+ * Tests the OS integration in the Presentation layer:
+ * 1. Reducer handles workspace_tree events → updates PresentationState.os
+ * 2. PresentationOS operations (read/write/list)
+ * 3. Initial state has os: null
  */
 
 import { describe, expect, test } from "bun:test";
@@ -15,13 +15,13 @@ import type { FileTreeEntry, PresentationState } from "../types";
 // Reducer: workspace_tree event
 // ============================================================================
 
-describe("Presentation Workspace Reducer", () => {
-  test("initial state has workspace: null", () => {
+describe("Presentation OS Reducer", () => {
+  test("initial state has os: null", () => {
     const state = createInitialState();
-    expect(state.workspace).toBeNull();
+    expect(state.os).toBeNull();
   });
 
-  test("workspace_tree event sets workspace.files", () => {
+  test("workspace_tree event sets os.files", () => {
     const state = createInitialState();
     const files: FileTreeEntry[] = [
       { name: "src", path: "src", type: "directory" },
@@ -35,14 +35,14 @@ describe("Presentation Workspace Reducer", () => {
     };
 
     const newState = presentationReducer(state, event as any);
-    expect(newState.workspace).not.toBeNull();
-    expect(newState.workspace!.files).toEqual(files);
+    expect(newState.os).not.toBeNull();
+    expect(newState.os!.files).toEqual(files);
   });
 
   test("workspace_tree event replaces previous files", () => {
     const state: PresentationState = {
       ...createInitialState(),
-      workspace: {
+      os: {
         files: [{ name: "old.txt", path: "old.txt", type: "file" }],
       },
     };
@@ -59,8 +59,8 @@ describe("Presentation Workspace Reducer", () => {
     };
 
     const newState = presentationReducer(state, event as any);
-    expect(newState.workspace!.files).toEqual(newFiles);
-    expect(newState.workspace!.files).not.toContainEqual({
+    expect(newState.os!.files).toEqual(newFiles);
+    expect(newState.os!.files).not.toContainEqual({
       name: "old.txt",
       path: "old.txt",
       type: "file",
@@ -80,10 +80,10 @@ describe("Presentation Workspace Reducer", () => {
     const newState = presentationReducer(state, event as any);
     expect(newState.status).toBe("responding");
     expect(newState.conversations).toEqual([]);
-    expect(newState.workspace).toEqual({ files: [] });
+    expect(newState.os).toEqual({ files: [] });
   });
 
-  test("unknown event does not create workspace state", () => {
+  test("unknown event does not create os state", () => {
     const state = createInitialState();
     const event = {
       type: "some_unknown_event",
@@ -92,7 +92,7 @@ describe("Presentation Workspace Reducer", () => {
     };
 
     const newState = presentationReducer(state, event as any);
-    expect(newState.workspace).toBeNull();
+    expect(newState.os).toBeNull();
     expect(newState).toBe(state); // Same reference = no change
   });
 });

package/src/presentation/index.ts

@@ -5,9 +5,9 @@
  */
 
 export {
+  type OS,
   Presentation,
   type PresentationOptions,
-  type Workspace,
 } from "./Presentation";
 export {
   addUserConversation,
@@ -24,9 +24,10 @@ export type {
   FileBlock,
   FileTreeEntry,
   ImageBlock,
+  OSState,
   PresentationMetrics,
+  PresentationOS,
   PresentationState,
-  PresentationWorkspace,
   SessionMetrics,
   TextBlock,
   ThinkingBlock,
@@ -34,6 +35,5 @@ export type {
   ToolBlock,
   TurnMetrics,
   UserConversation,
-  WorkspaceState,
 } from "./types";
 export { initialMetrics, initialPresentationState, initialSessionMetrics } from "./types";

package/src/presentation/reducer.ts

@@ -490,7 +490,7 @@ function handleWorkspaceTree(
 ): PresentationState {
   return {
     ...state,
-    workspace: { files: data.files },
+    os: { files: data.files },
   };
 }