Install from `file://` source misroutes to `git clone` (is_git_url / is_local_path_source classifier conflict)

[valeriiD]

Environment

• openhands-agent-server / sdk / tools 1.44.1 (pip, stock venv)
• Windows 11, python -m openhands.agent_server --host 127.0.0.1 --port 8001
• Re-checked against current main — the classifier conflict below is unchanged

Summary

Correction — my original report overstated the failure set; see my analysis comment for the full three-cause breakdown. Of the three local-source forms tested, only the file:// URI is a server-side bug. The raw-Windows-path failure was a client-side JSON escaping artifact in my own requests (unescaped backslashes — the two-character sequences \b and \r are valid JSON escapes and corrupted the path before it reached the server); with a correctly encoded body the REST endpoints install a raw Windows path fine, verified against the same server. The /r/... MSYS-style path is drive-relative on Windows (not a Windows path) and is expected to fail. What remains is below.

The bug: a file:// source is misclassified as a git URL, so install attempts run git clone against a plain directory and fail.

Steps to Reproduce

SDK-only, no server needed (platform-independent):

python -c "
from openhands.sdk.extensions.fetch import parse_extension_source
from openhands.sdk.git.utils import is_git_url
from openhands.sdk.utils.path import is_local_path_source

src = 'file:///C:/path/to/local/extension'
print(is_git_url(src))             # True  — claims file:// 'for testing'
print(is_local_path_source(src))   # True  — documents file:// as local syntax
print(parse_extension_source(src)) # (SourceType.GIT, ...) — git wins by ordering
"

REST consequence (either router, any OS) — note the body below is correctly escaped JSON, so this failure is genuinely server-side:

curl -X POST .../api/canvas-extensions/install -H 'Content-Type: application/json' \
  -d '{"source": "file:///C:/path/to/local/extension"}'
# -> 400 "Failed to fetch canvas extension source"
#    server log: `git clone --depth 1 file:///C:/path/to/local/extension` → exit 128
#    ("does not appear to be a git repository")

Expected Behavior

• parse_extension_source("file:///...") classifies the source as SourceType.LOCAL, matching is_local_path_source()'s docstring ("accepts explicit local path syntax such as file:// URLs").
• Installing from a file:// URI copies the local directory.

Actual Behavior

Running the python snippet above: is_git_url() and is_local_path_source() both return True for the same file:// string, and parse_extension_source() resolves the contradiction in favour of git:

• openhands/sdk/git/utils.py — is_git_url() returns True for file:// (comment: "File protocol (for testing)").
• openhands/sdk/extensions/fetch.py — parse_extension_source() checks is_git_url() before is_local_path_source(), so file:// sources are routed to git clone → ExtensionFetchError → the routers return 400 "Failed to fetch ... source". The local classifier's file:// branch is unreachable on this path.
• _resolve_local_source() does bare Path(url) with no URL→path conversion, so the LOCAL branch couldn't handle a file:// URI either (Path('file:///C:/x').resolve() resolves to garbage). The fix needs both halves.

Acceptance Criteria

• parse_extension_source("file:///path/to/ext") returns SourceType.LOCAL
• Installing from a file:// URI copies the local directory (no git clone attempt)
• is_git_url() and is_local_path_source() no longer both claim file://

Suggested fix

Classify file:// as LOCAL in parse_extension_source() (check is_local_path_source() first, or drop the file:// claim from is_git_url()), and teach _resolve_local_source() to convert a file:// URI to a path (strip scheme, urllib.parse.unquote).

Notes

