Python
Universal scratch: every session gets a scratch root; Artifacts panel everywhere
Rohit C Prasad65c568cd4448
diff --git a/coworker/catalog.py b/coworker/catalog.pyindex e2ce78a7..feb9d083 100644--- a/coworker/catalog.py+++ b/coworker/catalog.py@@ -53,17 +53,22 @@ class Capability:def _code_files(context: AgentContext) -> list:- """Repo-oriented files: single-root, line-numbered/windowed `read_file`. Our `grep` and- windowed `read_file` replace aisuite's slower `search_files` / `read_file`/`read_file_lines`.+ """Repo-oriented files: line-numbered/windowed `read_file`. Our `grep` and windowed+ `read_file` replace aisuite's slower `search_files` / `read_file`/`read_file_lines`.+ Multi-root aware (universal scratch): with session roots, writes/reads reach the+ scratch and granted dirs too; the workspace stays the relative-path anchor."""ws = str(context.workspace)replaced = {"search_files", "read_file", "read_file_lines"}+ file_kwargs = (+ {"roots": context.roots} if context.roots else {"root": ws, "allow_write": True}+ )files = [t- for t in ai.toolkits.files(root=ws, allow_write=True)+ for t in ai.toolkits.files(**file_kwargs)if getattr(t, "__name__", "") not in replaced]- return [*files, *file_tools(ws)]+ return [*files, *file_tools(ws, roots=context.roots)]def _files(context: AgentContext) -> list:diff --git a/coworker/roots.py b/coworker/roots.pyindex 54fd52a7..6e155a0f 100644--- a/coworker/roots.py+++ b/coworker/roots.py@@ -63,13 +63,33 @@ def render_context(roots: list[RootDir]) -> str:if not roots:return ""lines = ["Available directories (you may use file/shell tools within these):"]+ has_side_scratch = any(i > 0 and r.label == "scratch" for i, r in enumerate(roots))for i, r in enumerate(roots):access = "read-write" if r.writable else "read-only"- tag = " — primary scratch, the default place to save files" if i == 0 else ""+ if i == 0 and r.label == "scratch":+ tag = " — primary scratch, the default place to save files"+ elif i == 0:+ tag = " — the session's workspace (relative paths resolve here)"+ elif r.label == "scratch":+ tag = (+ " — your scratch directory: temporary files, and artifacts you don't "+ "want to leave inside the workspace"+ )+ else:+ tag = ""lines.append(f"- {r.path} [{access}]{tag}")- lines.append(- "Relative paths resolve against the primary directory; pass an absolute path to use "- "another directory. Writes are only allowed in read-write directories. If the user "- "cares where a deliverable lands, ask; otherwise save it in the primary scratch."- )+ if has_side_scratch:+ lines.append(+ "Relative paths resolve against the workspace; pass an absolute path to use "+ "another directory. Writes are only allowed in read-write directories. Put "+ "reports, analyses, and other non-repo deliverables in the scratch directory "+ "(they appear in the user's Artifacts panel) — write into the workspace only "+ "for changes that belong in it."+ )+ else:+ lines.append(+ "Relative paths resolve against the primary directory; pass an absolute path to use "+ "another directory. Writes are only allowed in read-write directories. If the user "+ "cares where a deliverable lands, ask; otherwise save it in the primary scratch."+ )return "\n".join(lines)diff --git a/coworker/server/manager.py b/coworker/server/manager.pyindex 76322867..4ed7ff83 100644--- a/coworker/server/manager.py+++ b/coworker/server/manager.py@@ -386,8 +386,14 @@ class SessionManager:DEFAULT_SCRATCH_BASE = "~/OpenWorker"def scratch_base(self) -> Path:- """Common area for per-conversation scratch directories. Configurable via prefs."""- base = self._prefs.get("scratch_base") or self.DEFAULT_SCRATCH_BASE+ """Common area for per-conversation scratch directories. Configurable via prefs;+ the env override keeps tests (and any sandboxed run) out of the real home dir —+ universal scratch means every session provisions here, not just orphan ones."""+ base = (+ self._prefs.get("scratch_base")+ or os.environ.get("COWORKER_SCRATCH_BASE")+ or self.DEFAULT_SCRATCH_BASE+ )return Path(base).expanduser()def _provision_scratch(self, session_id: str) -> str:@@ -539,17 +545,35 @@ class SessionManager:if ws:self.session_store.touch_workspace(ws)- # Orphan surfaces are multi-root: the scratch (ws) is the primary writable root, plus any- # folders the user added (persisted per session). Folder-gated personas stay single-root- # (roots=None) until universal scratch lands (workspace-scratch-design.md phase B).+ # Universal scratch (workspace-scratch-design.md §4): EVERY session is multi-root+ # with a per-conversation scratch dir. Orphan sessions run ON their scratch+ # (ws == scratch, primary). Sessions on a real folder — gated personas, or a+ # temp-workspace pick that later became a project — keep that folder primary and+ # gain scratch as a second writable root, so deliverables/temp files have a home+ # that never dirties the user's repo. request_directory rides on roots, so it now+ # registers everywhere.roots = None- if not ag.requires_folder and ws:+ if ws:extra = [rfor r in ((record.extra_roots if record else []) or [])if Path(str(r.get("path", ""))).is_dir()]- roots = [{"path": ws, "writable": True, "label": "scratch"}, *extra]+ if self.is_temp_workspace(ws):+ roots = [{"path": ws, "writable": True, "label": "scratch"}, *extra]+ elif self._SESSION_ID_RE.match(session_id or "") and session_id not in {".", ".."}:+ roots = [+ {"path": ws, "writable": True, "label": "workspace"},+ {+ "path": self._provision_scratch(session_id),+ "writable": True,+ "label": "scratch",+ },+ *extra,+ ]+ else:+ # A session id we won't put in a filesystem path: primary root only.+ roots = [{"path": ws, "writable": True, "label": "workspace"}, *extra]engine = build_engine(agent=ag,workspace=ws,@@ -2305,13 +2329,28 @@ class SessionManager:)return "\n".join(lines)- def list_artifacts(self, session_id: str) -> list[dict[str, Any]]:+ def _artifact_scan_root(self, session_id: str) -> Optional[Path]:+ """The dir the Artifacts panel lists: the session's SCRATCH surface only+ (workspace-scratch-design.md §2.5). For orphan sessions that's the workspace+ itself; for folder-gated sessions it's the side scratch root — never the user's+ repo, which would list the whole codebase as 'artifacts'."""record = self.session_store.load(session_id)workspace = record.workspace if record else self.default_workspace- if not workspace:- return []- root = Path(workspace).expanduser().resolve()- if not root.is_dir():+ if workspace and self.is_temp_workspace(workspace):+ return Path(workspace).expanduser().resolve()+ if self._SESSION_ID_RE.match(session_id or "") and session_id not in {".", ".."}:+ d = (self.scratch_base() / session_id).resolve()+ if d.is_dir():+ return d+ # Legacy fallback (pre-universal-scratch sessions on a custom scratch base):+ # a workspace that is itself disposable still scans.+ if workspace and not record:+ return Path(workspace).expanduser().resolve()+ return None++ def list_artifacts(self, session_id: str) -> list[dict[str, Any]]:+ root = self._artifact_scan_root(session_id)+ if root is None or not root.is_dir():return []out: list[dict[str, Any]] = []suffixes = {@@ -2385,25 +2424,45 @@ class SessionManager:def _artifact_target(self, session_id: str, path: str, *, allow_dir: bool = False) -> tuple[Optional[Path], Optional[str]]:- """Resolve an artifact path under the session's workspace, or (None, error)."""+ """Resolve an artifact path under one of the session's roots — workspace first,+ then the scratch dir, then user-granted extra roots. Universal scratch means a+ gated session's artifacts live BESIDE its workspace, so single-root resolution+ would orphan every transcript chip pointing at scratch."""record = self.session_store.load(session_id)workspace = record.workspace if record else self.default_workspace- if not workspace:+ candidates: list[Path] = []+ if workspace:+ candidates.append(Path(workspace).expanduser().resolve())+ if self._SESSION_ID_RE.match(session_id or "") and session_id not in {".", ".."}:+ scratch = (self.scratch_base() / session_id).resolve()+ if scratch.is_dir() and scratch not in candidates:+ candidates.append(scratch)+ for r in (record.extra_roots if record else []) or []:+ p = Path(str(r.get("path", ""))).expanduser()+ if p.is_dir():+ rp = p.resolve()+ if rp not in candidates:+ candidates.append(rp)+ if not candidates:return None, "no workspace"- root = Path(workspace).expanduser().resolve()- target = (root / path).expanduser().resolve()- try:- target.relative_to(root)- except ValueError:- return None, "path escapes workspace"- if allow_dir and target.is_dir():- return target, None- if not target.is_file():+ found_missing = False+ for root in candidates:+ target = (root / path).expanduser().resolve()+ try:+ target.relative_to(root)+ except ValueError:+ continue+ if allow_dir and target.is_dir():+ return target, None+ if target.is_file():+ return target, None+ found_missing = True+ if found_missing:return None, ("This isn't in the conversation's folder anymore — it may have been ""moved or deleted.")- return target, None+ return None, "path escapes workspace"def read_artifact(self, session_id: str, path: str) -> dict[str, Any]:# Folders are readable too (a model sometimes links a whole package, e.g. a skilldiff --git a/coworker/tools/files.py b/coworker/tools/files.pyindex cd5fe71d..59716a0b 100644--- a/coworker/tools/files.py+++ b/coworker/tools/files.py@@ -9,7 +9,7 @@ the agent how to continue reading. Read-only, workspace-scoped.from __future__ import annotationsfrom pathlib import Path-from typing import Any+from typing import Any, Optionalimport aisuite as ai@@ -47,8 +47,12 @@ _SCHEMA = {}-def file_tools(workspace: str) -> list:+def file_tools(workspace: str, roots: Optional[list] = None) -> list:+ """Windowed read_file rooted at `workspace`. With `roots` (RootDir list), absolute+ paths inside ANY root also resolve — multi-root sessions (universal scratch) address+ their scratch/extra dirs by the absolute paths the roots context advertises."""root = Path(workspace).resolve()+ extra_roots = [Path(str(r.path)).resolve() for r in (roots or [])]def read_file(path: str,@@ -63,10 +67,19 @@ def file_tools(workspace: str) -> list:)n = min(n, _DEFAULT_MAX_LINES)target = (root / path).resolve()+ home = roottry:target.relative_to(root) # keep reads inside the workspaceexcept ValueError:- return {"error": "path escapes the workspace"}+ for r in extra_roots:+ try:+ target.relative_to(r)+ home = r+ break+ except ValueError:+ continue+ else:+ return {"error": "path escapes the session's directories"}if not target.is_file():return {"error": f"not a file: {path}"}@@ -87,7 +100,7 @@ def file_tools(workspace: str) -> list:end = start + len(selected) - 1 if selected else start - 1result: dict[str, Any] = {- "path": str(target.relative_to(root)),+ "path": str(target.relative_to(home)) if home == root else str(target),"start_line": start,"end_line": end,"total_lines": total,diff --git a/surfaces/gui/e2e/artifacts.spec.ts b/surfaces/gui/e2e/artifacts.spec.tsindex 747195f2..a8706a08 100644--- a/surfaces/gui/e2e/artifacts.spec.ts+++ b/surfaces/gui/e2e/artifacts.spec.ts@@ -53,3 +53,21 @@ test("a transcript chip opens the viewer on the FIRST click even with the rail hawait page.getByTestId("artifact-chip").click();await expect(page.getByTestId("artifact-frame")).toBeVisible();});++test("Artifacts section renders for a folder-gated coworker too (universal scratch)", async ({+ page,+}) => {+ // UX-036: every session has a scratch surface, so the drawer's Artifacts section is no+ // longer cowork-only — a security session lists its scratch-side reports the same way.+ await page.goto("/");+ await page.getByTestId("coworker-chip").click();+ await page.locator(".setup-menu").getByRole("button", { name: /Security Coworker/ }).click();+ await page.getByPlaceholder(/Ask the coworker/).fill("audit this repo");+ await page.getByRole("button", { name: "Send" }).click();+ await page.getByTestId("send-folder-dialog").getByRole("button", { name: "Choose a folder…" }).click();+ await expect(page.getByText(/Echo: audit this repo/)).toBeVisible();++ await expect(page.getByTestId("rail-toggle-artifacts")).toBeVisible();+ await page.getByTestId("rail-toggle-artifacts").click();+ await expect(page.locator(".artifact-row", { hasText: "security-review.html" })).toBeVisible();+});diff --git a/surfaces/gui/src/App.tsx b/surfaces/gui/src/App.tsxindex 9fd31e3f..c76cfb2f 100644--- a/surfaces/gui/src/App.tsx+++ b/surfaces/gui/src/App.tsx@@ -2065,12 +2065,14 @@ export function App() {todo={todo}running={running}onPreviewChange={onArtifactPreview}- showArtifacts={agent === "cowork"}+ // Universal scratch (UX-036): every session has a scratch surface, so the+ // Artifacts section always shows — the server lists the scratch root only.+ showArtifactspersonaId={agent}projectScoped={isProjectScoped(personaOf(agent))}workspace={workspace || undefined}branch={branch}- scratchPrimary={agent === "cowork" || tempWorkspace}+ scratchPrimary={tempWorkspace || !isProjectScoped(personaOf(agent))}openAccessKey={accessKey}onOpenIntegrations={() => setSurface("integrations")}board={board}diff --git a/tests/conftest.py b/tests/conftest.pyindex 61abb579..fa9b4cbf 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -21,6 +21,9 @@ def _isolated_state_dir(tmp_path, monkeypatch):sign-in, which made test session creation emit REAL telemetry to prod (found 2026-07-03as burst noise in the ocw-connect-telemetry-events table)."""monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "coworker-state"))+ # Universal scratch provisions a per-session dir for EVERY session — without this,+ # tests would mkdir under the developer's real ~/OpenWorker.+ monkeypatch.setenv("COWORKER_SCRATCH_BASE", str(tmp_path / "coworker-scratch"))monkeypatch.delenv("COWORKER_API_TOKEN", raising=False)diff --git a/tests/test_multiroot.py b/tests/test_multiroot.pyindex d24aa0ef..e42b7277 100644--- a/tests/test_multiroot.py+++ b/tests/test_multiroot.py@@ -320,3 +320,90 @@ def test_request_directory_without_requester_is_safe_noop():next(e for e in events if e.type == EventType.TOOL_FINISHED).data["status"]== "denied")+++# -- Universal scratch (workspace-scratch-design.md §4) -------------------------+++def _repo(tmp_path, name="repo"):+ d = tmp_path / name+ d.mkdir()+ (d / "README.md").write_text("hello", encoding="utf-8")+ return d+++def test_gated_session_gets_workspace_plus_scratch_roots(tmp_path):+ mgr = _cowork_manager(tmp_path)+ repo = _repo(tmp_path)+ sid = "sessGated1"+ engine = mgr.get_engine(sid, agent="code", workspace=str(repo))+ assert engine is not None++ roots = mgr.get_roots(sid)+ assert len(roots) == 2+ assert roots[0]["primary"] and Path(roots[0]["path"]) == repo.resolve()+ scratch = mgr.scratch_base() / sid+ assert Path(roots[1]["path"]) == scratch.resolve()+ assert roots[1]["writable"] is True+ assert scratch.is_dir() # provisioned at engine build++ # Both roots are writable to the permission engine; elsewhere is not.+ perms = engine.permissions+ assert perms._under_writable_root(str(repo / "x.txt"))+ assert perms._under_writable_root(str(scratch / "x.txt"))+ assert not perms._under_writable_root(str(tmp_path / "elsewhere.txt"))+++def test_orphan_session_keeps_scratch_primary_single_scratch_root(tmp_path):+ mgr = _cowork_manager(tmp_path)+ sid = "sessOrphan1"+ engine = mgr.get_engine(sid, agent="cowork")+ assert engine is not None+ roots = mgr.get_roots(sid)+ # ws == scratch: exactly one scratch root, never doubled.+ assert len(roots) == 1 and roots[0]["primary"] and roots[0]["writable"]+ assert Path(roots[0]["path"]) == (mgr.scratch_base() / sid).resolve()+++def test_gated_session_artifacts_list_scratch_not_repo(tmp_path):+ mgr = _cowork_manager(tmp_path)+ repo = _repo(tmp_path)+ sid = "sessGated2"+ assert mgr.get_engine(sid, agent="code", workspace=str(repo)) is not None+ scratch = mgr.scratch_base() / sid+ (scratch / "report.html").write_text("<h1>posture</h1>", encoding="utf-8")++ arts = mgr.list_artifacts(sid)+ names = {a["name"] for a in arts}+ # The repo's files are NOT artifacts; the scratch report is.+ assert "report.html" in names and "README.md" not in names+++def test_artifact_chips_resolve_in_workspace_and_scratch(tmp_path):+ mgr = _cowork_manager(tmp_path)+ repo = _repo(tmp_path)+ sid = "sessGated3"+ engine = mgr.get_engine(sid, agent="code", workspace=str(repo))+ assert engine is not None+ mgr.save(sid, engine) # chips resolve against the persisted record, as after a turn+ scratch = mgr.scratch_base() / sid+ (scratch / "report.html").write_text("<h1>ok</h1>", encoding="utf-8")++ # Relative chip → workspace file (as before).+ assert mgr.read_artifact(sid, "README.md")["ok"] is True+ # Relative chip that only exists in scratch → resolves there.+ assert mgr.read_artifact(sid, "report.html")["ok"] is True+ # Absolute scratch path (what the roots context advertises) → resolves.+ assert mgr.read_artifact(sid, str(scratch / "report.html"))["ok"] is True+ # Escapes every root → refused.+ outside = tmp_path / "outside.txt"+ outside.write_text("x", encoding="utf-8")+ assert mgr.read_artifact(sid, str(outside))["ok"] is False+++def test_gated_session_registers_request_directory(tmp_path):+ mgr = _cowork_manager(tmp_path)+ repo = _repo(tmp_path)+ engine = mgr.get_engine("sessGated4", agent="code", workspace=str(repo))+ assert engine is not None+ assert "request_directory" in engine.registry.names()