@kb-labs/adapters 0.5.0

package/packages/adapters-workspace-agent/src/__tests__/adapter.test.ts

@@ -0,0 +1,212 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AgentWorkspaceAdapter } from '../index.js';
+import type { MaterializeWorkspaceRequest } from '@kb-labs/core-platform';
+
+// ── fetch mock helpers ────────────────────────────────────────────────────────
+
+function mockFetchOk(result: unknown): void {
+  vi.stubGlobal('fetch', vi.fn(async () => ({
+    ok: true,
+    json: async () => ({ result }),
+    text: async () => JSON.stringify({ result }),
+  })));
+}
+
+function mockFetchError(status: number, body: string): void {
+  vi.stubGlobal('fetch', vi.fn(async () => ({
+    ok: false,
+    status,
+    text: async () => body,
+  })));
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────────
+
+describe('AgentWorkspaceAdapter', () => {
+  let cacheDir: string;
+
+  beforeEach(async () => {
+    cacheDir = await mkdtemp(join(tmpdir(), 'ws-agent-test-'));
+  });
+
+  afterEach(async () => {
+    vi.unstubAllGlobals();
+    await rm(cacheDir, { recursive: true, force: true });
+  });
+
+  describe('materialize', () => {
+    it('calls /internal/dispatch with filesystem.fetchWorkspace', async () => {
+      const files = [{ path: 'index.ts', content: 'export {}' }];
+      mockFetchOk(files);
+
+      const adapter = new AgentWorkspaceAdapter({
+        gatewayUrl: 'http://localhost:4000',
+        internalSecret: 'test-secret',
+        namespaceId: 'ns-1',
+        cacheDir,
+      });
+
+      const req: MaterializeWorkspaceRequest = { workspaceId: 'ws-test', basePath: '/workspace' };
+      await adapter.materialize(req);
+
+      const fetchMock = vi.mocked(fetch);
+      expect(fetchMock).toHaveBeenCalledOnce();
+      const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+      expect(url).toBe('http://localhost:4000/internal/dispatch');
+      expect((init.headers as Record<string, string>)['x-internal-secret']).toBe('test-secret');
+      const body = JSON.parse(init.body as string);
+      expect(body.adapter).toBe('filesystem');
+      expect(body.method).toBe('fetchWorkspace');
+      expect(body.namespaceId).toBe('ns-1');
+    });
+
+    it('writes fetched files to cacheDir/workspaceId/', async () => {
+      const files = [
+        { path: 'index.ts', content: 'export {}' },
+        { path: join('src', 'app.ts'), content: 'const x = 1;' },
+      ];
+      mockFetchOk(files);
+
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+
+      const descriptor = await adapter.materialize({ workspaceId: 'ws-abc', basePath: '.' });
+
+      expect(descriptor.workspaceId).toBe('ws-abc');
+      expect(descriptor.status).toBe('ready');
+      expect(descriptor.rootPath).toBe(join(cacheDir, 'ws-abc'));
+      expect(descriptor.provider).toBe('workspace-agent');
+
+      const indexContent = await readFile(join(cacheDir, 'ws-abc', 'index.ts'), 'utf-8');
+      expect(indexContent).toBe('export {}');
+
+      const appContent = await readFile(join(cacheDir, 'ws-abc', 'src', 'app.ts'), 'utf-8');
+      expect(appContent).toBe('const x = 1;');
+    });
+
+    it('generates workspaceId when not provided', async () => {
+      mockFetchOk([]);
+
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+      const descriptor = await adapter.materialize({ basePath: '.' });
+
+      expect(descriptor.workspaceId).toMatch(/^ws_/);
+    });
+
+    it('stores file count in descriptor metadata', async () => {
+      const files = [
+        { path: 'a.ts', content: 'x' },
+        { path: 'b.ts', content: 'y' },
+        { path: 'c.ts', content: 'z' },
+      ];
+      mockFetchOk(files);
+
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+      const descriptor = await adapter.materialize({ workspaceId: 'ws-meta', basePath: '.' });
+
+      expect(descriptor.metadata?.fileCount).toBe(3);
+    });
+
+    it('throws when dispatch returns non-array', async () => {
+      mockFetchOk({ notAnArray: true });
+
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+
+      await expect(adapter.materialize({ workspaceId: 'ws-bad', basePath: '.' }))
+        .rejects.toThrow('expected array of files');
+    });
+
+    it('throws when fetch returns non-ok status', async () => {
+      mockFetchError(503, '{"error":"No host connected"}');
+
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+
+      await expect(adapter.materialize({ workspaceId: 'ws-err', basePath: '.' }))
+        .rejects.toThrow('dispatch failed (503)');
+    });
+
+    it('passes hostId when configured', async () => {
+      mockFetchOk([]);
+
+      const adapter = new AgentWorkspaceAdapter({
+        cacheDir,
+        internalSecret: 'secret',
+        namespaceId: 'ns-x',
+        hostId: 'host-specific',
+      });
+
+      await adapter.materialize({ workspaceId: 'ws-host', basePath: '.' });
+
+      const fetchMock = vi.mocked(fetch);
+      const body = JSON.parse((fetchMock.mock.calls[0]![1] as RequestInit).body as string);
+      expect(body.hostId).toBe('host-specific');
+    });
+
+    it('uses basePath for remotePath', async () => {
+      mockFetchOk([]);
+
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+      await adapter.materialize({ workspaceId: 'ws-path', basePath: '/home/user/myproject' });
+
+      const fetchMock = vi.mocked(fetch);
+      const body = JSON.parse((fetchMock.mock.calls[0]![1] as RequestInit).body as string);
+      expect(body.args).toEqual(['/home/user/myproject']);
+    });
+  });
+
+  describe('attach / getStatus / release', () => {
+    it('attach returns mountPath', async () => {
+      mockFetchOk([]);
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+      await adapter.materialize({ workspaceId: 'ws-1', basePath: '.' });
+
+      const att = await adapter.attach({ workspaceId: 'ws-1', environmentId: 'env-1' });
+      expect(att.workspaceId).toBe('ws-1');
+      expect(att.mountPath).toBe('/workspace');
+    });
+
+    it('getStatus returns ready after materialize', async () => {
+      mockFetchOk([]);
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+      await adapter.materialize({ workspaceId: 'ws-2', basePath: '.' });
+
+      const status = await adapter.getStatus('ws-2');
+      expect(status.status).toBe('ready');
+    });
+
+    it('getStatus throws for unknown workspace', async () => {
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+      await expect(adapter.getStatus('unknown')).rejects.toThrow('Workspace not found');
+    });
+
+    it('release transitions status to released', async () => {
+      mockFetchOk([]);
+      const adapter = new AgentWorkspaceAdapter({ cacheDir, internalSecret: 'secret' });
+      await adapter.materialize({ workspaceId: 'ws-3', basePath: '.' });
+      await adapter.release('ws-3');
+
+      const status = await adapter.getStatus('ws-3');
+      expect(status.status).toBe('released');
+    });
+  });
+
+  describe('getCapabilities', () => {
+    it('reports remote:true', () => {
+      const adapter = new AgentWorkspaceAdapter({ internalSecret: 'secret' });
+      const caps = adapter.getCapabilities();
+      expect(caps.custom?.remote).toBe(true);
+      expect(caps.supportsAttach).toBe(true);
+    });
+  });
+
+  describe('createAdapter factory', () => {
+    it('exports createAdapter default function', async () => {
+      const mod = await import('../index.js');
+      expect(typeof mod.createAdapter).toBe('function');
+      const adapter = mod.createAdapter({ internalSecret: 'test' });
+      expect(adapter).toBeInstanceOf(AgentWorkspaceAdapter);
+    });
+  });
+});

package/packages/adapters-workspace-agent/src/index.ts

@@ -0,0 +1,220 @@
+/**
+ * @module @kb-labs/adapters-workspace-agent
+ *
+ * IWorkspaceProvider implementation that materializes workspaces by fetching
+ * files from a local machine via Host Agent connected to the Gateway.
+ *
+ * Usage in kb.config.json (cloud mode):
+ *   "platform": {
+ *     "adapters": {
+ *       "workspace": "@kb-labs/adapters-workspace-agent"
+ *     },
+ *     "adapterOptions": {
+ *       "workspace": {
+ *         "gatewayUrl": "http://localhost:4000",
+ *         "namespaceId": "default",
+ *         "cacheDir": ".kb/runtime/workspaces"
+ *       }
+ *     }
+ *   }
+ *
+ * The adapter calls filesystem.fetchWorkspace on the connected Host Agent
+ * via Gateway's /internal/dispatch endpoint, writes files to a local cache
+ * dir, and returns a WorkspaceDescriptor with rootPath pointing to that cache.
+ * From that point on, workflow workers and Docker environments use rootPath
+ * as a normal local directory — no knowledge of remote origin.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type {
+  IWorkspaceProvider,
+  MaterializeWorkspaceRequest,
+  WorkspaceDescriptor,
+  AttachWorkspaceRequest,
+  WorkspaceAttachment,
+  WorkspaceStatusResult,
+  WorkspaceProviderCapabilities,
+  WorkspaceStatus,
+} from '@kb-labs/core-platform';
+
+export { manifest } from './manifest.js';
+
+export interface AgentWorkspaceAdapterConfig {
+  /** Gateway base URL. Default: 'http://localhost:4000' */
+  gatewayUrl?: string;
+  /** Shared secret for /internal/dispatch. Read from GATEWAY_INTERNAL_SECRET env if omitted. */
+  internalSecret?: string;
+  /** Gateway namespace to find the host agent in. Default: 'default' */
+  namespaceId?: string;
+  /** Local directory where fetched workspaces are cached. Default: '.kb/runtime/workspaces' */
+  cacheDir?: string;
+  /** Specific hostId to use. If omitted, Gateway picks first connected host in namespace. */
+  hostId?: string;
+}
+
+interface WorkspaceRecord {
+  workspaceId: string;
+  rootPath: string;
+  status: WorkspaceStatus;
+  updatedAt: string;
+}
+
+export class AgentWorkspaceAdapter implements IWorkspaceProvider {
+  private readonly gatewayUrl: string;
+  private readonly internalSecret: string;
+  private readonly namespaceId: string;
+  private readonly cacheDir: string;
+  private readonly hostId?: string;
+  private readonly records = new Map<string, WorkspaceRecord>();
+
+  constructor(config: AgentWorkspaceAdapterConfig = {}) {
+    this.gatewayUrl = (config.gatewayUrl ?? 'http://localhost:4000').replace(/\/$/, '');
+    this.internalSecret = config.internalSecret ?? process.env['GATEWAY_INTERNAL_SECRET'] ?? '';
+    this.namespaceId = config.namespaceId ?? 'default';
+    this.cacheDir = config.cacheDir ?? '.kb/runtime/workspaces';
+    this.hostId = config.hostId;
+  }
+
+  async materialize(request: MaterializeWorkspaceRequest): Promise<WorkspaceDescriptor> {
+    const workspaceId = request.workspaceId ?? `ws_${randomUUID()}`;
+    const now = new Date().toISOString();
+
+    // Determine which path to fetch from the agent
+    const remotePath = request.basePath ?? request.sourceRef ?? '.';
+
+    // Call filesystem.fetchWorkspace via Gateway /internal/dispatch
+    const files = await this.dispatch('filesystem', 'fetchWorkspace', [remotePath]) as Array<{ path: string; content: string }>;
+
+    if (!Array.isArray(files)) {
+      throw new Error(`AgentWorkspaceAdapter: expected array of files from fetchWorkspace, got ${typeof files}`);
+    }
+
+    // Write files to local cache
+    const rootPath = join(this.cacheDir, workspaceId);
+    await mkdir(rootPath, { recursive: true });
+
+    for (const file of files) {
+      const dest = join(rootPath, file.path);
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, file.content, 'utf-8');
+    }
+
+    const descriptor: WorkspaceDescriptor = {
+      workspaceId,
+      provider: 'workspace-agent',
+      status: 'ready',
+      rootPath,
+      createdAt: now,
+      updatedAt: now,
+      metadata: {
+        sourceRef: request.sourceRef,
+        remotePath,
+        namespaceId: this.namespaceId,
+        fileCount: files.length,
+      },
+    };
+
+    this.records.set(workspaceId, {
+      workspaceId,
+      rootPath,
+      status: 'ready',
+      updatedAt: now,
+    });
+
+    return descriptor;
+  }
+
+  async attach(request: AttachWorkspaceRequest): Promise<WorkspaceAttachment> {
+    const now = new Date().toISOString();
+    const record = this.getRecordOrThrow(request.workspaceId);
+    record.status = 'attached';
+    record.updatedAt = now;
+
+    return {
+      workspaceId: request.workspaceId,
+      environmentId: request.environmentId,
+      mountPath: request.mountPath ?? '/workspace',
+      attachedAt: now,
+      metadata: {
+        rootPath: record.rootPath,
+        readOnly: request.readOnly ?? false,
+      },
+    };
+  }
+
+  async release(workspaceId: string): Promise<void> {
+    const record = this.records.get(workspaceId);
+    if (record) {
+      record.status = 'released';
+      record.updatedAt = new Date().toISOString();
+    }
+    // Cached files kept on disk — GC handled separately
+  }
+
+  async getStatus(workspaceId: string): Promise<WorkspaceStatusResult> {
+    const record = this.getRecordOrThrow(workspaceId);
+    return {
+      workspaceId,
+      status: record.status,
+      updatedAt: record.updatedAt,
+    };
+  }
+
+  getCapabilities(): WorkspaceProviderCapabilities {
+    return {
+      supportsAttach: true,
+      supportsRelease: true,
+      supportsReadOnlyMounts: true,
+      custom: {
+        provider: 'agent',
+        remote: true,
+      },
+    };
+  }
+
+  /**
+   * Call an adapter method on the connected Host Agent via Gateway /internal/dispatch.
+   */
+  private async dispatch(adapter: string, method: string, args: unknown[]): Promise<unknown> {
+    const url = `${this.gatewayUrl}/internal/dispatch`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-internal-secret': this.internalSecret,
+      },
+      body: JSON.stringify({
+        namespaceId: this.namespaceId,
+        hostId: this.hostId,
+        adapter,
+        method,
+        args,
+      }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      throw new Error(
+        `AgentWorkspaceAdapter: dispatch failed (${response.status}): ${text}`,
+      );
+    }
+
+    const json = await response.json() as { result: unknown };
+    return json.result;
+  }
+
+  private getRecordOrThrow(workspaceId: string): WorkspaceRecord {
+    const record = this.records.get(workspaceId);
+    if (!record) { throw new Error(`Workspace not found: ${workspaceId}`); }
+    return record;
+  }
+}
+
+export function createAdapter(config?: AgentWorkspaceAdapterConfig): AgentWorkspaceAdapter {
+  return new AgentWorkspaceAdapter(config);
+}
+
+export default createAdapter;

