feat(think): built-in workspace for every Think agent (#1275)

Every Think instance now gets `this.workspace` — a Workspace backed by
the DO's SQLite storage, with no R2 required. Workspace tools (read,
write, edit, list, find, grep, delete) are automatically merged into
every `onChatMessage` call before `getTools()`.

Changes:
- think.ts: add `workspace` field (auto-initialized from DO SQLite),
  import Workspace + createWorkspaceTools, merge workspace tools first
  in onChatMessage tool spread, re-export Workspace from main entry
- package.json: @cloudflare/shell is now a required peer dependency
  (removed from peerDependenciesMeta.optional)
- e2e worker: simplified TestAssistant — removed manual getTools()
  override and direct Workspace/createWorkspaceTools imports, kept
  R2 override as the canonical pattern for large file spillover
- examples/assistant: removed manual Workspace + createWorkspaceTools
  wiring, removed @cloudflare/shell direct dependency
- README.md: added built-in workspace section, updated exports/peer
  deps tables, added configureSession/onChatResponse to override points,
  added session + skills documentation
- design/think.md: added built-in workspace subsection, updated
  exports table descriptions

Made-with: Cursor

Author: threepointone

.changeset/think-built-in-workspace.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/think": patch
+---
+
+Add built-in workspace to Think. Every Think instance now has `this.workspace` backed by the DO's SQLite storage, and workspace tools (read, write, edit, list, find, grep, delete) are automatically merged into every chat turn. Override `workspace` to add R2 spillover for large files. `@cloudflare/shell` is now a required peer dependency.

design/think.md

@@ -319,11 +319,17 @@ Think inherits `runFiber()` from the `Agent` base class. Fiber state is persiste
 
 ## Tools
 
-Think provides factory functions for common tool patterns, published as separate export paths.
+Think provides a built-in workspace and factory functions for additional tool patterns.
+
+### Built-in workspace
+
+Every Think instance gets `this.workspace` — a `Workspace` (from `@cloudflare/shell`) backed by the DO's SQLite storage. Workspace tools (`read`, `write`, `edit`, `list`, `find`, `grep`, `delete`) are automatically merged into every `onChatMessage` call, before `getTools()`.
+
+Override to add R2 spillover: `override workspace = new Workspace({ sql: this.ctx.storage.sql, r2: this.env.R2, name: () => this.name })`.
 
 ### Workspace tools (`@cloudflare/think/tools/workspace`)
 
-Seven file operation tools backed by abstract operation interfaces (`ReadOperations`, `WriteOperations`, etc.). A convenience function creates all tools from a `Workspace` instance, but you can also create tools against custom storage backends.
+The individual tool factories are also exported for custom storage backends. Seven file operation tools backed by abstract operation interfaces (`ReadOperations`, `WriteOperations`, etc.).
 
 | Tool             | Description                                       | Operations interface |
 | ---------------- | ------------------------------------------------- | -------------------- |
