agent-sdk-ts parity: Workspace helpers (upload/download/copy, git diff/changes, CommandResult parity) (deferred)

[enyst]

NOTE (VS Code extension context): In VS Code we generally work locally with git, and for diffs/changes we can use the VS Code APIs (including the built-in SCM view) rather than re-implementing git plumbing in agent-sdk-ts. It’s not clear this parity work is necessary for the VS Code-first workflow — please confirm priority/need with the human overseer.

agent-sdk-ts is basically a transpilation of the original python SDK that we can find at enyst/agent-sdk (it’s a fork for our use). Clone yourself agent-sdk so you have the original codebase and you can understand the code deeply before transpiling.

Gap

Python workspace layer provides file transfer helpers, git helpers, and richer result models (e.g. CommandResult.timeout_occurred). TS LocalWorkspace supports basic exec/read/write but lacks these parity utilities.

Python reference

• openhands-sdk/openhands/sdk/workspace/models.py (CommandResult, FileOperationResult)
• openhands-sdk/openhands/sdk/workspace/local.py

Current TS state

• packages/agent-sdk-ts/src/workspace/LocalWorkspace.ts has CommandResult but no timeoutOccurred, no upload/download/copy helpers, no git helpers/models.

Implementation plan

1. Extend TS CommandResult to include timeoutOccurred: boolean (and any other parity fields we need).
2. Add FileOperationResult + copyToWorkspace / fileUpload / fileDownload helpers (local-only acceptable initially).
3. Add gitChanges() + gitDiff() helpers and types.
4. Add tests.

Acceptance criteria

• TS workspace layer exposes equivalents for the Python APIs and returns typed results.

[enyst]

Dependency notes (stacking / merge order)

Blocked by: #633

Rationale / why it’s stacked this way:

• agent-sdk-ts parity: BaseWorkspace abstraction + Workspace() factory #633: Introduces shared workspace abstraction/factory; prevents duplicating types in helpers.

Likely blocks: #635, #645

[enyst]

Related PR: #665 adds/extends unit tests around git diff summary utilities. This PR is not an issue (it is a PR), so it cannot be used as a GitHub “blocked by” dependency via addBlockedBy, but it is relevant context for this parity work.

[enyst]

Desk note (security): there was a valid review concern on deferred PR #667 — workspace upload/download helpers accept arbitrary localPath read/write without root/allowlist restrictions. When this work is revived, please constrain localPath to allowed roots (workspace-only or explicit allowlist) and add unit tests covering the rejection paths.