• file:// is not documented as an install-source form in the REST schema ("git URL, GitHub shorthand, or local path"), so this is an internal-consistency fix rather than a broken documented feature — the documented forms work per-platform (native Windows paths on Windows, POSIX paths on Linux) when request bodies are correctly encoded.
• Nearest existing work (fix(extensions): compose local source with repo_path #4839, local source + repo_path composition) addresses a different local-source defect.

[github-actions]

⚠️ Not yet ready-for-dev

This issue does not yet meet the readiness criteria, so the
ready-for-dev label has not been applied (or has been removed).
The criteria are type-specific:

Bug reports (bug label, see .github/ISSUE_TEMPLATE/bug_template.yml):

• The ### Actual Behavior section must describe reproducible SDK steps
  and include a command such as python, pytest, uv, or pip.
• An ### Acceptance Criteria section with at least one checklist item (- [ ] …).

Enhancements (enhancement label, see .github/ISSUE_TEMPLATE/feature_request.yml):

• A ### Desired Behavior section.
• An ### Acceptance Criteria section with at least one checklist item.

What is missing:

• The issue has neither the bug nor enhancement label, so its readiness criteria cannot be evaluated. Add the appropriate label.

Edit the issue to address the gaps and the ready-for-dev label will be
applied automatically.

Note: Section headings require exact ### matches from the templates.
If a missing type label is reported, no action is needed from external
contributors — maintainers will add the label during triage.

This is an automated check — no AI was used to generate this comment.

[valeriiD]

Correction + root-cause analysis (from the reporter — I overstated the failure set in the original report)

I've reproduced this against stock 1.44.1 and re-checked the current main sources. The three failing forms have three different causes, and only one is a server-side bug:

1. file:// URIs — real bug, still present on main. Two classifiers contradict each other and the wrong one wins:

• openhands/sdk/git/utils.py — is_git_url() returns True for file:// (comment: "File protocol (for testing)").
• openhands/sdk/utils/path.py — is_local_path_source() explicitly documents file:// URLs as local syntax (docstring + first startswith check).
• openhands/sdk/extensions/fetch.py — parse_extension_source() checks is_git_url() before is_local_path_source(), so a file:// source is routed to git clone --depth 1 file:///... against a plain directory → exit 128 ("does not appear to be a git repository") → ExtensionFetchError → the 400. The local classifier's file:// branch is unreachable on this path.
• Additionally _resolve_local_source() does bare Path(url) with no URL→path conversion, so the LOCAL branch couldn't handle a file:// URI either (Path('file:///R:/x').resolve() → R:x). The fix needs both halves.

2. Raw Windows path (R:\...) — client-side JSON escaping, not a server bug. The failing request carried unescaped backslashes inside the JSON body; the two-character sequences \b and \r are valid JSON escapes (backspace, CR), so the body parsed fine and the path arrived corrupted with control characters → nonexistent path → the same 400. With a correctly encoded body (R:\\... or forward slashes) the REST endpoint installs successfully — verified against the same server, and the in-process SDK install with the identical path string works (it's what produced the original "SDK succeeds" comparison). Suggest anyone re-testing uses forward slashes to avoid the escaping trap.

3. /r/... MSYS-style path — not a Windows path. On Windows Path('/r/...') is drive-relative, so _resolve_local_source() resolves it against the server process's current drive → nonexistent path → 400. Expected for a native Windows process; the MSYS drive mapping isn't knowable server-side.

SDK repro for (1) (any OS — the classifier conflict is platform-independent):

from openhands.sdk.extensions.fetch import parse_extension_source, SourceType
from openhands.sdk.git.utils import is_git_url
from openhands.sdk.utils.path import is_local_path_source

src = "file:///C:/path/to/local/extension"
print(is_git_url(src))             # True  — claims it "for testing"
print(is_local_path_source(src))   # True  — documents it as local syntax
print(parse_extension_source(src)) # (SourceType.GIT, ...) — git wins by ordering

Suggested fix: in parse_extension_source(), classify file:// as LOCAL (either check is_local_path_source() first, or drop the file:// claim from is_git_url()), and teach _resolve_local_source() to convert a file:// URI to a path (strip scheme, urllib.parse.unquote).

Acceptance criteria:

• parse_extension_source("file:///path/to/ext") returns SourceType.LOCAL
• Installing from a file:// URI copies the local directory (no git clone attempt)
• is_git_url() and is_local_path_source() no longer both claim file://

Context note: file:// is not documented as an install-source form in the REST schema ("git URL, GitHub shorthand, or local path"), so this is an internal-consistency fix rather than a broken documented feature — the documented forms all work on Windows when the JSON body is correctly escaped, and POSIX paths resolve natively on Linux.

[valeriiD]

Correction — closing as user error on our side. Re-testing with carefully constructed request bodies, the raw Windows absolute path form ({"source": "R:\rig\my-plugin"}) works correctly on both endpoints (returns 409 already-installed here, i.e. fetch succeeded). Our original failures came from our own client-side request construction, not the endpoints.

One narrow observation in case it's useful (not the subject of this issue as filed): the file:///R:/... URI form does fail on Windows — resolve_source_path strips file:// leaving /R:/..., which isn't a valid Windows path. Raw paths are the working local form; feel free to ignore if URI support is out of scope.