fix(workspace): guard downloadAndSave against non-browser environments

[VascoSch92]

Problem

RemoteWorkspace.downloadAndSave() uses browser-only DOM APIs (document.createElement, document.body, URL.createObjectURL) with no environment check. In Node.js — a common environment for RemoteWorkspace automation — it throws a cryptic ReferenceError: document is not defined.

Closes #114.

Change

Add a runtime guard at the top of downloadAndSave():

if (typeof document === 'undefined') {
  throw new Error(
    'downloadAndSave() is only available in browser environments. ' +
      'Use downloadAsBlob() or downloadAsText() in Node.js.'
  );
}

• Non-breaking: browser behavior is unchanged; Node.js callers get a clear, actionable error instead of a cryptic ReferenceError. The suggested fallbacks (downloadAsBlob(), downloadAsText()) already exist and are Node-safe.

Tests

New src/__tests__/remote-workspace-download.test.ts:

• throws the guard error in the Node (testEnvironment: 'node') suite and confirms the network is never touched;
• with a stubbed browser-like document/URL, the anchor download still fires (createElement('a'), href, click, appendChild/removeChild, revokeObjectURL);
• honors an explicit saveAsFileName.

Full unit suite green (274 tests), tsc build clean, eslint + prettier clean.

[github-actions]

Endpoint audit

❌ 7 off-contract call(s) — not on the agent-server · classifiers: cloud

Category	Count
❌ Off-contract (not on agent-server)	7
⛔ no known backend	6
↗️ served by cloud	1
➕ Missing API (agent-server has, client lacks)	7
agent-server endpoints	112
client endpoints	110

❌ Not on agent-server (gated, 7)

⛔ (no known backend) — served by no backend we can see (6)

• DELETE /api/meta-profiles/{}
• GET /api/meta-profiles
• GET /api/meta-profiles/{}
• POST /api/cloud-proxy
• POST /api/meta-profiles/{}
• POST /api/meta-profiles/{}/activate

↗️ served by cloud (1)

• GET /api/shared-events/search

➕ Missing API — agent-server exposes it, client does not implement (7)

• GET /
• GET /api/conversations
• GET /api/conversations/{}/events
• GET /api/conversations/{}/workspace
• GET /api/conversations/{}/workspace/{}
• GET /api/init
• POST /api/init

[all-hands-bot]

🤖 OpenHands is reviewing this PR.

Head commit: de392c025852c9fd28264c36387b6e54b93c668c
View the conversation: https://oss-agent-canvas.ngrok.dev/conversations/7ca01e03-9f67-4241-8daa-830c6a8eb1f5

This comment was posted by an AI agent (OpenHands).

[all-hands-bot]

This review was created by an AI agent (OpenHands) on behalf of the repository maintainers.

Review Summary

This PR adds a runtime environment guard (typeof document === 'undefined') at the top of RemoteWorkspace.downloadAndSave(), throwing a clear, actionable error that directs Node.js callers to the existing Node-safe alternatives (downloadAsBlob() / downloadAsText()).

Findings

No material issues found. The change is clean, minimal, and well-targeted:

• Guard placement is correct — it runs before downloadAsBlob() (the network call), so Node.js callers fail fast without touching the network, and the first test case explicitly verifies this.
• Error message is actionable — both suggested fallbacks (downloadAsBlob, downloadAsText) exist on the same class (lines 263/281) and are Node-safe.
• Guard is sufficient — the method also uses URL.createObjectURL/revokeObjectURL, but the guard throws before reaching those, so no partial-execution concern.
• Tests are thorough — three cases covering the Node.js guard error (no network), browser-like DOM stub behavior (full anchor lifecycle + revoke), and custom filename honoring. Global stubs are cleaned up via try/finally.
• Browser-compatible — the guard itself uses only typeof (no Node.js APIs), consistent with the repo's browser-compatibility constraint.

Risk Assessment

Low risk. Browser behavior is unchanged; Node.js callers receive a clear error instead of a cryptic ReferenceError: document is not defined. Non-breaking.