Repository navigation
Feature: add workspace.inspect() and the workspace_summary tool #226
Description
I've built two additions to @cloudflare/computer on my fork. Pull requests are restricted to collaborators, so I'm posting them here first for a maintainer to review.
workspace.inspect() (branch: https://github.com/AmolDerickSoans/computer/tree/feat/workspace-inspect) returns a read-only snapshot of a workspace: storage counters, the current revision, sync cursors per backend, backend connection status, mounted roots, and tracked executions. It reads the local durable object store and in-memory state only, so it never dials a backend and is cheap enough to call from a health check or a logging loop.
workspace_summary (branch: https://github.com/AmolDerickSoans/computer/tree/feat/workspace-summary-tool, stacked on the first) is a new tool for all three tool sets. One call returns a directory's entry count, file and directory counts, total bytes, and every entry with its size and kind. Its description is built from the workspace, so it names the registered execution backends or says that none is registered. The tool is read-only, so it ships in read-only sets too.
Both branches include unit tests, documentation, and changesets. The test suite, typecheck, and npm run check pass:
npm run build --workspace @cloudflare/dofs --workspace @cloudflare/computer-rpc --workspace @cloudflare/computer
npm test --workspace @cloudflare/computer
npm run checkI have the implementation and unit tests ready on my fork branches. Since PR submissions are restricted to collaborators, could a maintainer review the branches or temporarily grant access to open the pull requests?
Activity
aron-cf commentedon Oct 12, 2026
Hey, thanks for opening this issue. Could you perhaps share more about how you're using these two features and why you think they would belong in the core library.
As it stands I don't think I'm prepared yet to introduce quite so specific interfaces to the core workspace for dumping stats, but you need APIs exposed to be able to build this in user space I'm open to changes.
I'm going to close this for now, but feel free to re-open with more information.
AmolDerickSoans commentedon Oct 15, 2026
Following up on your question, and correcting my proposal.
How I'm using it. I run long-lived agent workspaces behind an operational surface: a health check on a loop, and an operator view that shows, per workspace, whether its execution backends are actually connected and roughly how big it has grown. For anything that stays up and syncs, that is the minimum you need to know — are the backends up, is it draining, is it growing.
What I got wrong. You were right.
workspace.inspect()andworkspace_summaryare too specific for core — aminorthere freezes field names (totalFileBytes,blobBytes,tombstones,pushCursor), alargestFilesheuristic with its own default and cap, and internal sync states into your public API for good. Andworkspace_summaryneeds nothing new at all: it isfs.readdirplusruntime.backends(), so it belongs in user space.The one thing user code cannot reach. Storage numbers I can read from
workspace.db. What I cannot reach is backend liveness.runtime.backends()is a static descriptor — id, protocol, callable, description — snapshotted when the client is created and deliberately the same locally and over RPC. It cannot say whether a backend is currently connected; that is a live, Durable-Object-local fact with no accessor today. I would suggest a live companion, kept out of that frozen snapshot so its contract is untouched:That one accessor is what would let me — and anyone else — build the health surface in user space. I am not asking for a report type, a stats method, or a schema contract. If a connect/disconnect observer signal is more in keeping with how you want those transitions surfaced, that works for me too.
What is ready. A working prototype on my fork, with tests, docs and a changeset; one test proves the snapshot never dials a backend.
npm run checkandnpm testare green. If you want it, say so and I will open a PR for the liveness accessor alone — or move this to a feature-request Discussion if that is the channel you would prefer.