package/packages/adapters-workspace-agent/src/manifest.ts

@@ -0,0 +1,36 @@
+import type { AdapterManifest } from '@kb-labs/core-platform';
+
+export const manifest: AdapterManifest = {
+  manifestVersion: '1.0.0',
+  id: 'agent-workspace-provider',
+  name: 'Agent Workspace Provider',
+  version: '0.1.0',
+  description: 'Workspace provider that fetches files from a local machine via Host Agent connected to the Gateway',
+  author: 'KB Labs Team',
+  license: 'KBPL-1.1',
+  type: 'core',
+  implements: 'IWorkspaceProvider',
+  contexts: ['workspace'],
+  capabilities: {
+    custom: {
+      provider: 'agent',
+      remote: true,
+    },
+  },
+  configSchema: {
+    namespaceId: {
+      type: 'string',
+      default: 'default',
+      description: 'Gateway namespace to find the connected Host Agent',
+    },
+    cacheDir: {
+      type: 'string',
+      default: '.kb/runtime/workspaces',
+      description: 'Local directory where fetched workspace files are cached',
+    },
+    hostId: {
+      type: 'string',
+      description: 'Specific Host Agent ID to use (optional — defaults to first connected host)',
+    },
+  },
+};

package/packages/adapters-workspace-agent/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/adapters-workspace-agent/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@kb-labs/core-platform": [
+        "../../../kb-labs-core/packages/core-platform/src/index.ts"
+      ],
+      "@kb-labs/core-platform/*": [
+        "../../../kb-labs-core/packages/core-platform/src/*"
+      ]
+    }
+  },
+  "include": ["src"]
+}

