feat: add Workspace class — persistent virtual filesystem for Agents

[threepointone]

Summary

Adds the Workspace class to agents/experimental/workspace — a persistent virtual filesystem backed by Durable Object SQLite with optional R2 spillover for large files.

This PR includes the full implementation, comprehensive tests, a design document, and an interactive demo.

---

What is included

1. Workspace class (packages/agents/src/experimental/workspace.ts)

A complete virtual filesystem that any Agent can attach:

import { Workspace } from "agents/experimental/workspace";

class MyAgent extends Agent {
  workspace = new Workspace(this, { namespace: "ws" });
}

Filesystem operations:

• readFile, writeFile, deleteFile, rename
• readDir, mkdir, stat, lstat, exists
• glob (picomatch-based pattern matching)
• symlink, readlink
• getWorkspaceInfo (aggregate stats)

Storage model:

• Files <= 1 MB stored inline in SQLite (single round-trip reads)
• Files > 1 MB spill to R2 automatically (transparent to callers)
• Namespace isolation — multiple workspaces per DO, no table collisions

Bash execution:

• bash(command, { cwd }) — run shell commands via just-bash (pure JS bash interpreter)
• Custom commands, environment variables, and network config
• Observability events (workspace:bash) emitted for every execution

2. BashSession — persistent shell sessions

const session = workspace.createBashSession({ cwd: "/project" });
await session.exec("npm init -y");
await session.exec("mkdir src && echo \"hello\" > src/index.ts");
console.log(session.cwd);  // "/project"
console.log(session.env);  // includes all shell variables
session.close();

• cwd and env persist across exec() calls
• State captured via stdout-based sentinels (no filesystem side-effects)
• Multiple independent sessions share the same filesystem
• isClosed getter, Symbol.dispose support

3. Tests (packages/agents/src/tests/workspace.test.ts)

29 tests covering:

• Filesystem: readFile, writeFile, deleteFile, rename, readDir, mkdir, stat, exists, glob, symlinks, large file R2 spillover, namespace isolation, workspace info, change events
• Bash: echo/stdout, exit codes, file manipulation, env vars, custom commands, workspace-level commands, cwd option
• BashSession (15 tests): cwd persistence, env persistence, initial cwd/env, independent sessions, shared filesystem, session reuse, variable persistence, multi-step workflows, exit code preservation, stderr pass-through, empty stdout, early exit state preservation, isClosed lifecycle, observability events

4. Design document (design/workspace.md)

Covers: storage model, namespace isolation, symlinks, change events, observability, bash execution, bash sessions, streaming I/O, security boundaries, key decisions, tradeoffs, and testing strategy.

5. Experimental demo (experimental/workspace-chat/)

An interactive AIChatAgent + Workspace example:

• Server: AIChatAgent with 7 tools — readFile, writeFile, listDirectory, deleteFile, mkdir, bash, glob
• Client: Chat UI with a file browser sidebar (clickable files show content), auto-refresh after AI actions, reasoning trace rendering, Streamdown markdown
• Each browser gets its own agent instance (UUID persisted in localStorage)
• Model: @cf/zai-org/glm-4.7-flash via Workers AI

---

API surface

New export: agents/experimental/workspace

Export	Type	Description
Workspace	class	Main filesystem class
BashSession	class	Persistent shell session
BashOptions	type	Options for bash/createBashSession
BashResult	type	bash() return type
FileInfo	type	File/directory entry metadata
FileStat	type	Detailed file stats
WorkspaceChangeEvent	type	Change event payload
WorkspaceOptions	type	Constructor options
WorkspaceHost	interface	Host requirements
defineCommand	function	Helper for custom bash commands

---

Changeset

Included in .changeset/workspace-class.md — minor bump for agents package.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6157447

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/agents@1069

npm i https://pkg.pr.new/@cloudflare/ai-chat@1069

npm i https://pkg.pr.new/@cloudflare/codemode@1069

npm i https://pkg.pr.new/hono-agents@1069

commit: 1fd1675