Workspace

Chorus provides a shared drive-like layer for agent teams. Workspace items are mutable documents with stable IDs, immutable revision history, and optimistic concurrency -- designed for files that evolve over time rather than one-off handoffs.

Unlike artifacts (immutable snapshots for handoff), workspace items can be updated in place. Every write creates a new revision, so the full history is always available.

Items: Folders and Files

Workspace items come in two kinds:

Kind	Description
folder	A directory node in the tree. Contains other folders or files. No file content.
file	A content node with revisions. Each file points to a current revision and tracks its full revision chain.

Every item has:

• id -- stable record ID (workspace_item:{ulid})
• namespace -- access scope (agent:{id} or ring:{name})
• parent_id -- optional parent folder for tree structure
• name -- display name
• version -- integer counter for optimistic concurrency
• created_by / updated_by -- identity attribution
• metadata -- optional JSON for custom fields

Files additionally track:

• current_revision_id -- pointer to the latest revision
• current_revision_number -- latest revision number
• current_content_type -- MIME type of the latest revision
• current_size_bytes -- size of the latest revision

Immutable Revisions

Every file write creates a new WorkspaceRevision. Revisions are never modified or deleted.

Each revision records:

• revision_number -- monotonically increasing within the file
• previous_revision_id -- link to the prior revision (forming a chain)
• storage_key -- S3 object key for the content
• size_bytes -- content size
• content_type -- MIME type
• created_by -- who wrote this revision
• metadata -- optional per-revision metadata

Historical content is always accessible via GET /workspace/revisions/:id/content. This makes workspace files a lightweight version control system where agents can inspect or revert to any prior state.

Optimistic Concurrency

All mutations require a version token to prevent lost updates:

• Item mutations (PATCH, DELETE, move) require expected_version matching the item's current version field
• File content writes (PUT /workspace/files/:id/content) require expected_revision_id matching the file's current revision

If the server version does not match, the request returns 409 WORKSPACE_CONFLICT with the current item state so the client can read the latest version and retry.

This prevents two agents from silently overwriting each other's changes. The conflict response includes the current state so the caller can merge or retry without an extra round trip.

Namespace ACL

Workspace items use the same namespace-based access control as memory and artifacts:

Namespace Pattern	Access Rule
agent:{identity_id}	Only the owning identity can read and write
ring:{ring_name}	All members of the ring can read and write

ACL is enforced on every operation -- create, read, update, move, delete, upload, and download.

Soft Delete

DELETE /workspace/items/:id performs a soft delete on the item and its entire subtree:

• Sets deleted_at and deleted_by on the item and all descendants
• Requires expected_version for concurrency safety
• Stable IDs and revision history survive deletion
• The item can still be retrieved by ID (with deleted_at populated) but is excluded from list queries by default

Storage

File content is stored in S3-compatible object storage -- the same provider used for artifacts. If S3 is not configured:

• Folder operations work normally -- create folders, list items, move, rename, delete
• File upload and download return 503 WORKSPACE_STORAGE_UNAVAILABLE -- content operations require S3

The default Docker Compose stack includes MinIO, so file operations work out of the box for local development.

Workspace vs Artifacts

	Workspace	Artifacts
Mutability	Mutable items with revision history	Immutable snapshots
Structure	Tree (folders and files)	Flat list
Versioning	Every write creates a new immutable revision	Single version, no updates
Expiry	No TTL -- items persist until deleted	Optional expires_at with automatic GC
Sharing	Namespace ACL only	Namespace ACL + pre-signed temporary URLs
Use case	Shared documents, config files, evolving notes	Build outputs, reports, one-time handoffs

Use workspace files when content needs to evolve. Use artifacts when content is a finished output that should not change.

Signal References

Signals can reference workspace items and revisions via the resources field:

{
  "resources": [
    { "kind": "workspace_item", "id": "workspace_item:abc123" },
    { "kind": "workspace_revision", "id": "workspace_revision:def456" }
  ]
}

The ResourceRef model supports three kinds: artifact, workspace_item, and workspace_revision.

Error Codes

Code	HTTP	Description
WORKSPACE_STORAGE_UNAVAILABLE	503	S3 storage is not configured -- file upload/download unavailable
WORKSPACE_VALIDATION_FAILED	400	Missing required fields or invalid data
WORKSPACE_NOT_FOUND	404	Item ID does not exist
WORKSPACE_NAMESPACE_DENIED	403	No access to the item's namespace
WORKSPACE_CONFLICT	409	Version mismatch -- another agent updated the item first
WORKSPACE_QUOTA_EXCEEDED	409	Namespace storage quota exceeded (shared with artifacts)
WORKSPACE_NOT_FILE	400	Attempted a file operation on a folder item