Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Add a native folder picker to Code Sessions (#1712)

Ali Khokharc5918586a437
diff --git a/e2e/code_support.py b/e2e/code_support.py
index e82eb088..4411d922 100644
--- a/e2e/code_support.py
+++ b/e2e/code_support.py
@@ -12,6 +12,7 @@ from tests.code_sessions_support import FakeHarness
class CodeControl:
def __init__(self, directory):
self.harness = FakeHarness()
+ self.folder_picker = FolderPickerControl()
self.service = CodeService(
SQLiteCodeStore(directory / "code.db", directory / "code.lock"),
self.harness,
@@ -40,3 +41,31 @@ class CodeControl:
async def release_send(self):
self.admission.set()
self.admission_patch.stop()
+
+
+class FolderPickerControl:
+ """Substitute the native dialog while retaining its real runtime owner."""
+
+ def __init__(self):
+ self.calls = asyncio.Queue()
+
+ async def select(self, initial_path, stop):
+ result = asyncio.get_running_loop().create_future()
+ closed = asyncio.Event()
+ self.calls.put_nowait((initial_path, result, closed))
+ stopped = asyncio.create_task(stop.wait())
+ try:
+ await asyncio.wait((result, stopped), return_when=asyncio.FIRST_COMPLETED)
+ return None if stop.is_set() else result.result()
+ finally:
+ stopped.cancel()
+ await asyncio.gather(stopped, return_exceptions=True)
+ closed.set()
+
+ async def finish(self, call, path):
+ call[1].set_result(path)
+ await call[2].wait()
+
+ async def fail(self, call):
+ call[1].set_exception(RuntimeError("No desktop available"))
+ await call[2].wait()
diff --git a/e2e/conftest.py b/e2e/conftest.py
index e01d6333..f4de377e 100644
--- a/e2e/conftest.py
+++ b/e2e/conftest.py
@@ -31,6 +31,7 @@ from free_claude_code.providers.runtime import ProviderRuntime
from free_claude_code.runtime.application import ApplicationRuntime
from free_claude_code.runtime.asgi import RuntimeASGIApp
from free_claude_code.runtime.configuration import ConfigurationService
+from free_claude_code.runtime.folder_picker import NativeFolderPicker
from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
@@ -183,6 +184,11 @@ def admin_base_url(
transcriber=None,
code_service=code_control.service,
)
+ monkeypatch.setattr(
+ NativeFolderPicker,
+ "_select",
+ lambda _picker, initial, stop: code_control.folder_picker.select(initial, stop),
+ )
app = RuntimeASGIApp(
create_app(
ApiServices(
diff --git a/e2e/test_code_sessions.py b/e2e/test_code_sessions.py
index bac63e14..89351f03 100644
--- a/e2e/test_code_sessions.py
+++ b/e2e/test_code_sessions.py
@@ -1,4 +1,5 @@
import re
+import sys
import uuid
import pytest
@@ -29,6 +30,283 @@ def send(page, text):
expect(page.get_by_role("button", name="Stop", exact=True)).to_be_visible()
+def open_creation(page, base_url):
+ page.goto(f"{base_url}/admin/code")
+ page.get_by_role("button", name="New code session", exact=True).click()
+ return page.get_by_role("dialog", name="New code session", exact=True)
+
+
+def test_settings_apply_preserves_open_creation_and_picker(
+ page, admin_base_url, tmp_path, code_control
+):
+ pending = []
+ page.route("**/admin/api/config/apply", lambda route: pending.append(route))
+ page.goto(f"{admin_base_url}/admin")
+ expect(page.locator("#messageArea")).to_have_text("")
+ page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")
+ page.get_by_role("button", name="Apply", exact=True).click()
+ expect(page.locator("#messageArea")).to_have_text("Checking API keys…")
+ assert len(pending) == 1
+ page.get_by_role("button", name="Code sessions", exact=True).click()
+ page.get_by_role("button", name="New code session", exact=True).click()
+ form = page.get_by_role("dialog", name="New code session", exact=True)
+ form.get_by_role("button", name="Browse…", exact=True).click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+
+ pending.pop().fulfill(json={"applied": True, "credential_checks": []})
+ expect(page.locator("#messageArea")).to_have_text("Applied")
+ expect(form).to_be_visible()
+ code_control.run(code_control.folder_picker.finish(call, str(tmp_path)))
+ expect(form.get_by_role("textbox", name="Folder", exact=True)).to_have_value(
+ str(tmp_path)
+ )
+ form.get_by_role("button", name="Create session", exact=True).click()
+ expect(page).to_have_url(re.compile(r"/admin/code/[0-9a-f-]+$"))
+ sessions = page.request.get(f"{admin_base_url}/admin/api/code/sessions").json()[
+ "sessions"
+ ]
+ assert [session["cwd"] for session in sessions] == [str(tmp_path.resolve())]
+
+
+ ("suffix", "display"), [("\nA", "␊A"), ("\rA", "␍A"), ("\r\nA", "␍␊A")]
+)
+def test_picker_preserves_line_breaks_in_hint_and_submission(
+ page, admin_base_url, tmp_path, code_control, suffix, display
+):
+ selected = str(tmp_path / f"project{suffix}")
+ form = open_creation(page, admin_base_url)
+ folder = form.get_by_role("textbox", name="Folder", exact=True)
+ browse = form.get_by_role("button", name="Browse…", exact=True)
+ browse.click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ code_control.run(code_control.folder_picker.finish(call, selected))
+ expect(browse).to_be_enabled()
+ # Returning to Browse must use the real path, even after a native Cancel.
+ browse.click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ assert call[0] == selected
+ code_control.run(code_control.folder_picker.finish(call, None))
+ with page.expect_response("**/admin/api/code/sessions") as submission:
+ form.get_by_role("button", name="Create session", exact=True).click()
+ assert submission.value.request.post_data_json["cwd"] == selected
+ # The directory deliberately does not exist; the form stays available.
+ expect(folder).to_have_value(str(tmp_path / f"project{display}"))
+ expect(folder).not_to_be_editable()
+
+
[email protected]("replacement", ["manual", "browse"])
+def test_replacing_line_break_selection_uses_the_new_path(
+ page, admin_base_url, tmp_path, code_control, replacement
+):
+ form = open_creation(page, admin_base_url)
+ folder = form.get_by_role("textbox", name="Folder", exact=True)
+ browse = form.get_by_role("button", name="Browse…", exact=True)
+ browse.click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ code_control.run(
+ code_control.folder_picker.finish(call, str(tmp_path / "project\nA"))
+ )
+ expect(browse).to_be_enabled()
+ expect(folder).not_to_be_editable()
+ if replacement == "manual":
+ form.get_by_role("button", name="Enter path manually", exact=True).click()
+ expect(folder).to_have_value("")
+ else:
+ browse.click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ code_control.run(code_control.folder_picker.finish(call, str(tmp_path)))
+ expect(folder).to_have_value(str(tmp_path))
+ expect(folder).to_be_editable()
+ expect(
+ form.get_by_role("button", name="Enter path manually", exact=True)
+ ).to_be_hidden()
+ replacement_folder = tmp_path / "manual replacement"
+ replacement_folder.mkdir()
+ folder.fill(str(replacement_folder))
+ form.get_by_role("button", name="Create session", exact=True).click()
+ expect(page).to_have_url(re.compile(r"/admin/code/[0-9a-f-]+$"))
+ sessions = page.request.get(f"{admin_base_url}/admin/api/code/sessions").json()[
+ "sessions"
+ ]
+ assert [session["cwd"] for session in sessions] == [
+ str(replacement_folder.resolve())
+ ]
+
+
[email protected](sys.platform == "win32", reason="Windows forbids CR/LF in names")
+def test_picker_creates_in_selected_folder_not_its_line_break_free_neighbor(
+ page, admin_base_url, tmp_path, code_control
+):
+ selected = tmp_path / "project\r\nA"
+ selected.mkdir()
+ (tmp_path / "projectA").mkdir()
+ form = open_creation(page, admin_base_url)
+ form.get_by_role("button", name="Browse…", exact=True).click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ code_control.run(code_control.folder_picker.finish(call, str(selected)))
+ form.get_by_role("button", name="Create session", exact=True).click()
+ expect(page).to_have_url(re.compile(r"/admin/code/[0-9a-f-]+$"))
+ sessions = page.request.get(f"{admin_base_url}/admin/api/code/sessions").json()[
+ "sessions"
+ ]
+ assert [session["cwd"] for session in sessions] == [str(selected.resolve())]
+
+
+def test_browse_fills_only_its_tab_and_waits_for_create(
+ page, context, admin_base_url, tmp_path, code_control
+):
+ second = context.new_page()
+ try:
+ other = open_creation(second, admin_base_url)
+ other.get_by_role("textbox", name="Folder", exact=True).fill("other tab")
+ form = open_creation(page, admin_base_url)
+ folder = form.get_by_role("textbox", name="Folder", exact=True)
+ folder.fill(str(tmp_path))
+ form.get_by_role("button", name="Browse…", exact=True).click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ assert call[0] == str(tmp_path)
+ expect(folder).to_be_disabled()
+ expect(
+ form.get_by_role("button", name="Create session", exact=True)
+ ).to_be_disabled()
+ other.get_by_role("button", name="Browse…", exact=True).click()
+ expect(
+ other.get_by_text("A folder picker is already open", exact=True)
+ ).to_be_visible()
+ selected = tmp_path / "project café with spaces"
+ selected.mkdir()
+ code_control.run(code_control.folder_picker.finish(call, str(selected)))
+ expect(folder).to_have_value(str(selected))
+ expect(folder).to_be_enabled()
+ expect(other.get_by_role("textbox", name="Folder", exact=True)).to_have_value(
+ "other tab"
+ )
+ expect(page).to_have_url(f"{admin_base_url}/admin/code")
+ assert (
+ page.request.get(f"{admin_base_url}/admin/api/code/sessions").json()[
+ "sessions"
+ ]
+ == []
+ )
+ other.get_by_role("button", name="Cancel", exact=True).click()
+ form.get_by_role("button", name="Create session", exact=True).click()
+ expect(page).to_have_url(re.compile(r"/admin/code/[0-9a-f-]+$"))
+ expect(
+ second.get_by_role("button", name=re.compile("project café"))
+ ).to_be_visible()
+ sessions = page.request.get(f"{admin_base_url}/admin/api/code/sessions").json()[
+ "sessions"
+ ]
+ assert [session["cwd"] for session in sessions] == [str(selected.resolve())]
+ finally:
+ second.close()
+
+
[email protected]("failure", [False, True])
+def test_picker_cancel_or_error_preserves_manual_entry(
+ page, admin_base_url, tmp_path, code_control, failure
+):
+ form = open_creation(page, admin_base_url)
+ folder = form.get_by_role("textbox", name="Folder", exact=True)
+ folder.fill(str(tmp_path))
+ form.get_by_role("button", name="Browse…", exact=True).click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ if failure:
+ code_control.run(code_control.folder_picker.fail(call))
+ expect(
+ form.get_by_text(
+ "Could not open the folder picker. Enter the path manually.", exact=True
+ )
+ ).to_be_visible()
+ else:
+ code_control.run(code_control.folder_picker.finish(call, None))
+ expect(folder).to_have_value(str(tmp_path))
+ expect(folder).to_be_enabled()
+ form.get_by_role("button", name="Create session", exact=True).click()
+ expect(page).to_have_url(re.compile(r"/admin/code/[0-9a-f-]+$"))
+
+
[email protected]("leave", ["cancel", "escape", "refresh", "navigate", "view"])
+def test_dismissing_creation_closes_native_picker(
+ page, admin_base_url, code_control, leave
+):
+ form = open_creation(page, admin_base_url)
+ form.get_by_role("button", name="Browse…", exact=True).click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ if leave == "cancel":
+ form.get_by_role("button", name="Cancel", exact=True).click()
+ elif leave == "escape":
+ page.keyboard.press("Escape")
+ elif leave == "refresh":
+ page.reload()
+ elif leave == "view":
+ page.evaluate(
+ "history.pushState({}, '', '/admin'); window.dispatchEvent(new PopStateEvent('popstate'))"
+ )
+ else:
+ # Browser history works even with the modal's background made inert.
+ page.go_back()
+ code_control.run(call[2].wait())
+ expect(form).to_have_count(0)
+
+
+def test_closed_form_ignores_a_late_picker_response(
+ page, admin_base_url, tmp_path, code_control
+):
+ form = open_creation(page, admin_base_url)
+ page.evaluate("""() => {
+ const original = window.fetch;
+ window.fetch = async (...args) => {
+ const response = await original(...args);
+ if (String(args[0]).endsWith('/folder-picker')) {
+ window.pickerCaptured = true;
+ await new Promise(resolve => { window.releasePicker = resolve; });
+ }
+ return response;
+ };
+ }""")
+ form.get_by_role("button", name="Browse…", exact=True).click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ code_control.run(code_control.folder_picker.finish(call, str(tmp_path)))
+ page.wait_for_function("window.pickerCaptured === true")
+ form.get_by_role("button", name="Cancel", exact=True).click()
+ page.get_by_role("button", name="New code session", exact=True).click()
+ folder = page.get_by_role("textbox", name="Folder", exact=True)
+ folder.fill("new form")
+ page.evaluate("window.releasePicker()")
+ expect(folder).to_have_value("new form")
+
+
+def test_existing_session_keeps_streaming_while_folder_picker_is_open(
+ page, context, admin_base_url, tmp_path, code_control
+):
+ url = create_session(page, admin_base_url, tmp_path)
+ send(page, "Keep running")
+ connection = code_control.connection()
+ observer = context.new_page()
+ try:
+ observer.goto(url)
+ form = open_creation(page, admin_base_url)
+ form.get_by_role("button", name="Browse…", exact=True).click()
+ call = code_control.run(code_control.folder_picker.calls.get())
+ code_control.run(
+ connection.text(
+ "turn-1", "reply", "Update during folder selection", complete=True
+ )
+ )
+ expect(
+ observer.get_by_text("Update during folder selection", exact=True)
+ ).to_be_visible()
+ code_control.run(connection.finish("turn-1"))
+ expect(form).to_be_visible()
+ expect(form.get_by_role("textbox", name="Folder", exact=True)).to_be_disabled()
+ code_control.run(code_control.folder_picker.finish(call, None))
+ expect(form.get_by_role("textbox", name="Folder", exact=True)).to_be_enabled()
+ finally:
+ observer.close()
+
+
def test_code_streams_survive_refresh_and_all_viewers_leaving(
page, context, admin_base_url, tmp_path, code_control
):
diff --git a/pyproject.toml b/pyproject.toml
index f62abf71..db4a95a0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "6.0.0"
+version = "6.1.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index 3a668700..88de1bdc 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -167,6 +167,7 @@ function setActiveView(viewId, { scroll = false } = {}) {
window.scrollTo({ top: 0, behavior: "smooth" });
}
if (activeView.id === "code") window.CodeSessions.activate(window.location.pathname);
+ else window.CodeSessions.deactivate();
}
function navigateToView(viewId) {
@@ -547,7 +548,7 @@ function updateProviderCheckResult(providerId, status, message) {
function renderSections(sections, fields) {
state.modelComboboxes.clear();
- VIEW_GROUPS.forEach((view) => {
+ VIEW_GROUPS.filter((view) => view.sections.length).forEach((view) => {
byId(view.containerId).innerHTML = "";
});
diff --git a/src/free_claude_code/api/admin_static/code_sessions.css b/src/free_claude_code/api/admin_static/code_sessions.css
index 5e67451f..6c5bf906 100644
--- a/src/free_claude_code/api/admin_static/code_sessions.css
+++ b/src/free_claude_code/api/admin_static/code_sessions.css
@@ -59,6 +59,14 @@
.code-field small {
color: var(--muted);
}
+.code-folder-row {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) auto;
+ gap: 8px;
+}
+.code-folder-row input {
+ min-width: 0;
+}
.code-field input:not([type="checkbox"]):not([type="radio"]),
.code-field select,
.code-dialog input,
diff --git a/src/free_claude_code/api/admin_static/code_sessions.js b/src/free_claude_code/api/admin_static/code_sessions.js
index 4a0055c0..6b05c0a9 100644
--- a/src/free_claude_code/api/admin_static/code_sessions.js
+++ b/src/free_claude_code/api/admin_static/code_sessions.js
@@ -35,6 +35,7 @@
libraryLoading = false,
notice = "",
available = false;
+ let activeDialog = null;
function element(tag, text, className) {
const node = document.createElement(tag);
@@ -401,6 +402,7 @@
activate(path);
}
function activate(path) {
+ if (path !== desiredPath) dismissDialog();
desiredPath = path;
if (!api) return;
let id = /^\/admin\/code\/([0-9a-f-]+)$/.exec(path)?.[1] || null;
@@ -517,34 +519,69 @@
}
render();
}
+ function dismissDialog() {
+ activeDialog?.();
+ }
function dialog(title, build, actionLabel, action) {
+ dismissDialog();
const node = element("dialog", undefined, "code-dialog"),
form = element("form");
+ const controller = new AbortController();
+ let disposed = false;
const heading = element("h3", title),
error = element("p", "", "code-notice");
+ error.setAttribute("role", "status");
heading.id = `code-dialog-${crypto.randomUUID()}`;
node.setAttribute("aria-labelledby", heading.id);
form.append(heading);
- const value = build(form);
const actions = element("div", undefined, "code-actions");
- const cancel = button("Cancel", () => node.close());
+ const cancel = button("Cancel", close);
const confirm = button(actionLabel, () => {}, "primary-button");
confirm.type = "submit";
+ const context = {
+ signal: controller.signal,
+ isOpen: () => !disposed && node.open && node.isConnected,
+ isBusy: () => confirm.disabled,
+ setBusy(value) {
+ for (const control of form.querySelectorAll("input, select, button"))
+ if (control !== cancel) control.disabled = value;
+ },
+ message(text) {
+ error.textContent = text;
+ },
+ };
+ function close() {
+ if (disposed) return;
+ disposed = true;
+ controller.abort();
+ if (activeDialog === close) activeDialog = null;
+ node.close();
+ node.remove();
+ }
+ const value = build(form, context);
actions.append(cancel, confirm);
form.append(error, actions);
node.append(form);
- node.addEventListener("close", () => node.remove());
+ node.addEventListener("close", close);
+ node.addEventListener("cancel", (event) => {
+ event.preventDefault();
+ close();
+ });
form.addEventListener("submit", async (event) => {
event.preventDefault();
- confirm.disabled = true;
+ if (!context.isOpen() || context.isBusy()) return;
+ context.setBusy(true);
try {
- await action(value);
- node.close();
+ await action(value, context);
+ if (context.isOpen()) close();
} catch (failure) {
- error.textContent = failure.message;
- confirm.disabled = false;
+ if (context.isOpen()) {
+ context.message(failure.message);
+ context.setBusy(false);
+ }
}
});
+ activeDialog = close;
root.append(node);
node.showModal();
}
@@ -552,34 +589,85 @@
const id = crypto.randomUUID();
dialog(
"New code session",
- (form) => {
+ (form, context) => {
const harness = element("select");
harness.append(new Option("Codex", "codex"));
const folder = element("input");
folder.required = true;
folder.autocomplete = "off";
label(form, "Harness", harness);
- label(form, "Folder", folder);
+ const field = element("div", undefined, "code-field");
+ const caption = element("label", "Folder");
+ folder.id = `code-folder-${id}`;
+ caption.htmlFor = folder.id;
+ const row = element("div", undefined, "code-folder-row");
+ let selectedPath = null;
+ const readFolder = () => selectedPath ?? folder.value;
+ const lineBreakNotice = element("p", "", "code-notice");
+ lineBreakNotice.id = `${folder.id}-notice`;
+ folder.setAttribute("aria-describedby", lineBreakNotice.id);
+ const manual = button("Enter path manually", () => {
+ setFolder("");
+ folder.focus();
+ });
+ manual.hidden = true;
+ function setFolder(path) {
+ const hasLineBreaks = /[\r\n]/.test(path);
+ selectedPath = hasLineBreaks ? path : null;
+ folder.readOnly = hasLineBreaks;
+ folder.value = path.replaceAll("\r", "␍").replaceAll("\n", "␊");
+ manual.hidden = !hasLineBreaks;
+ lineBreakNotice.textContent = hasLineBreaks
+ ? "Line breaks in this folder name are shown as ␍ and ␊."
+ : "";
+ }
+ const browse = button("Browse…", async () => {
+ if (!context.isOpen() || context.isBusy()) return;
+ const initial = readFolder();
+ context.setBusy(true);
+ context.message("Choose a folder in the open folder picker.");
+ try {
+ const result = await api(`${base}/folder-picker`, {
+ method: "POST",
+ body: JSON.stringify({ initial_path: initial || null }),
+ signal: context.signal,
+ });
+ if (context.isOpen()) {
+ if (result.path !== null) setFolder(result.path);
+ context.message("");
+ }
+ } catch (failure) {
+ if (context.isOpen()) context.message(failure.message);
+ } finally {
+ if (context.isOpen()) {
+ context.setBusy(false);
+ folder.focus();
+ }
+ }
+ });
+ row.append(folder, browse);
+ field.append(caption, row, lineBreakNotice, manual);
+ form.append(field);
form.append(
element(
"p",
- "Choose an existing folder on the computer running FCC.",
+ "Choose an existing folder on the computer running FCC. You can also enter its path manually.",
"code-notice",
),
);
- return folder;
+ return readFolder;
},
"Create session",
- async (folder) => {
+ async (readFolder, context) => {
await api(`${base}/sessions`, {
method: "POST",
body: JSON.stringify({
session_id: id,
harness: "codex",
- cwd: folder.value,
+ cwd: readFolder(),
}),
});
- navigate(id);
+ if (context.isOpen()) navigate(id);
},
);
}
@@ -670,6 +758,7 @@
return node;
}
function shell() {
+ dismissDialog();
root.replaceChildren();
modelComboboxes.clear();
modelControl = reasoningControl = null;
@@ -1289,6 +1378,7 @@
}
form.append(actions);
}
+ window.addEventListener("pagehide", dismissDialog);
window.CodeSessions = {
initialize(client) {
api = client;
@@ -1296,6 +1386,7 @@
if (desiredPath) activate(desiredPath);
},
activate,
+ deactivate: dismissDialog,
async refresh() {
if (!api || !epoch) return;
try {
diff --git a/src/free_claude_code/api/app.py b/src/free_claude_code/api/app.py
index 60552bfb..215315fb 100644
--- a/src/free_claude_code/api/app.py
+++ b/src/free_claude_code/api/app.py
@@ -36,7 +36,7 @@ from .request_ids import (
attach_request_id_headers,
get_request_id,
)
-from .request_lifetime import InferenceRequestLifetimeMiddleware
+from .request_lifetime import ClientRequestLifetimeMiddleware
from .routes import router
from .validation_log import summarize_request_validation_body
@@ -46,7 +46,7 @@ def create_app(services: ApiServices) -> FastAPI:
app = FastAPI(title="Claude Code Proxy", version=package_version())
app.state.services = services
app.add_middleware(AdminNoStoreMiddleware)
- app.add_middleware(InferenceRequestLifetimeMiddleware)
+ app.add_middleware(ClientRequestLifetimeMiddleware)
app.add_middleware(RequestCorrelationMiddleware)
app.include_router(admin_router)
diff --git a/src/free_claude_code/api/code_sessions_routes.py b/src/free_claude_code/api/code_sessions_routes.py
index df5b97b2..e5ee93c8 100644
--- a/src/free_claude_code/api/code_sessions_routes.py
+++ b/src/free_claude_code/api/code_sessions_routes.py
@@ -5,7 +5,7 @@ import json
from collections.abc import AsyncIterator, Mapping
from typing import Literal
-from fastapi import APIRouter, Depends, Query, Request
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
from fastapi.sse import EventSourceResponse, ServerSentEvent
from pydantic import BaseModel, ConfigDict, Field
@@ -19,6 +19,7 @@ from free_claude_code.application.code_sessions import (
CodeUnavailableError,
CodeValidationError,
)
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.session_events import EventOverflowError
from free_claude_code.core.json_types import JsonObject, JsonValue
@@ -41,6 +42,10 @@ class CreatePayload(CommandPayload):
harness: Literal["codex"] = "codex"
+class FolderPickerPayload(CommandPayload):
+ initial_path: str | None = Field(default=None, max_length=4096)
+
+
class SettingsPayload(CommandPayload):
expected_revision: int = Field(gt=0)
title: str | None = Field(default=None, min_length=1, max_length=200)
@@ -91,6 +96,16 @@ def bootstrap(services: ApiServices = Depends(get_services)) -> JsonObject:
}
[email protected]("/admin/api/code/folder-picker")
+async def pick_folder(
+ payload: FolderPickerPayload, services: ApiServices = Depends(get_services)
+) -> JsonObject:
+ try:
+ return {"path": await services.admin.pick_folder(payload.initial_path)}
+ except ApplicationUnavailableError as exc:
+ raise HTTPException(status_code=503, detail=exc.message) from exc
+
+
@router.get("/admin/api/code/events", response_class=EventSourceResponse)
async def events(
services: ApiServices = Depends(get_services),
diff --git a/src/free_claude_code/api/ports.py b/src/free_claude_code/api/ports.py
index 053eba79..b7d13e3d 100644
--- a/src/free_claude_code/api/ports.py
+++ b/src/free_claude_code/api/ports.py
@@ -28,6 +28,8 @@ class AdminRuntimePort(Protocol):
async def admin_status(self) -> JsonObject: ...
+ async def pick_folder(self, initial_path: str | None) -> str | None: ...
+
async def test_provider(self, provider_id: str) -> JsonObject: ...
async def refresh_models(self) -> ProviderModelRefreshResult: ...
diff --git a/src/free_claude_code/api/request_lifetime.py b/src/free_claude_code/api/request_lifetime.py
index 91771a6a..70afdc5a 100644
--- a/src/free_claude_code/api/request_lifetime.py
+++ b/src/free_claude_code/api/request_lifetime.py
@@ -1,14 +1,16 @@
-"""Client-owned lifetime boundary for long-running inference requests."""
+"""Client-owned lifetime boundary for long-running HTTP requests."""
import asyncio
from starlette.types import ASGIApp, Message, Receive, Scope, Send
-_INFERENCE_PATHS = frozenset({"/v1/messages", "/v1/responses"})
+_CLIENT_OWNED_PATHS = frozenset(
+ {"/v1/messages", "/v1/responses", "/admin/api/code/folder-picker"}
+)
-class InferenceRequestLifetimeMiddleware:
- """Cancel inference when its HTTP client disconnects."""
+class ClientRequestLifetimeMiddleware:
+ """Cancel client-owned operations when their HTTP client disconnects."""
def __init__(self, app: ASGIApp) -> None:
self._app = app
@@ -19,7 +21,7 @@ class InferenceRequestLifetimeMiddleware:
receive: Receive,
send: Send,
) -> None:
- if not _owns_inference_lifetime(scope):
+ if not _owns_client_lifetime(scope):
await self._app(scope, receive, send)
return
@@ -40,11 +42,11 @@ class InferenceRequestLifetimeMiddleware:
application_task = asyncio.create_task(
run_application(),
- name="fcc-inference-application",
+ name="fcc-client-application",
)
receive_task = asyncio.create_task(
receive_until_disconnect(),
- name="fcc-inference-disconnect-receiver",
+ name="fcc-client-disconnect-receiver",
)
try:
done, _pending = await asyncio.wait(
@@ -70,18 +72,18 @@ class InferenceRequestLifetimeMiddleware:
except asyncio.CancelledError:
cleanup_task = asyncio.create_task(
_cancel_and_wait(application_task, receive_task),
- name="fcc-inference-lifetime-cleanup",
+ name="fcc-client-lifetime-cleanup",
)
await _wait_for_cleanup(cleanup_task)
raise
-def _owns_inference_lifetime(scope: Scope) -> bool:
+def _owns_client_lifetime(scope: Scope) -> bool:
path = scope.get("path")
return (
scope["type"] == "http"
and scope.get("method") == "POST"
- and path in _INFERENCE_PATHS
+ and path in _CLIENT_OWNED_PATHS
)
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index 75f666e1..b3aff1bd 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -48,6 +48,7 @@ from free_claude_code.providers.credential_validation import (
)
from .configuration import ConfigurationService
+from .folder_picker import NativeFolderPicker
from .provider_manager import ProviderRuntimeManager
from .retired_chat import remove_retired_chat_history
@@ -148,6 +149,7 @@ class ApplicationRuntime:
self.provider_manager = provider_manager
self._configuration = configuration
self._code_service = code_service
+ self._folder_picker = NativeFolderPicker()
self._transcriber = transcriber
self._restart_callback = restart_callback
self._connected_accounts = dict(connected_accounts or {})
@@ -226,6 +228,7 @@ class ApplicationRuntime:
def begin_shutdown(self) -> None:
"""Finish indefinite observer responses before the server drains HTTP."""
self._draining = True
+ self._folder_picker.begin_shutdown()
if self._code_service is not None:
self._code_service.begin_shutdown()
@@ -246,6 +249,9 @@ class ApplicationRuntime:
)
return self._closed
+ async def pick_folder(self, initial_path: str | None) -> str | None:
+ return await self._folder_picker.pick_folder(initial_path)
+
async def apply_admin_config(
self,
updates: Mapping[str, ConfigInputValue],
@@ -585,6 +591,8 @@ class ApplicationRuntime:
logger.info("{} platform started with messaging workflow", components.name)
async def _close_owned_resources(self) -> bool:
+ if not await best_effort("folder_picker.close", self._folder_picker.close()):
+ return False
if not await self._cleanup_messaging():
return False
verbose = self.settings.log_api_error_tracebacks
diff --git a/src/free_claude_code/runtime/folder_picker.py b/src/free_claude_code/runtime/folder_picker.py
new file mode 100644
index 00000000..6de4af64
--- /dev/null
+++ b/src/free_claude_code/runtime/folder_picker.py
@@ -0,0 +1,134 @@
+"""Own the native folder dialog for one client request at a time."""
+
+import asyncio
+import json
+import os
+import signal
+import subprocess
+import sys
+from contextlib import suppress
+from pathlib import Path
+
+from loguru import logger
+
+from free_claude_code.application.errors import ApplicationUnavailableError
+from free_claude_code.cli.process_registry import register_pid, unregister_pid
+
+_UNAVAILABLE = "Could not open the folder picker. Enter the path manually."
+
+
+def _unavailable(exc: Exception) -> ApplicationUnavailableError:
+ logger.warning("Folder picker failed: {}: {}", type(exc).__name__, exc)
+ return ApplicationUnavailableError(_UNAVAILABLE)
+
+
+class NativeFolderPicker:
+ def __init__(self) -> None:
+ self._active: asyncio.Task[str | None] | None = None
+ self._stop = asyncio.Event()
+ self._closed = False
+
+ async def pick_folder(self, initial_path: str | None) -> str | None:
+ if self._closed:
+ raise ApplicationUnavailableError("FCC is shutting down.")
+ if self._active is not None:
+ raise ApplicationUnavailableError("A folder picker is already open")
+ self._stop = asyncio.Event()
+ task = self._active = asyncio.create_task(
+ self._select(initial_path, self._stop), name="fcc-folder-picker"
+ )
+ try:
+ return await self._join(task)
+ except ApplicationUnavailableError:
+ raise
+ except Exception as exc:
+ raise _unavailable(exc) from exc
+ finally:
+ self._active = None
+
+ def begin_shutdown(self) -> None:
+ self._closed = True
+ self._stop.set()
+
+ async def close(self) -> None:
+ self.begin_shutdown()
+ if self._active is not None:
+ # The request reports selection failures after the child is reaped.
+ with suppress(ApplicationUnavailableError):
+ await self._join(self._active)
+
+ async def _join(self, task: asyncio.Task[str | None]) -> str | None:
+ cancellation: asyncio.CancelledError | None = None
+ while not task.done():
+ try:
+ # Never cancel spawn/cleanup: signal the owned operation instead.
+ await asyncio.wait({task})
+ except asyncio.CancelledError as exc:
+ cancellation = exc
+ self._stop.set()
+ if cancellation is not None:
+ if not task.cancelled():
+ task.exception()
+ raise cancellation
+ return task.result()
+
+ async def _spawn(self, initial_path: str | None) -> asyncio.subprocess.Process:
+ return await asyncio.create_subprocess_exec(
+ sys.executable,
+ "-m",
+ "free_claude_code.runtime.native_folder_dialog",
+ initial_path or "",
+ stdin=asyncio.subprocess.DEVNULL,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ creationflags=subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0,
+ start_new_session=sys.platform != "win32",
+ )
+
+ async def _select(
+ self, initial_path: str | None, stop: asyncio.Event
+ ) -> str | None:
+ try:
+ process = await self._spawn(initial_path)
+ except (OSError, ValueError) as exc:
+ raise _unavailable(exc) from exc
+ register_pid(process.pid)
+ reading = asyncio.create_task(process.communicate())
+ stopped = asyncio.create_task(stop.wait())
+ try:
+ await asyncio.wait((reading, stopped), return_when=asyncio.FIRST_COMPLETED)
+ if stop.is_set():
+ return None
+ stdout, stderr = reading.result()
+ if process.returncode != 0:
+ raise RuntimeError(stderr.decode("utf-8", errors="replace"))
+ result = json.loads(stdout)
+ if not isinstance(result, dict) or "path" not in result:
+ raise ValueError("Missing folder selection")
+ path = result["path"]
+ if path is not None and (
+ not isinstance(path, str)
+ or not path
+ or "\0" in path
+ or not Path(path).is_absolute()
+ ):
+ raise ValueError("Invalid folder selection")
+ return path
+ except Exception as exc:
+ raise _unavailable(exc) from exc
+ finally:
+ try:
+ if process.returncode is None or not reading.done():
+ try:
+ if sys.platform == "win32":
+ process.kill()
+ else:
+ os.killpg(process.pid, signal.SIGKILL)
+ except ProcessLookupError:
+ pass
+ await process.wait()
+ await reading
+ finally:
+ stopped.cancel()
+ await asyncio.gather(stopped, return_exceptions=True)
+ unregister_pid(process.pid)
diff --git a/src/free_claude_code/runtime/native_folder_dialog.py b/src/free_claude_code/runtime/native_folder_dialog.py
new file mode 100644
index 00000000..a6c8870e
--- /dev/null
+++ b/src/free_claude_code/runtime/native_folder_dialog.py
@@ -0,0 +1,119 @@
+"""Short-lived OS dialog helper; stdout carries only its JSON result."""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+_TITLE = "Choose a Code Session folder"
+_MAC_SCRIPT = """
+on run argv
+ try
+ if item 1 of argv is "" then
+ set chosen to choose folder with prompt "Choose a Code Session folder"
+ else
+ set chosen to choose folder with prompt "Choose a Code Session folder" default location (POSIX file (item 1 of argv))
+ end if
+ return POSIX path of chosen
+ on error messageText number errorNumber
+ if errorNumber is -128 then return ""
+ error messageText number errorNumber
+ end try
+end run
+"""
+_DISPLAY_ERRORS = (
+ "cannot open display",
+ "failed to open display",
+ "no qt platform plugin could be initialized",
+ "could not connect to display",
+)
+
+
+def _initial_directory(value: str) -> str | None:
+ if value:
+ try:
+ path = Path(value).expanduser().resolve(strict=True)
+ if path.is_dir():
+ return str(path)
+ except OSError, ValueError:
+ pass
+ return None
+
+
+def _windows(initial: str | None) -> str | None:
+ import tkinter
+ from tkinter import filedialog
+
+ root = tkinter.Tk()
+ root.withdraw()
+ try:
+ root.attributes("-topmost", True)
+ return (
+ filedialog.askdirectory(
+ parent=root, title=_TITLE, initialdir=initial or "", mustexist=True
+ )
+ or None
+ )
+ finally:
+ root.destroy()
+
+
+def _macos(initial: str | None) -> str | None:
+ result = subprocess.run(
+ ["/usr/bin/osascript", "-e", _MAC_SCRIPT, initial or ""],
+ capture_output=True,
+ check=True,
+ )
+ return result.stdout.decode("utf-8").removesuffix("\n") or None
+
+
+def _linux(initial: str | None) -> str | None:
+ env = os.environ.copy()
+ if executable := shutil.which("zenity"):
+ command = [executable, "--file-selection", "--directory", f"--title={_TITLE}"]
+ if initial:
+ command.append(f"--filename={initial.rstrip('/')}/")
+ env = {
+ key: value for key, value in env.items() if not key.startswith("ZENITY_")
+ }
+ elif executable := shutil.which("kdialog"):
+ command = [executable, "--title", _TITLE, "--getexistingdirectory"]
+ if initial:
+ command.append(initial)
+ else:
+ raise RuntimeError("No desktop folder picker is available")
+ result = subprocess.run(command, capture_output=True, env=env, check=False)
+ path = result.stdout.decode("utf-8").removesuffix("\n")
+ if result.returncode == 0 and path:
+ return path
+ diagnostic = result.stderr.decode("utf-8", errors="replace")
+ if any(message in diagnostic.lower() for message in _DISPLAY_ERRORS):
+ raise RuntimeError(diagnostic)
+ if result.returncode == 1:
+ return None
+ raise RuntimeError(diagnostic or "Folder picker returned no directory")
+
+
+def main() -> int:
+ try:
+ initial = _initial_directory(sys.argv[1] if len(sys.argv) > 1 else "")
+ if sys.platform == "win32":
+ path = _windows(initial)
+ elif sys.platform == "darwin":
+ path = _macos(initial)
+ elif sys.platform.startswith("linux"):
+ path = _linux(initial)
+ else:
+ raise RuntimeError("No native folder picker for this platform")
+ print(json.dumps({"path": path}, ensure_ascii=True))
+ return 0
+ except Exception as exc:
+ print(f"{type(exc).__name__}: {exc}", file=sys.stderr)
+ print(json.dumps({"error": "unavailable"}))
+ return 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/api/test_code_sessions_routes.py b/tests/api/test_code_sessions_routes.py
index ead849da..3d9f693c 100644
--- a/tests/api/test_code_sessions_routes.py
+++ b/tests/api/test_code_sessions_routes.py
@@ -6,6 +6,7 @@ import pytest
import pytest_asyncio
from free_claude_code.application.code_sessions import CodeService
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.runtime.code_sessions_sqlite import SQLiteCodeStore
from tests.api.support import create_test_app
from tests.code_sessions_support import FakeHarness
@@ -124,3 +125,74 @@ async def test_code_routes_share_admin_access_boundary(code_api, headers):
response = await client.get(path, headers=headers)
assert response.status_code == 403
assert harness.connections == []
+
+
[email protected]("cancelled", [False, True])
+async def test_folder_selection_only_returns_to_requesting_form(
+ code_api, monkeypatch, cancelled
+):
+ client, _, harness, folder, app = code_api
+ selected = None if cancelled else str(folder)
+ hints = []
+
+ async def pick(initial_path):
+ hints.append(initial_path)
+ return selected
+
+ monkeypatch.setattr(app.state.services.admin, "pick_folder", pick)
+ response = await client.post(
+ "/admin/api/code/folder-picker", json={"initial_path": str(folder)}
+ )
+ assert response.status_code == 200
+ assert response.json() == {"path": selected}
+ assert response.headers["cache-control"] == "no-store"
+ assert hints == [str(folder)]
+ assert (await client.get("/admin/api/code/sessions")).json()["sessions"] == []
+ assert harness.connections == []
+
+
+async def test_folder_picker_errors_use_admin_detail(code_api, monkeypatch):
+ client, _, _, _, app = code_api
+
+ async def pick(_initial_path):
+ raise ApplicationUnavailableError("A folder picker is already open")
+
+ monkeypatch.setattr(app.state.services.admin, "pick_folder", pick)
+ response = await client.post("/admin/api/code/folder-picker", json={})
+ assert response.status_code == 503
+ assert response.json() == {"detail": "A folder picker is already open"}
+
+
+async def test_folder_picker_only_opens_on_an_authorized_explicit_post(
+ code_api, monkeypatch
+):
+ client, _, _, _, app = code_api
+
+ async def unexpected(_initial_path):
+ pytest.fail("Unauthorized or passive request opened a dialog")
+
+ monkeypatch.setattr(app.state.services.admin, "pick_folder", unexpected)
+ for headers in (
+ {"host": "remote.example"},
+ {"origin": "https://remote.example"},
+ ):
+ response = await client.post(
+ "/admin/api/code/folder-picker", json={}, headers=headers
+ )
+ assert response.status_code == 403
+ for payload in ({"initial_path": "x" * 4097}, {"other": True}):
+ response = await client.post("/admin/api/code/folder-picker", json=payload)
+ assert response.status_code == 422
+ async with httpx.AsyncClient(
+ transport=httpx.ASGITransport(app=app, client=("192.0.2.1", 1234)),
+ base_url="http://127.0.0.1",
+ ) as remote:
+ assert (
+ await remote.post("/admin/api/code/folder-picker", json={})
+ ).status_code == 403
+ assert (await client.get("/admin/api/code/folder-picker")).status_code == 405
+ assert (await client.get("/admin/code")).status_code == 200
+ assert (await client.get("/admin/api/code/bootstrap")).status_code == 200
diff --git a/tests/api/test_request_ids.py b/tests/api/test_request_ids.py
index ea1c75a5..41dd5a5a 100644
--- a/tests/api/test_request_ids.py
+++ b/tests/api/test_request_ids.py
@@ -16,7 +16,7 @@ from free_claude_code.api.request_ids import (
RequestCorrelationMiddleware,
get_request_id,
)
-from free_claude_code.api.request_lifetime import InferenceRequestLifetimeMiddleware
+from free_claude_code.api.request_lifetime import ClientRequestLifetimeMiddleware
from tests.api.support import create_test_app
@@ -48,7 +48,7 @@ def test_application_uses_the_pure_asgi_correlation_owner() -> None:
assert sum(cls is RequestCorrelationMiddleware for cls in middleware_classes) == 1
assert middleware_classes.index(
RequestCorrelationMiddleware
- ) < middleware_classes.index(InferenceRequestLifetimeMiddleware)
+ ) < middleware_classes.index(ClientRequestLifetimeMiddleware)
assert all(cls is not BaseHTTPMiddleware for cls in middleware_classes)
diff --git a/tests/api/test_request_lifetime.py b/tests/api/test_request_lifetime.py
index 4f897f4c..44d32c5c 100644
--- a/tests/api/test_request_lifetime.py
+++ b/tests/api/test_request_lifetime.py
@@ -1,4 +1,4 @@
-"""Inference request lifetime contracts at the pure-ASGI boundary."""
+"""Client-owned request lifetime contracts at the pure-ASGI boundary."""
import asyncio
import json
@@ -11,7 +11,7 @@ from starlette.types import ASGIApp, Message, Receive, Scope, Send
from free_claude_code.api.app import create_app
from free_claude_code.api.ports import AdminRuntimePort, ApiServices
from free_claude_code.api.request_lifetime import (
- InferenceRequestLifetimeMiddleware,
+ ClientRequestLifetimeMiddleware,
)
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.application.ports import (
@@ -65,7 +65,7 @@ async def _unused_send(_message: Message) -> None:
cast(Scope, {"type": "lifespan", "asgi": {"version": "3.0"}}),
],
)
-async def test_non_inference_scopes_delegate_with_original_callables(
+async def test_other_scopes_delegate_with_original_callables(
scope: Scope,
) -> None:
observed: tuple[Scope, Receive, Send] | None = None
@@ -84,7 +84,7 @@ async def test_non_inference_scopes_delegate_with_original_callables(
nonlocal observed
observed = (received_scope, received_receive, received_send)
- await InferenceRequestLifetimeMiddleware(cast(ASGIApp, app))(
+ await ClientRequestLifetimeMiddleware(cast(ASGIApp, app))(
scope,
receive,
send,
@@ -99,6 +99,7 @@ async def test_non_inference_scopes_delegate_with_original_callables(
[
"/v1/messages",
"/v1/responses",
+ "/admin/api/code/folder-picker",
],
)
async def test_request_body_frames_are_relayed_once_in_order(path: str) -> None:
@@ -132,7 +133,7 @@ async def test_request_body_frames_are_relayed_once_in_order(path: str) -> None:
received.append(await app_receive())
received.append(await app_receive())
- await InferenceRequestLifetimeMiddleware(cast(ASGIApp, app))(
+ await ClientRequestLifetimeMiddleware(cast(ASGIApp, app))(
_http_scope(path),
receive,
_unused_send,
@@ -162,7 +163,7 @@ async def test_receive_pump_buffers_only_a_bounded_number_of_frames() -> None:
await stop_app.wait()
request = asyncio.create_task(
- InferenceRequestLifetimeMiddleware(cast(ASGIApp, app))(
+ ClientRequestLifetimeMiddleware(cast(ASGIApp, app))(
_http_scope(),
receive,
_unused_send,
@@ -187,6 +188,8 @@ type DisconnectScenario = Callable[
async def _run_disconnect_scenario(
app: DisconnectScenario,
ready: asyncio.Event,
+ *,
+ path: str = "/v1/messages",
) -> list[Message]:
allow_disconnect = asyncio.Event()
body_consumed = asyncio.Event()
@@ -210,8 +213,8 @@ async def _run_disconnect_scenario(
sent.append(message)
request = asyncio.create_task(
- InferenceRequestLifetimeMiddleware(app)(
- _http_scope(),
+ ClientRequestLifetimeMiddleware(app)(
+ _http_scope(path),
receive,
send,
)
@@ -224,7 +227,10 @@ async def _run_disconnect_scenario(
@pytest.mark.asyncio
-async def test_disconnect_before_response_start_cancels_application() -> None:
+ "path", ["/v1/messages", "/v1/responses", "/admin/api/code/folder-picker"]
+)
+async def test_disconnect_before_response_start_cancels_application(path: str) -> None:
app_started = asyncio.Event()
app_closed = asyncio.Event()
@@ -236,7 +242,7 @@ async def test_disconnect_before_response_start_cancels_application() -> None:
finally:
app_closed.set()
- sent = await _run_disconnect_scenario(app, app_started)
+ sent = await _run_disconnect_scenario(app, app_started, path=path)
assert sent == []
assert app_closed.is_set()
@@ -303,7 +309,7 @@ async def test_application_error_wins_and_receive_pump_is_closed() -> None:
raise RuntimeError("application failed")
with pytest.raises(RuntimeError, match="application failed"):
- await InferenceRequestLifetimeMiddleware(cast(ASGIApp, app))(
+ await ClientRequestLifetimeMiddleware(cast(ASGIApp, app))(
_http_scope(),
receive,
_unused_send,
@@ -326,7 +332,7 @@ async def test_receive_error_cancels_application_and_is_preserved() -> None:
app_closed.set()
with pytest.raises(RuntimeError, match="receive failed"):
- await InferenceRequestLifetimeMiddleware(cast(ASGIApp, app))(
+ await ClientRequestLifetimeMiddleware(cast(ASGIApp, app))(
_http_scope(),
receive,
_unused_send,
@@ -365,7 +371,7 @@ async def test_outer_cancellation_drains_both_owned_tasks() -> None:
app_closed.set()
request = asyncio.create_task(
- InferenceRequestLifetimeMiddleware(cast(ASGIApp, app))(
+ ClientRequestLifetimeMiddleware(cast(ASGIApp, app))(
_http_scope(),
receive,
_unused_send,
diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.py
index d9eeb8b3..47cb67ac 100644
--- a/tests/runtime/test_application_runtime.py
+++ b/tests/runtime/test_application_runtime.py
@@ -1330,3 +1330,35 @@ async def test_composition_publishes_startup_notice_after_runtime_and_repair() -
assert "plans_directory" not in manager_constructor.call_args.kwargs
assert await runtime.close() is True
+
+
+async def test_folder_picker_is_stopped_before_http_shutdown_drains(monkeypatch):
+ import uvicorn
+
+ from free_claude_code.cli.commands import RuntimeServer
+
+ runtime, _manager = _runtime_with_admin_provider(AdminModelProvider())
+ started = asyncio.Event()
+ signals = []
+
+ async def select(_initial, stop):
+ signals.append(stop)
+ started.set()
+ await stop.wait()
+ return None
+
+ monkeypatch.setattr(runtime._folder_picker, "_select", select)
+ request = asyncio.create_task(runtime.pick_folder(None))
+ await started.wait()
+
+ async def drain(_server, sockets=None):
+ assert signals[0].is_set()
+ assert await request is None
+
+ monkeypatch.setattr(uvicorn.Server, "shutdown", drain)
+ server = RuntimeServer(
+ uvicorn.Config("unused:app"), begin_shutdown=runtime.begin_shutdown
+ )
+ await server.shutdown()
+ assert await runtime.close() is True
diff --git a/tests/runtime/test_folder_picker.py b/tests/runtime/test_folder_picker.py
new file mode 100644
index 00000000..6186f71e
--- /dev/null
+++ b/tests/runtime/test_folder_picker.py
@@ -0,0 +1,165 @@
+import asyncio
+import json
+import os
+import subprocess
+import sys
+
+import pytest
+
+from free_claude_code.application.errors import ApplicationUnavailableError
+from free_claude_code.runtime.folder_picker import NativeFolderPicker
+
+
+class DialogProcess:
+ """A real child, with barriers around the return from subprocess creation."""
+
+ def __init__(self, script):
+ self.script = script
+ self.started = asyncio.Event()
+ self.return_spawn = asyncio.Event()
+ self.return_spawn.set()
+ self.process: asyncio.subprocess.Process
+
+ async def spawn(self, _initial_path):
+ self.process = await asyncio.create_subprocess_exec(
+ sys.executable,
+ "-u",
+ "-c",
+ "print('ready', flush=True)\n" + self.script,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ creationflags=subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0,
+ start_new_session=sys.platform != "win32",
+ )
+ assert self.process.stdout is not None
+ assert (await self.process.stdout.readline()).rstrip(b"\r\n") == b"ready"
+ self.started.set()
+ await self.return_spawn.wait()
+ return self.process
+
+
[email protected]("cancelled", [False, True])
+async def test_selection_and_cancellation_return_after_child_exit(
+ monkeypatch, tmp_path, cancelled
+):
+ path = None if cancelled else str(tmp_path / "project café with spaces")
+ child = DialogProcess(f"print({json.dumps({'path': path})!r})")
+ picker = NativeFolderPicker()
+ monkeypatch.setattr(picker, "_spawn", child.spawn)
+ assert await picker.pick_folder(None) == path
+ assert child.process.returncode == 0
+ # Completion makes the next independent click available.
+ assert await picker.pick_folder(None) == path
+ await picker.close()
+
+
+async def test_selection_failure_racing_shutdown_is_reported_to_request(monkeypatch):
+ picker = NativeFolderPicker()
+ started = asyncio.Event()
+
+ async def spawn(_initial):
+ started.set()
+ await picker._stop.wait()
+ raise FileNotFoundError("Native picker disappeared while shutdown started")
+
+ monkeypatch.setattr(picker, "_spawn", spawn)
+ request = asyncio.create_task(picker.pick_folder(None))
+ await started.wait()
+ try:
+ await picker.close()
+ finally:
+ with pytest.raises(
+ ApplicationUnavailableError, match="Enter the path manually"
+ ):
+ await request
+
+
[email protected]("output", ['{"path": 42}', "{}", "not json", '{"path":""}'])
+async def test_invalid_child_result_gives_manual_entry_guidance(monkeypatch, output):
+ child = DialogProcess(f"print({output!r})")
+ picker = NativeFolderPicker()
+ monkeypatch.setattr(picker, "_spawn", child.spawn)
+ with pytest.raises(ApplicationUnavailableError, match="Enter the path manually"):
+ await picker.pick_folder(None)
+ assert child.process.returncode == 0
+ await picker.close()
+
+
+async def test_two_clicks_and_disconnect_during_spawn_keep_one_owned_child(monkeypatch):
+ child = DialogProcess("import threading\nthreading.Event().wait()")
+ child.return_spawn.clear()
+ picker = NativeFolderPicker()
+ monkeypatch.setattr(picker, "_spawn", child.spawn)
+ request = asyncio.create_task(picker.pick_folder(None))
+ try:
+ await child.started.wait()
+ request.cancel()
+ with pytest.raises(ApplicationUnavailableError, match="already open"):
+ await picker.pick_folder(None)
+ assert not request.done()
+ request.cancel()
+ child.return_spawn.set()
+ with pytest.raises(asyncio.CancelledError):
+ await request
+ assert child.process.returncode is not None
+ finally:
+ child.return_spawn.set()
+ await picker.close()
+
+
+async def test_shutdown_closes_picker_and_rejects_new_clicks(monkeypatch):
+ child = DialogProcess("import threading\nthreading.Event().wait()")
+ picker = NativeFolderPicker()
+ monkeypatch.setattr(picker, "_spawn", child.spawn)
+ request = asyncio.create_task(picker.pick_folder(None))
+ await child.started.wait()
+ picker.begin_shutdown()
+ with pytest.raises(ApplicationUnavailableError, match="shutting down"):
+ await picker.pick_folder(None)
+ await picker.close()
+ assert await request is None
+ assert child.process.returncode is not None
+ await picker.close()
+
+
+async def test_interrupted_close_still_waits_for_child_cleanup(monkeypatch):
+ child = DialogProcess("import threading\nthreading.Event().wait()")
+ child.return_spawn.clear()
+ picker = NativeFolderPicker()
+ monkeypatch.setattr(picker, "_spawn", child.spawn)
+ request = asyncio.create_task(picker.pick_folder(None))
+ await child.started.wait()
+ closing = asyncio.create_task(picker.close())
+ # The explicit stop signal acknowledges that close has started.
+ await picker._stop.wait()
+ closing.cancel()
+ child.return_spawn.set()
+ with pytest.raises(asyncio.CancelledError):
+ await closing
+ assert await request is None
+ assert child.process.returncode is not None
+
+
[email protected](os.name == "nt", reason="POSIX process group ownership")
+async def test_cancellation_reaps_a_helper_waiting_on_its_child(monkeypatch):
+ child = DialogProcess(
+ "import subprocess, sys\n"
+ "subprocess.run([sys.executable, '-c', 'import threading; threading.Event().wait()'])"
+ )
+ picker = NativeFolderPicker()
+ monkeypatch.setattr(picker, "_spawn", child.spawn)
+ request = asyncio.create_task(picker.pick_folder(None))
+ await child.started.wait()
+ request.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await request
+ # communicate() also waits for pipes inherited by descendants to close.
+ assert child.process.returncode is not None
+ await picker.close()
diff --git a/tests/runtime/test_native_folder_dialog.py b/tests/runtime/test_native_folder_dialog.py
new file mode 100644
index 00000000..8301e46d
--- /dev/null
+++ b/tests/runtime/test_native_folder_dialog.py
@@ -0,0 +1,110 @@
+import subprocess
+from types import SimpleNamespace
+
+import pytest
+
+from free_claude_code.runtime import native_folder_dialog as native
+
+
+ ("status", "output", "diagnostic", "expected"),
+ [
+ (0, "/tmp/project café \n\n", "", "/tmp/project café \n"),
+ (1, "", "", None),
+ (1, "", "Gtk-WARNING: optional theme is missing", None),
+ ],
+)
+def test_linux_selection_preserves_paths_and_normal_cancel(
+ monkeypatch, status, output, diagnostic, expected
+):
+ monkeypatch.setattr(native.shutil, "which", lambda _tool: "/usr/bin/zenity")
+ monkeypatch.setenv("ZENITY_CANCEL", "42")
+ calls = []
+
+ def run(command, **kwargs):
+ calls.append((command, kwargs))
+ return subprocess.CompletedProcess(
+ command, status, output.encode("utf-8"), diagnostic.encode("utf-8")
+ )
+
+ monkeypatch.setattr(native.subprocess, "run", run)
+ assert native._linux("/tmp/start") == expected
+ assert "--filename=/tmp/start/" in calls[0][0]
+ assert "ZENITY_CANCEL" not in calls[0][1]["env"]
+
+
+ "diagnostic",
+ [
+ "Gtk-WARNING: cannot open display",
+ "Failed to open display",
+ "Could not connect to display",
+ ],
+)
+def test_linux_display_failure_is_not_user_cancellation(monkeypatch, diagnostic):
+ monkeypatch.setattr(native.shutil, "which", lambda _tool: "/usr/bin/zenity")
+ monkeypatch.setattr(
+ native.subprocess,
+ "run",
+ lambda *args, **kwargs: subprocess.CompletedProcess(
+ args, 1, b"", diagnostic.encode()
+ ),
+ )
+ with pytest.raises(RuntimeError, match=diagnostic):
+ native._linux(None)
+
+
+def test_linux_uses_installed_kdialog_or_reports_missing_tools(monkeypatch):
+ monkeypatch.setattr(
+ native.shutil,
+ "which",
+ lambda tool: "/usr/bin/kdialog" if tool == "kdialog" else None,
+ )
+ calls = []
+
+ def run(command, **_kwargs):
+ calls.append(command)
+ return subprocess.CompletedProcess(command, 0, b"/tmp/project\n", b"")
+
+ monkeypatch.setattr(native.subprocess, "run", run)
+ assert native._linux("/tmp") == "/tmp/project"
+ assert calls[0][-2:] == ["--getexistingdirectory", "/tmp"]
+ monkeypatch.setattr(native.shutil, "which", lambda _tool: None)
+ with pytest.raises(RuntimeError, match="No desktop folder picker"):
+ native._linux(None)
+
+
+def test_macos_passes_the_hint_as_data_and_preserves_path_characters(monkeypatch):
+ hint = '/tmp/quotes " and spaces'
+
+ def run(command, **_kwargs):
+ assert command[-1] == hint
+ assert hint not in command[-2]
+ return subprocess.CompletedProcess(command, 0, b"/tmp/project \n\n", b"")
+
+ monkeypatch.setattr(native.subprocess, "run", run)
+ assert native._macos(hint) == "/tmp/project \n"
+
+
[email protected]("selection", ["", "C:/Projects/café"])
+def test_windows_destroys_hidden_parent_after_selection(monkeypatch, selection):
+ calls = []
+ root = SimpleNamespace(
+ withdraw=lambda: calls.append("hidden"),
+ attributes=lambda *_args: None,
+ destroy=lambda: calls.append("destroyed"),
+ )
+ module = SimpleNamespace(
+ Tk=lambda: root,
+ filedialog=SimpleNamespace(askdirectory=lambda **_kwargs: selection),
+ )
+ monkeypatch.setitem(native.sys.modules, "tkinter", module)
+ assert native._windows(None) == (selection or None)
+ assert calls == ["hidden", "destroyed"]
+
+
+def test_folder_hint_is_optional_and_checked_in_helper(tmp_path):
+ assert native._initial_directory(str(tmp_path)) == str(tmp_path.resolve())
+ assert native._initial_directory(str(tmp_path / "missing")) is None
+ assert native._initial_directory("\0") is None
+ assert native._initial_directory("") is None
diff --git a/uv.lock b/uv.lock
index 011d3dc7..0514aba7 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,7 +598,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "6.0.0"
+version = "6.1.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },