@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.10

package/src/adapter/cloudflare/workspace/scoped-workspace.ts

@@ -0,0 +1,376 @@
+import type {
+  WorkspaceAdminPort,
+  WorkspaceFileInfo,
+  WorkspacePort,
+  WorkspaceQuota,
+  WorkspaceUsage,
+} from "../../../kernel/bindings";
+import type {
+  WorkspaceConditionalWriteResult,
+  WorkspaceFileVersion,
+} from "./publisher";
+
+const USAGE_PAGE_SIZE = 256;
+const UNCONFIGURED_QUOTA: WorkspaceQuota = Object.freeze({
+  maxFiles: null,
+  maxTotalBytes: null,
+  maxFileBytes: null,
+});
+
+function normalizePath(path: string): string {
+  const value = path.trim().replaceAll("\\", "/");
+  const absolute = value.startsWith("/") ? value : `/${value}`;
+  const parts = absolute.split("/").filter(Boolean);
+  if (parts.some((part) => part === ".." || part === ".")) {
+    throw new Error("workspace path traversal is not allowed");
+  }
+  return `/${parts.join("/")}`;
+}
+
+function isReservedMemoryPath(path: string): boolean {
+  return path === "/shared/memories" || path.startsWith("/shared/memories/");
+}
+
+/**
+ * A Session sees the user's shared mount plus its own directory. All other
+ * paths are interpreted relative to the current Session directory; another
+ * Session can never be named through this port. The Inbox Host also uses this
+ * object to create and remove the Session tree, so callers never need to build
+ * the physical `/sessions/<id>` path themselves.
+ */
+export class ScopedWorkspace implements WorkspacePort, WorkspaceAdminPort {
+  readonly sessionRoot: string;
+
+  constructor(
+    private readonly parent: WorkspacePort,
+    readonly sessionId: string,
+    private readonly quota: WorkspaceQuota = UNCONFIGURED_QUOTA,
+  ) {
+    if (!sessionId || sessionId.includes("/") || sessionId === "." || sessionId === "..") {
+      throw new Error("invalid session id");
+    }
+    this.sessionRoot = `/sessions/${sessionId}`;
+  }
+
+  async ensure(): Promise<void> {
+    await this.parent.mkdir("/shared", { recursive: true });
+    await this.parent.mkdir(this.sessionRoot, { recursive: true });
+  }
+
+  /**
+   * Count only this Session's private tree. User-level `/shared` belongs to the
+   * Inbox and must not be charged once per Chat.
+   */
+  async getUsage(): Promise<WorkspaceUsage> {
+    if (!(await this.parent.exists(this.sessionRoot))) {
+      return { fileCount: 0, directoryCount: 0, totalBytes: 0 };
+    }
+
+    let fileCount = 0;
+    let directoryCount = 0;
+    let totalBytes = 0;
+    const pending = [this.sessionRoot];
+
+    while (pending.length > 0) {
+      const directory = pending.pop()!;
+      let offset = 0;
+      while (true) {
+        const entries = await this.parent.readDir(directory, {
+          limit: USAGE_PAGE_SIZE,
+          offset,
+        });
+        for (const entry of entries) {
+          if (entry.type === "directory") {
+            directoryCount += 1;
+            pending.push(entry.path);
+          } else {
+            fileCount += 1;
+            totalBytes += entry.size;
+          }
+        }
+        if (entries.length < USAGE_PAGE_SIZE) break;
+        offset += entries.length;
+      }
+    }
+
+    return { fileCount, directoryCount, totalBytes };
+  }
+
+  async getQuota(): Promise<WorkspaceQuota> {
+    return { ...this.quota };
+  }
+
+  /** Host-only lifecycle operation. It never removes the user-level `/shared` tree. */
+  async removeAll(): Promise<void> {
+    await this.parent.rm(this.sessionRoot, {
+      recursive: true,
+      force: true,
+    });
+  }
+
+  private physical(path: string): string {
+    const normalized = normalizePath(path);
+    if (normalized === "/shared" || normalized.startsWith("/shared/")) {
+      return normalized;
+    }
+    if (normalized === this.sessionRoot || normalized.startsWith(`${this.sessionRoot}/`)) {
+      return normalized;
+    }
+    if (normalized === "/sessions" || normalized.startsWith("/sessions/")) {
+      throw new Error("another Session workspace is not accessible");
+    }
+    return normalized === "/"
+      ? this.sessionRoot
+      : `${this.sessionRoot}${normalized}`;
+  }
+
+  private writablePhysical(path: string): string {
+    const physical = this.physical(path);
+    if (isReservedMemoryPath(physical)) {
+      throw new Error("/shared/memories is read-only in Session workspaces");
+    }
+    return physical;
+  }
+
+  private async assertNoSymlinkComponents(path: string): Promise<void> {
+    let root: string;
+    if (path === "/shared" || path.startsWith("/shared/")) {
+      root = "/shared";
+    } else if (
+      path === this.sessionRoot ||
+      path.startsWith(`${this.sessionRoot}/`)
+    ) {
+      root = this.sessionRoot;
+    } else {
+      throw new Error("another Session workspace is not accessible");
+    }
+    const relative = path.slice(root.length);
+    const parts = relative.split("/").filter(Boolean);
+    let current = root;
+
+    for (const part of ["", ...parts]) {
+      if (part) current = `${current}/${part}`;
+      const info = await this.parent.lstat(current);
+      if (!info) return;
+      if (info.type === "symlink") {
+        throw new Error(
+          "symbolic links are not accessible in scoped workspaces",
+        );
+      }
+    }
+  }
+
+  private async guardedPhysical(
+    path: string,
+    writable = false,
+  ): Promise<string> {
+    const physical = writable
+      ? this.writablePhysical(path)
+      : this.physical(path);
+    await this.assertNoSymlinkComponents(physical);
+    return physical;
+  }
+
+  private virtual(path: string): string {
+    if (path === this.sessionRoot) return "/";
+    if (path.startsWith(`${this.sessionRoot}/`)) {
+      return path.slice(this.sessionRoot.length);
+    }
+    return path;
+  }
+
+  private project(info: WorkspaceFileInfo | null): WorkspaceFileInfo | null {
+    return info ? { ...info, path: this.virtual(info.path) } : null;
+  }
+
+  async readFile(path: string) {
+    return this.parent.readFile(await this.guardedPhysical(path));
+  }
+
+  async readFileBytes(path: string) {
+    return this.parent.readFileBytes(await this.guardedPhysical(path));
+  }
+
+  async writeFile(path: string, content: string, mimeType?: string) {
+    return this.parent.writeFile(
+      await this.guardedPhysical(path, true),
+      content,
+      mimeType,
+    );
+  }
+
+  async writeFileBytes(
+    path: string,
+    data: Uint8Array | ArrayBuffer,
+    mimeType?: string,
+  ) {
+    return this.parent.writeFileBytes(
+      await this.guardedPhysical(path, true),
+      data,
+      mimeType,
+    );
+  }
+
+  async writeFileBytesIfUnchanged(
+    path: string,
+    data: Uint8Array,
+    mimeType: string,
+    expected: WorkspaceFileVersion | null,
+  ): Promise<WorkspaceConditionalWriteResult> {
+    const physical = await this.guardedPhysical(path, true);
+    if (physical === "/shared" || physical.startsWith("/shared/")) {
+      throw new Error("/shared is read-only for Sandbox publishing");
+    }
+    const current = await this.parent.stat(physical);
+    const currentVersion =
+      current?.type === "file"
+        ? { updatedAt: current.updatedAt, size: current.size }
+        : null;
+    const matches =
+      expected === null
+        ? current === null
+        : current?.type === "file" &&
+          current.updatedAt === expected.updatedAt &&
+          current.size === expected.size;
+    if (!matches) {
+      return {
+        written: false,
+        reason: "conflict",
+        current: currentVersion,
+      };
+    }
+    await this.parent.writeFileBytes(physical, data, mimeType);
+    const written = await this.parent.stat(physical);
+    if (!written || written.type !== "file") {
+      throw new Error("published Workspace file could not be verified");
+    }
+    return {
+      written: true,
+      version: {
+        updatedAt: written.updatedAt,
+        size: written.size,
+      },
+    };
+  }
+
+  async appendFile(path: string, content: string, mimeType?: string) {
+    return this.parent.appendFile(
+      await this.guardedPhysical(path, true),
+      content,
+      mimeType,
+    );
+  }
+
+  async exists(path: string) {
+    return this.parent.exists(await this.guardedPhysical(path));
+  }
+
+  async stat(path: string) {
+    return this.project(
+      await this.parent.stat(await this.guardedPhysical(path)),
+    );
+  }
+
+  async lstat(path: string) {
+    return this.project(
+      await this.parent.lstat(await this.guardedPhysical(path)),
+    );
+  }
+
+  async mkdir(path: string, opts?: { recursive?: boolean }) {
+    return this.parent.mkdir(await this.guardedPhysical(path, true), opts);
+  }
+
+  async readDir(dir = "/", opts?: { limit?: number; offset?: number }) {
+    const files = await this.parent.readDir(
+      await this.guardedPhysical(dir),
+      opts,
+    );
+    return files.map((file) => this.project(file)!);
+  }
+
+  async rm(path: string, opts?: { recursive?: boolean; force?: boolean }) {
+    const physical = await this.guardedPhysical(path, true);
+    if (physical === "/shared" || physical === this.sessionRoot) {
+      throw new Error("workspace mount roots cannot be removed");
+    }
+    return this.parent.rm(physical, opts);
+  }
+
+  async cp(src: string, dest: string, opts?: { recursive?: boolean }) {
+    return this.parent.cp(
+      await this.guardedPhysical(src),
+      await this.guardedPhysical(dest, true),
+      opts,
+    );
+  }
+
+  async mv(src: string, dest: string, opts?: { recursive?: boolean }) {
+    return this.parent.mv(
+      await this.guardedPhysical(src, true),
+      await this.guardedPhysical(dest, true),
+      opts,
+    );
+  }
+
+  async symlink(target: string, linkPath: string) {
+    /*
+     * A symlink stored under `/shared` could target this Session's physical
+     * directory and then be followed by another Session. Path normalization
+     * cannot guard a later filesystem dereference, so scoped runtimes do not
+     * create symlinks at all.
+     */
+    void target;
+    void linkPath;
+    throw new Error("symbolic links are disabled in scoped workspaces");
+  }
+
+  async readlink(path: string) {
+    return this.virtual(
+      await this.parent.readlink(await this.guardedPhysical(path)),
+    );
+  }
+
+  async glob(pattern: string) {
+    const files = await this.parent.glob(this.physical(pattern));
+    for (const file of files) {
+      await this.assertNoSymlinkComponents(file.path);
+    }
+    return files.map((file) => this.project(file)!);
+  }
+}
+
+/**
+ * Build a runtime capability object that contains data-plane methods only.
+ *
+ * A TypeScript annotation does not remove extra methods at runtime. Returning
+ * this explicit facade prevents Agent Runtime and Sandbox adapters from
+ * reaching ScopedWorkspace lifecycle/accounting methods through the same
+ * object reference.
+ */
+export function createWorkspacePortFacade(
+  workspace: WorkspacePort,
+): WorkspacePort {
+  const facade: WorkspacePort = {
+    readFile: (path) => workspace.readFile(path),
+    readFileBytes: (path) => workspace.readFileBytes(path),
+    writeFile: (path, content, mimeType) =>
+      workspace.writeFile(path, content, mimeType),
+    writeFileBytes: (path, data, mimeType) =>
+      workspace.writeFileBytes(path, data, mimeType),
+    appendFile: (path, content, mimeType) =>
+      workspace.appendFile(path, content, mimeType),
+    exists: (path) => workspace.exists(path),
+    stat: (path) => workspace.stat(path),
+    lstat: (path) => workspace.lstat(path),
+    mkdir: (path, opts) => workspace.mkdir(path, opts),
+    readDir: (dir, opts) => workspace.readDir(dir, opts),
+    rm: (path, opts) => workspace.rm(path, opts),
+    cp: (src, dest, opts) => workspace.cp(src, dest, opts),
+    mv: (src, dest, opts) => workspace.mv(src, dest, opts),
+    symlink: (target, linkPath) => workspace.symlink(target, linkPath),
+    readlink: (path) => workspace.readlink(path),
+    glob: (pattern) => workspace.glob(pattern),
+  };
+  return Object.freeze(facade);
+}