package/packages/adapters-workspace-agent/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/manifest.ts'],
+  format: ['esm'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  target: 'es2022',
+  external: [/^@kb-labs\/.*/],
+});

package/packages/adapters-workspace-localfs/README.md

@@ -0,0 +1,9 @@
+# @kb-labs/adapters-workspace-localfs
+
+Local filesystem implementation of `IWorkspaceProvider`.
+
+## Features
+
+- Materialize workspace from existing path or create dedicated directory
+- Attach/release status for environment mount lifecycle
+- Workspace registry persisted for integration with snapshot adapters

package/packages/adapters-workspace-localfs/eslint.config.js

@@ -0,0 +1,2 @@
+import cfg from '@kb-labs/devkit/eslint/node.js';
+export default cfg;

package/packages/adapters-workspace-localfs/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kb-labs/adapters-workspace-localfs",
+  "version": "0.5.0",
+  "description": "Local filesystem adapter implementing IWorkspaceProvider",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix"
+  },
+  "peerDependencies": {
+    "@kb-labs/core-platform": "*"
+  },
+  "devDependencies": {
+    "@kb-labs/core-platform": "link:../../../../platform/kb-labs-core/packages/core-platform",
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "rimraf": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}

package/packages/adapters-workspace-localfs/src/index.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { mkdtemp, rm } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { LocalFsWorkspaceAdapter } from './index.js';
+
+describe('LocalFsWorkspaceAdapter', () => {
+  it('materializes and attaches workspace', async () => {
+    const tmp = await mkdtemp(path.join(os.tmpdir(), 'kb-workspace-'));
+    try {
+      const adapter = new LocalFsWorkspaceAdapter({ workspace: { cwd: tmp } });
+      const workspace = await adapter.materialize({ basePath: './demo' });
+      expect(workspace.status).toBe('ready');
+
+      const attachment = await adapter.attach({
+        workspaceId: workspace.workspaceId,
+        environmentId: 'env_1',
+      });
+      expect(attachment.mountPath).toBe('/workspace');
+
+      const status = await adapter.getStatus(workspace.workspaceId);
+      expect(status.status).toBe('attached');
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+});