@@ -464,13 +470,13 @@ Tests in `packages/think/src/tests/`, running inside the Workers runtime via `@c
 
 ## Package exports
 
-| Import path                          | Source                    | Purpose                                 |
-| ------------------------------------ | ------------------------- | --------------------------------------- |
-| `@cloudflare/think`                  | `src/think.ts`            | Think base class, StreamCallback, types |
-| `@cloudflare/think/extensions`       | `src/extensions/index.ts` | ExtensionManager, HostBridgeLoopback    |
-| `@cloudflare/think/tools/workspace`  | `src/tools/workspace.ts`  | File operation tools (7 tools)          |
-| `@cloudflare/think/tools/execute`    | `src/tools/execute.ts`    | Sandboxed code execution tool           |
-| `@cloudflare/think/tools/extensions` | `src/tools/extensions.ts` | Extension management AI tools           |
+| Import path                          | Source                    | Purpose                                                |
+| ------------------------------------ | ------------------------- | ------------------------------------------------------ |
+| `@cloudflare/think`                  | `src/think.ts`            | Think base class, Session, Workspace re-exports, types |
+| `@cloudflare/think/extensions`       | `src/extensions/index.ts` | ExtensionManager, HostBridgeLoopback                   |
+| `@cloudflare/think/tools/workspace`  | `src/tools/workspace.ts`  | File operation tool factories (for custom backends)    |
+| `@cloudflare/think/tools/execute`    | `src/tools/execute.ts`    | Sandboxed code execution tool                          |
+| `@cloudflare/think/tools/extensions` | `src/tools/extensions.ts` | Extension management AI tools                          |
 
 ## History
 

examples/assistant/README.md

@@ -4,8 +4,8 @@ A chat agent built with `@cloudflare/think` — the opinionated chat agent base
 
 ## What this demonstrates
 
-- **Think overrides** — `getModel()`, `getSystemPrompt()`, `getTools()` for a batteries-included agent
-- **Workspace tools** — read, write, edit, find, grep files in the DO's SQLite filesystem
+- **Think overrides** — `getModel()`, `configureSession()`, `getTools()` for a batteries-included agent
+- **Built-in workspace** — every Think agent gets `this.workspace` with file tools (read, write, edit, find, grep, delete) auto-wired
 - **Server-side tools** — `getWeather` executes on the server automatically
 - **Client-side tools** — `getUserTimezone` runs in the browser via `onToolCall`
 - **Tool approval** — `calculate` requires user approval for large numbers
@@ -22,17 +22,18 @@ npm start
 
 ## Key code
 
-**Server** (`src/server.ts`) — ~150 lines:
+**Server** (`src/server.ts`):
 
 ```typescript
 export class MyAssistant extends Think<Env> {
-  workspace = new Workspace({ sql: this.ctx.storage.sql, name: () => this.name });
   waitForMcpConnections = true;
 
   getModel() { return createWorkersAI({ binding: this.env.AI })("@cf/moonshotai/kimi-k2.5"); }
-  getSystemPrompt() { return "You are a helpful assistant..."; }
-  getTools() { return { ...createWorkspaceTools(this.workspace), ...this.mcp.getAITools(), ... }; }
+  configureSession(session) { return session.withContext("memory", { ... }).withCachedPrompt(); }
+  getTools() { return { ...this.mcp.getAITools(), getWeather: tool({ ... }), ... }; }
 }
 ```
 
+Workspace tools are included automatically — no manual wiring needed.
+
 **Client** (`src/client.tsx`) — uses `useAgentChat` from `@cloudflare/ai-chat/react`, which works with both Think and AIChatAgent out of the box.

examples/assistant/package.json

@@ -12,7 +12,6 @@
   "dependencies": {
     "@cloudflare/ai-chat": "*",
     "@cloudflare/kumo": "^1.17.0",
-    "@cloudflare/shell": "*",
     "@cloudflare/think": "*",
     "@phosphor-icons/react": "^2.1.10",
     "agents": "*",

examples/assistant/src/server.ts

@@ -1,31 +1,19 @@
 /**
- * Assistant — a Think-based chat agent with workspace tools and MCP.
+ * Assistant — a Think-based chat agent with MCP and custom tools.
  *
- * Demonstrates Think's core features:
- *   - getModel()         — Workers AI with session affinity
- *   - configureSession() — persistent memory via context blocks
- *   - getTools()         — workspace tools + MCP tools + custom tools
- *   - waitForMcpConnections — MCP integration
- *   - Client-side tools  — getUserTimezone (no execute, handled by onToolCall)
- *   - Tool approval      — calculate (needsApproval for large numbers)
- *   - Workspace          — file read/write/edit via @cloudflare/shell
+ * Think provides workspace tools (read, write, edit, find, grep, delete)
+ * out of the box. This agent adds MCP integration, client-side tools,
+ * and tool approval on top.
  */
 
 import { createWorkersAI } from "workers-ai-provider";
 import { routeAgentRequest, callable } from "agents";
 import { Think, Session } from "@cloudflare/think";
-import { createWorkspaceTools } from "@cloudflare/think/tools/workspace";
-import { Workspace } from "@cloudflare/shell";
 import { tool } from "ai";
 import type { LanguageModel, ToolSet } from "ai";
 import { z } from "zod";
 
 export class MyAssistant extends Think<Env> {
-  workspace = new Workspace({
-    sql: this.ctx.storage.sql,
-    name: () => this.name
-  });
-
   waitForMcpConnections = { timeout: 5000 };
 
   getModel(): LanguageModel {
@@ -65,7 +53,6 @@ Always respond concisely.`
     const mcpTools = this.mcp.getAITools();
 
     return {
-      ...createWorkspaceTools(this.workspace),
       ...mcpTools,
 
       getWeather: tool({

packages/think/README.md

@@ -25,14 +25,38 @@ export class MyAgent extends Think<Env> {
 }
 ```
 
-That's it. Think handles the WebSocket chat protocol, message persistence, the agentic loop, message sanitization, stream resumption, and client tool support. Connect from the browser with `useAgentChat` from `@cloudflare/ai-chat`.
+That's it. Think handles the WebSocket chat protocol, message persistence, the agentic loop, message sanitization, stream resumption, client tool support, and workspace file tools. Connect from the browser with `useAgentChat` from `@cloudflare/ai-chat`.
+
+## Built-in workspace
+
+Every Think agent gets `this.workspace` — a virtual filesystem backed by the DO's SQLite storage. Workspace tools (`read`, `write`, `edit`, `list`, `find`, `grep`, `delete`) are automatically available to the model.
+
+```ts
+export class MyAgent extends Think<Env> {
+  getModel() { ... }
+  // this.workspace is ready to use — no setup needed
+  // workspace tools are auto-merged into every chat turn
+}
+```
+
+Override to add R2 spillover for large files:
+
+```ts
+export class MyAgent extends Think<Env> {
+  override workspace = new Workspace({
+    sql: this.ctx.storage.sql,
+    r2: this.env.R2,
+    name: () => this.name
+  });
+}
+```
 
 ## Exports
 
 | Export                               | Description                                                   |
 | ------------------------------------ | ------------------------------------------------------------- |
-| `@cloudflare/think`                  | `Think` — the main class, plus types                          |
-| `@cloudflare/think/tools/workspace`  | `createWorkspaceTools()` — file operation tools               |
+| `@cloudflare/think`                  | `Think`, `Session`, `Workspace` — main class + re-exports     |
+| `@cloudflare/think/tools/workspace`  | `createWorkspaceTools()` — for custom storage backends        |
 | `@cloudflare/think/tools/execute`    | `createExecuteTool()` — sandboxed code execution via codemode |
 | `@cloudflare/think/tools/extensions` | `createExtensionTools()` — LLM-driven extension loading       |
 | `@cloudflare/think/extensions`       | `ExtensionManager`, `HostBridgeLoopback` — extension runtime  |
@@ -41,15 +65,17 @@ That's it. Think handles the WebSocket chat protocol, message persistence, the a
 
 ### Override points
 
-| Method                    | Default                          | Description                           |
-| ------------------------- | -------------------------------- | ------------------------------------- |
-| `getModel()`              | throws                           | Return the `LanguageModel` to use     |
-| `getSystemPrompt()`       | `"You are a helpful assistant."` | System prompt                         |
-| `getTools()`              | `{}`                             | AI SDK `ToolSet` for the agentic loop |
-| `getMaxSteps()`           | `10`                             | Max tool-call rounds per turn         |
-| `assembleContext()`       | prune older tool calls           | Customize what's sent to the LLM      |
-| `onChatMessage(options?)` | `streamText(...)`                | Full control over inference           |
-| `onChatError(error)`      | passthrough                      | Customize error handling              |
+| Method                    | Default                          | Description                                     |
+| ------------------------- | -------------------------------- | ----------------------------------------------- |
+| `getModel()`              | throws                           | Return the `LanguageModel` to use               |
+| `getSystemPrompt()`       | `"You are a helpful assistant."` | System prompt (fallback when no context blocks) |
+| `getTools()`              | `{}`                             | AI SDK `ToolSet` for the agentic loop           |
+| `getMaxSteps()`           | `10`                             | Max tool-call rounds per turn                   |
+| `configureSession()`      | identity                         | Add context blocks, compaction, search, skills  |
+| `assembleContext()`       | prune older tool calls           | Customize what's sent to the LLM                |
+| `onChatMessage(options?)` | `streamText(...)`                | Full control over inference                     |
+| `onChatResponse(result)`  | no-op                            | Post-turn lifecycle hook                        |
+| `onChatError(error)`      | passthrough                      | Customize error handling                        |
 
 ### Client tools
 
@@ -60,13 +86,44 @@ Think supports client-defined tools that execute in the browser. The client send
 { messages: [...], clientTools: [{ name: "search", description: "Search the web" }] }
 
 // In onChatMessage, the default implementation merges:
-// getTools() + clientTools + options.tools
+// workspace + getTools() + clientTools + session context tools + options.tools
 ```
 
 When the LLM calls a client tool, the tool call chunk is sent to the client. The client executes it and sends back `CF_AGENT_TOOL_RESULT`. Think applies the result, persists the updated message, broadcasts `CF_AGENT_MESSAGE_UPDATED`, and optionally auto-continues the conversation (debounce-based — multiple rapid tool results coalesce into one continuation turn).
 
 Tool approval flows are also supported via `CF_AGENT_TOOL_APPROVAL`.
 
+### Session and context blocks
+
+Think uses Session for conversation storage. Override `configureSession` to add persistent memory, skills, compaction, and search:
+
+```ts
+export class MyAgent extends Think<Env> {
+  getModel() { ... }
+
+  configureSession(session: Session) {
+    return session
+      .withContext("memory", { description: "Learned facts", maxTokens: 2000 })
+      .withCachedPrompt();
+  }
+}
+```
+
+Skills support load/unload for explicit context management:
+
+```ts
+import { R2SkillProvider } from "agents/experimental/memory/session";
+
+configureSession(session: Session) {
+  return session
+    .withContext("skills", {
+      provider: new R2SkillProvider(this.env.SKILLS_BUCKET, { prefix: "skills/" })
+    })
+    .withCachedPrompt();
+}
+// Model gets load_context and unload_context tools automatically
+```
+
 ### MCP integration
 
 Think inherits MCP client support from the Agent base class. Set `waitForMcpConnections` to ensure MCP-discovered tools are available before `onChatMessage` runs:
@@ -113,6 +170,7 @@ export class MyAgent extends Think<Env, MyConfig> {
 ### Production features
 
 - **WebSocket protocol** — wire-compatible with `useAgentChat` from `@cloudflare/ai-chat`
+- **Built-in workspace** — every agent gets `this.workspace` with file tools auto-wired
 - **Stream resumption** — page refresh replays buffered chunks via `ResumableStream`
 - **Client tools** — accept tool schemas from clients, handle results and approvals
 - **Auto-continuation** — debounce-based continuation after tool results
@@ -122,22 +180,19 @@ export class MyAgent extends Think<Env, MyConfig> {
 - **Partial persistence** — on error, the partial assistant message is saved
 - **Message sanitization** — strips ephemeral provider metadata before storage
 - **Row size enforcement** — compacts tool outputs exceeding 1.8MB
-- **Incremental persistence** — skips SQL writes for unchanged messages
-- **Storage bounds** — set `maxPersistedMessages` to cap stored history
-- **Messages on connect** — newly connected clients receive the current message list immediately
 
 ## Workspace tools
 
-File operation tools backed by the Agents SDK `Workspace`:
+File operation tools are built into Think and available to the model on every turn. For custom storage backends, the individual tool factories are also exported:
 
 ```ts
 import { createWorkspaceTools } from "@cloudflare/think/tools/workspace";
 
-const tools = createWorkspaceTools(this.workspace);
-// Tools: read, write, edit, list, find, grep, delete
+// Use with a custom ReadOperations/WriteOperations implementation
+const tools = createWorkspaceTools(myCustomStorage);
 ```
 
-Each tool is an AI SDK `tool()` with Zod schemas. The underlying operations are abstracted behind interfaces (`ReadOperations`, `WriteOperations`, etc.) so you can create tools backed by custom storage.
+Each tool is an AI SDK `tool()` with Zod schemas. The underlying operations are abstracted behind interfaces (`ReadOperations`, `WriteOperations`, etc.) so you can create tools backed by any storage.
 
 ## Code execution tool
 
@@ -148,7 +203,6 @@ import { createExecuteTool } from "@cloudflare/think/tools/execute";
 
 getTools() {
   return {
-    ...createWorkspaceTools(this.workspace),
     execute: createExecuteTool({ tools: wsTools, loader: this.env.LOADER })
   };
 }
@@ -181,5 +235,5 @@ getTools() {
 | `agents`               | yes      | Cloudflare Agents SDK            |
 | `ai`                   | yes      | Vercel AI SDK v6                 |
 | `zod`                  | yes      | Schema validation (v3.25+ or v4) |
+| `@cloudflare/shell`    | yes      | Workspace filesystem             |
 | `@cloudflare/codemode` | optional | For `createExecuteTool`          |
-| `@cloudflare/shell`    | optional | For workspace tools              |

packages/think/package.json

@@ -35,9 +35,6 @@
   "peerDependenciesMeta": {
     "@cloudflare/codemode": {
       "optional": true
-    },
-    "@cloudflare/shell": {
-      "optional": true
     }
   },
   "exports": {

packages/think/src/e2e-tests/worker.ts

@@ -5,11 +5,9 @@
  */
 import { createWorkersAI } from "workers-ai-provider";
 import { callable, routeAgentRequest } from "agents";
-import type { LanguageModel, ToolSet, UIMessage } from "ai";
-import { Workspace } from "@cloudflare/shell";
-import { Think } from "../think";
+import type { LanguageModel, UIMessage } from "ai";
+import { Think, Workspace } from "../think";
 import type { ChatRecoveryContext, ChatRecoveryOptions } from "../think";
-import { createWorkspaceTools } from "../tools/workspace";
 
 type Env = {
   TestAssistant: DurableObjectNamespace<TestAssistant>;
@@ -19,7 +17,7 @@ type Env = {
 };
 
 export class TestAssistant extends Think<Env> {
-  workspace = new Workspace({
+  override workspace = new Workspace({
     sql: this.ctx.storage.sql,
     r2: this.env.R2,
     name: () => this.name
@@ -39,10 +37,6 @@ When asked to write a file, use the write tool. When asked to read a file, use t
 Always respond concisely.`;
   }
 
-  getTools(): ToolSet {
-    return createWorkspaceTools(this.workspace);
-  }
-
   @callable()
   override getMessages(): UIMessage[] {
     return this.messages;