Initial commit: opencode_bridge JupyterLab extension (Slices 1-3.5)

A JupyterLab extension that bridges the cell UI to a local OpenCode Serve
process. The extension is a dual package: a Python server extension
exposed under /opencode-bridge/*, plus a TypeScript frontend that
registers per-cell toolbars.

Backend (Python, tornado)
- Slice 1: config + auth + OpenCode HTTP client (tornado.httpclient,
  no aiohttp). 4 settings in schema/plugin.json (url, user, password,
  request timeout).
- Slice 2: handlers for /hello, /health, /providers, /edit.
- Slice 2.1 (correction): SessionManager with 1 notebook = 1 session
  mapping, async-safe via per-path locks, 404 recovery via invalidate().
  Two new endpoints: GET /sessions, DELETE /session?notebook=<path>.
- 32 pytest tests pass.

Frontend (TypeScript, JupyterLab 4.6)
- src/types.ts: CellContext, OpenCodeRequest/Response, OpenCodeSettings.
- src/context/cell_context.ts: extract CellContext from a CodeCell +
  its parent NotebookPanel, structured error collection.
- src/api/opencode_client.ts: callOpenCodeEdit, callOpenCodeProviders.
- src/components/opencode_cell_footer.ts: OpenCodeCellFooter Widget
  implementing ICellFooter with 3 buttons (optimize / fix / edit),
  resolved via this.parent instanceof CodeCell. NOT cellToolbar
  (does not exist in JL 4.6) and NOT Widget.findParent (removed in
  @lumino/widgets 2.x).
- src/components/opencode_cell_factory.ts: Cell.ContentFactory
  subclass returning the OpenCodeCellFooter.
- src/components/opencode_installer.ts: installOpenCodeEverywhere
  patches every notebook (existing + new) to use the custom factory.
- src/index.ts: registers the factory, loads settings, fetches
  /providers on activation and logs the list to the console.
- 23 jest tests pass (mocked JupyterLab boundary, pnpm path safe).

Settings
- 6 fields: 3 auth (url/user/password) + 1 timeout + 2 model selection
  (provider/model). Provider list is fetched at startup from
  /opencode-bridge/providers and printed to the browser console so
  users can copy values into Settings Editor.

Docs
- design.md: 6 sections covering architecture, UI flow, API contract,
  TS skeletons, session management (v0.2.1 correction), and
  provider/model selection (v0.2.2 addition).
- CLAUDE.md: agent guidance for working in this repo.
- TODO.md: remaining work for Slices 4-7 + v0.4+ backlog.

CI
- Gitea release workflow at .github/workflows/build.yml.
- Bark notification helper (non-fatal on failure).

Generated artefacts ignored: opencode_bridge/labextension/, _version.py,
*.tsbuildinfo, junit.xml, test.ipynb scratch notebook.

opencode_bridge/tests/__init__.py

@@ -0,0 +1 @@
+"""Python unit tests for opencode_bridge."""

opencode_bridge/tests/test_client.py

@@ -0,0 +1,149 @@
+"""Tests for opencode_bridge.opencode_client."""
+
+import json
+from io import BytesIO
+
+import pytest
+import tornado.httpclient
+import tornado.httputil
+
+from opencode_bridge.config import OpenCodeConfig
+from opencode_bridge.opencode_client import OpenCodeClient, OpenCodeError
+
+
+class MockHTTPClient:
+    def __init__(self) -> None:
+        self.calls: list[dict] = []
+        self.responses: list[tuple[int, object]] = []
+
+    async def fetch(self, request, **kwargs) -> tornado.httpclient.HTTPResponse:
+        self.calls.append({"request": request, "kwargs": kwargs})
+        status, body = self.responses.pop(0)
+        buffer = BytesIO(json.dumps(body).encode("utf-8"))
+        return tornado.httpclient.HTTPResponse(
+            request=request,
+            code=status,
+            headers=tornado.httputil.HTTPHeaders(),
+            buffer=buffer,
+        )
+
+
+@pytest.fixture
+def base_config() -> OpenCodeConfig:
+    return OpenCodeConfig(
+        url="http://127.0.0.1:4096",
+        user="opencode",
+        password="",
+        request_timeout_seconds=120,
+    )
+
+
+def _make_client(config: OpenCodeConfig, responses: list[tuple[int, object]]) -> tuple[OpenCodeClient, MockHTTPClient]:
+    mock = MockHTTPClient()
+    mock.responses = responses
+    return OpenCodeClient(config, http_client=mock), mock
+
+
+@pytest.mark.asyncio
+async def test_health_gets_global_health(base_config: OpenCodeConfig) -> None:
+    client, mock = _make_client(base_config, [(200, {"status": "ok"})])
+    result = await client.health()
+    assert result == {"status": "ok"}
+    assert len(mock.calls) == 1
+    call = mock.calls[0]
+    assert call["request"].url == "http://127.0.0.1:4096/global/health"
+    assert call["request"].method == "GET"
+
+
+@pytest.mark.asyncio
+async def test_create_session_posts_title(base_config: OpenCodeConfig) -> None:
+    client, mock = _make_client(base_config, [(200, {"id": "s1"})])
+    result = await client.create_session("foo")
+    assert result == {"id": "s1"}
+    call = mock.calls[0]
+    assert call["request"].url == "http://127.0.0.1:4096/session"
+    assert call["request"].method == "POST"
+    body = json.loads(call["request"].body.decode("utf-8"))
+    assert body == {"title": "foo"}
+
+
+@pytest.mark.asyncio
+async def test_auth_in_fetch_kwargs_when_password_set(base_config: OpenCodeConfig) -> None:
+    config = base_config._replace(password="secret")
+    client, mock = _make_client(config, [(200, {"status": "ok"})])
+    await client.health()
+    call = mock.calls[0]
+    assert call["kwargs"].get("auth_username") == "opencode"
+    assert call["kwargs"].get("auth_password") == "secret"
+
+
+@pytest.mark.asyncio
+async def test_auth_not_in_fetch_kwargs_when_password_empty(base_config: OpenCodeConfig) -> None:
+    client, mock = _make_client(base_config, [(200, {"status": "ok"})])
+    await client.health()
+    call = mock.calls[0]
+    assert "auth_username" not in call["kwargs"]
+    assert "auth_password" not in call["kwargs"]
+
+
+@pytest.mark.asyncio
+async def test_send_message_sync_includes_model_when_provider_and_model_given(
+    base_config: OpenCodeConfig,
+) -> None:
+    client, mock = _make_client(base_config, [(200, {"done": True})])
+    parts = [{"type": "text", "text": "hello"}]
+    result = await client.send_message_sync("s1", parts, provider_id="p1", model_id="m1")
+    assert result == {"done": True}
+    call = mock.calls[0]
+    assert call["request"].url == "http://127.0.0.1:4096/session/s1/message"
+    body = json.loads(call["request"].body.decode("utf-8"))
+    assert body["parts"] == parts
+    assert body["model"] == {"providerID": "p1", "modelID": "m1"}
+
+
+@pytest.mark.asyncio
+async def test_send_message_sync_omits_model_when_provider_or_model_missing(
+    base_config: OpenCodeConfig,
+) -> None:
+    client, mock = _make_client(base_config, [(200, {"done": True})])
+    parts = [{"type": "text", "text": "hello"}]
+    result = await client.send_message_sync("s1", parts)
+    assert result == {"done": True}
+    call = mock.calls[0]
+    body = json.loads(call["request"].body.decode("utf-8"))
+    assert body["parts"] == parts
+    assert "model" not in body
+
+
+@pytest.mark.asyncio
+async def test_send_message_sync_includes_system_when_provided() -> None:
+    """system param is forwarded into the request body when not None."""
+    config = OpenCodeConfig(url="http://x:1", user="u", password="")
+    mock = MockHTTPClient()
+    mock.responses.append((200, {"info": {}, "parts": []}))
+    client = OpenCodeClient(config, http_client=mock)
+
+    await client.send_message_sync("sid", [{"type": "text", "text": "hi"}], system="be brief")
+
+    assert len(mock.calls) == 1
+    body = json.loads(mock.calls[0]["request"].body.decode("utf-8"))
+    assert body["system"] == "be brief"
+    assert body["parts"] == [{"type": "text", "text": "hi"}]
+
+
+@pytest.mark.asyncio
+async def test_delete_session_returns_bool_by_status(base_config: OpenCodeConfig) -> None:
+    client, mock = _make_client(base_config, [(200, True), (404, False)])
+    assert await client.delete_session("s1") is True
+    assert await client.delete_session("s1") is False
+    assert len(mock.calls) == 2
+    assert mock.calls[0]["request"].method == "DELETE"
+    assert mock.calls[0]["request"].url == "http://127.0.0.1:4096/session/s1"
+
+
+@pytest.mark.asyncio
+async def test_non_2xx_response_raises_with_body(base_config: OpenCodeConfig) -> None:
+    client, mock = _make_client(base_config, [(500, {"error": "boom"})])
+    with pytest.raises(OpenCodeError) as exc_info:
+        await client.health()
+    assert "boom" in str(exc_info.value)

opencode_bridge/tests/test_config.py

@@ -0,0 +1,54 @@
+"""Tests for opencode_bridge.config."""
+
+from opencode_bridge.config import OpenCodeConfig, resolve_config
+
+
+def test_all_defaults() -> None:
+    config = resolve_config({})
+    assert config.url == "http://127.0.0.1:4096"
+    assert config.user == "opencode"
+    assert config.password == ""
+    assert config.request_timeout_seconds == 120
+
+
+def test_env_url_overrides_default(monkeypatch) -> None:
+    monkeypatch.setenv("OPENCODE_BRIDGE_URL", "http://x:1")
+    config = resolve_config({})
+    assert config.url == "http://x:1"
+
+
+def test_jupyter_settings_override_env(monkeypatch) -> None:
+    monkeypatch.setenv("OPENCODE_BRIDGE_URL", "http://x:1")
+    settings = {"opencode_bridge": {"opencodeServerUrl": "http://y:2"}}
+    config = resolve_config(settings)
+    assert config.url == "http://y:2"
+
+
+def test_all_env_vars(monkeypatch) -> None:
+    monkeypatch.setenv("OPENCODE_BRIDGE_URL", "http://x:1")
+    monkeypatch.setenv("OPENCODE_BRIDGE_USER", "u")
+    monkeypatch.setenv("OPENCODE_BRIDGE_PASSWORD", "p")
+    config = resolve_config({})
+    assert config.url == "http://x:1"
+    assert config.user == "u"
+    assert config.password == "p"
+
+
+def test_auth_none_when_password_empty() -> None:
+    config = resolve_config({})
+    assert config.auth is None
+
+
+def test_auth_when_password_set() -> None:
+    config = OpenCodeConfig(
+        url="http://127.0.0.1:4096",
+        user="opencode",
+        password="secret",
+    )
+    assert config.auth == ("opencode", "secret")
+
+
+def test_request_timeout_from_settings() -> None:
+    settings = {"opencode_bridge": {"requestTimeoutSeconds": 300}}
+    config = resolve_config(settings)
+    assert config.request_timeout_seconds == 300

opencode_bridge/tests/test_routes.py

@@ -0,0 +1,198 @@
+import json
+
+
+class FakeOpenCodeClient:
+    """Drop-in replacement for OpenCodeClient with recording + canned responses."""
+
+    def __init__(self):
+        self.calls = []
+        self.session_id = "fake-session-123"
+        self.health_response = {"healthy": True, "version": "0.1.0"}
+        self.providers_response = {"providers": [{"id": "anthropic", "models": [{"id": "claude"}]}]}
+        self.message_response = {
+            "info": {"id": "msg-1"},
+            "parts": [{"type": "text", "text": "def foo():\n    return 42\n"}],
+        }
+
+    @property
+    def endpoint(self):
+        return "http://fake-opencode"
+
+    async def health(self):
+        self.calls.append(("health",))
+        return self.health_response
+
+    async def list_providers(self):
+        self.calls.append(("list_providers",))
+        return self.providers_response
+
+    async def create_session(self, title):
+        self.calls.append(("create_session", title))
+        return {"id": self.session_id, "title": title}
+
+    async def send_message_sync(self, session_id, parts, provider_id=None, model_id=None, system=None):
+        self.calls.append(("send_message_sync", session_id, parts, system))
+        return self.message_response
+
+    async def delete_session(self, session_id):
+        self.calls.append(("delete_session", session_id))
+        return True
+
+
+class FakeSessionManager:
+    """Drop-in replacement for SessionManager with recording."""
+
+    def __init__(self, session_id: str = "fake-session-123") -> None:
+        self._session_id = session_id
+        self.calls: list = []
+
+    async def get_or_create(self, notebook_path: str) -> str:
+        self.calls.append(("get_or_create", notebook_path))
+        return self._session_id
+
+    async def release(self, notebook_path: str) -> bool:
+        self.calls.append(("release", notebook_path))
+        return True
+
+    def list_sessions(self) -> list:
+        return [
+            {"notebookPath": path, "sessionId": sid}
+            for path, sid in sorted(self._sessions.items())
+        ]
+
+    def invalidate(self, notebook_path: str) -> bool:
+        self.calls.append(("invalidate", notebook_path))
+        return True
+
+
+async def test_hello(jp_fetch):
+    # When
+    response = await jp_fetch("opencode-bridge", "hello")
+
+    # Then
+    assert response.code == 200
+    payload = json.loads(response.body)
+    assert payload == {
+            "data": (
+                "Hello, world!"
+                " This is the '/opencode-bridge/hello' endpoint."
+                " Try visiting me in your browser!"
+            ),
+        }
+
+
+async def test_health_handler(monkeypatch, jp_fetch):
+    fake = FakeOpenCodeClient()
+    monkeypatch.setattr("opencode_bridge.routes.make_client", lambda h: fake)
+
+    response = await jp_fetch("opencode-bridge", "health")
+    assert response.code == 200
+    payload = json.loads(response.body)
+    assert payload["ok"] is True
+    assert payload["version"] == "0.1.0"
+    assert ("health",) in fake.calls
+
+
+async def test_providers_handler(monkeypatch, jp_fetch):
+    fake = FakeOpenCodeClient()
+    monkeypatch.setattr("opencode_bridge.routes.make_client", lambda h: fake)
+
+    response = await jp_fetch("opencode-bridge", "providers")
+    assert response.code == 200
+    payload = json.loads(response.body)
+    assert "providers" in payload
+    assert payload["providers"][0]["id"] == "anthropic"
+    assert ("list_providers",) in fake.calls
+
+
+async def test_edit_handler(monkeypatch, jp_fetch):
+    fake = FakeOpenCodeClient()
+    monkeypatch.setattr("opencode_bridge.routes.make_client", lambda h: fake)
+
+    fake_sm = FakeSessionManager(session_id="fake-session-123")
+    monkeypatch.setattr(
+        "opencode_bridge.routes.get_session_manager", lambda h: fake_sm
+    )
+
+    body = json.dumps({
+        "mode": "edit",
+        "prompt": "Add type hints",
+        "context": {
+            "notebookPath": "test.ipynb",
+            "cellId": "cell-1",
+            "language": "python",
+            "cellIndex": 0,
+            "totalCells": 1,
+            "source": "def foo(): return 42\n",
+            "previousCode": None,
+            "error": None,
+        },
+    })
+    response = await jp_fetch(
+        "opencode-bridge", "edit",
+        method="POST",
+        body=body,
+    )
+    assert response.code == 200
+    payload = json.loads(response.body)
+    assert payload["ok"] is True
+    assert payload["finalSource"] == "def foo():\n    return 42"
+    assert payload["sessionId"] == "fake-session-123"
+    assert payload["notebookPath"] == "test.ipynb"
+
+    # Session manager was used, not direct create/delete on client
+    call_names = [c[0] for c in fake.calls]
+    assert "create_session" not in call_names
+    assert "delete_session" not in call_names
+    assert "send_message_sync" in call_names
+
+    # send_message_sync received the session ID from the manager
+    send_call = [c for c in fake.calls if c[0] == "send_message_sync"][0]
+    assert send_call[1] == "fake-session-123"
+    # system prompt was passed
+    assert "你是一个代码编辑助手" in send_call[3]
+
+    # SessionManager.get_or_create was called with the notebook path
+    sm_call_names = [c[0] for c in fake_sm.calls]
+    assert sm_call_names == ["get_or_create"]
+    assert fake_sm.calls[0][1] == "test.ipynb"
+
+
+async def test_session_list_handler(monkeypatch, jp_fetch):
+    fake_sm = FakeSessionManager()
+    fake_sm._sessions = {
+        "foo.ipynb": "sid-1",
+        "bar.ipynb": "sid-2",
+    }  # direct injection
+    monkeypatch.setattr(
+        "opencode_bridge.routes.get_session_manager", lambda h: fake_sm
+    )
+
+    response = await jp_fetch("opencode-bridge", "sessions")
+    assert response.code == 200
+    payload = json.loads(response.body)
+    assert "sessions" in payload
+    paths = {s["notebookPath"] for s in payload["sessions"]}
+    assert paths == {"foo.ipynb", "bar.ipynb"}
+
+
+async def test_session_release_handler(monkeypatch, jp_fetch):
+    fake = FakeOpenCodeClient()
+    monkeypatch.setattr("opencode_bridge.routes.make_client", lambda h: fake)
+
+    fake_sm = FakeSessionManager()
+    monkeypatch.setattr(
+        "opencode_bridge.routes.get_session_manager", lambda h: fake_sm
+    )
+
+    response = await jp_fetch(
+        "opencode-bridge", "session",
+        method="DELETE",
+        params={"notebook": "foo.ipynb"},
+    )
+    assert response.code == 200
+    payload = json.loads(response.body)
+    assert payload["ok"] is True
+    assert payload["notebookPath"] == "foo.ipynb"
+    assert payload["deleted"] is True
+    assert ("release", "foo.ipynb") in fake_sm.calls

opencode_bridge/tests/test_session_manager.py

@@ -0,0 +1,135 @@
+"""Unit tests for SessionManager — no Jupyter server fixture."""
+from __future__ import annotations
+
+import pytest
+
+from opencode_bridge.session_manager import SessionManager
+
+
+class FakeClient:
+    """Mimics OpenCodeClient just enough for SessionManager."""
+    def __init__(self, session_id: str = "sid-from-fake") -> None:
+        self._session_id = session_id
+        self.calls: list = []
+
+    async def create_session(self, title: str) -> dict:
+        self.calls.append(("create_session", title))
+        return {"id": self._session_id, "title": title}
+
+    async def delete_session(self, session_id: str) -> bool:
+        self.calls.append(("delete_session", session_id))
+        return True
+
+
+@pytest.mark.asyncio
+async def test_get_or_create_first_call_creates_session():
+    client = FakeClient()
+    sm = SessionManager(lambda: client)
+    sid = await sm.get_or_create("foo.ipynb")
+    assert sid == "sid-from-fake"
+    assert sm.has_session("foo.ipynb")
+    assert client.calls == [("create_session", "jupyter:foo.ipynb")]
+
+
+@pytest.mark.asyncio
+async def test_get_or_create_second_call_returns_same_sid():
+    client = FakeClient()
+    sm = SessionManager(lambda: client)
+    sid1 = await sm.get_or_create("foo.ipynb")
+    sid2 = await sm.get_or_create("foo.ipynb")
+    assert sid1 == sid2
+    # Only ONE create_session call total
+    create_calls = [c for c in client.calls if c[0] == "create_session"]
+    assert len(create_calls) == 1
+
+
+@pytest.mark.asyncio
+async def test_different_notebooks_get_different_sessions():
+    client1 = FakeClient(session_id="sid-1")
+    client2 = FakeClient(session_id="sid-2")
+    factories = [client1, client2]
+    sm = SessionManager(lambda: factories.pop(0) if factories else client1)
+    sid1 = await sm.get_or_create("foo.ipynb")
+    sid2 = await sm.get_or_create("bar.ipynb")
+    assert sid1 == "sid-1"
+    assert sid2 == "sid-2"
+
+
+@pytest.mark.asyncio
+async def test_release_returns_true_and_clears_session():
+    client = FakeClient()
+    sm = SessionManager(lambda: client)
+    await sm.get_or_create("foo.ipynb")
+    deleted = await sm.release("foo.ipynb")
+    assert deleted is True
+    assert not sm.has_session("foo.ipynb")
+    assert ("delete_session", "sid-from-fake") in client.calls
+
+
+@pytest.mark.asyncio
+async def test_release_returns_false_when_no_session():
+    client = FakeClient()
+    sm = SessionManager(lambda: client)
+    deleted = await sm.release("never-existed.ipynb")
+    assert deleted is False
+    assert client.calls == []
+
+
+@pytest.mark.asyncio
+async def test_get_or_create_after_release_creates_new_session():
+    client = FakeClient()
+    sm = SessionManager(lambda: client)
+    sid1 = await sm.get_or_create("foo.ipynb")
+    await sm.release("foo.ipynb")
+    sid2 = await sm.get_or_create("foo.ipynb")
+    # Same fake client returns same ID, but two create_session calls happened
+    assert sid1 == sid2
+    create_calls = [c for c in client.calls if c[0] == "create_session"]
+    assert len(create_calls) == 2
+
+
+@pytest.mark.asyncio
+async def test_invalidate_drops_cached_sid_without_calling_opencode():
+    client = FakeClient()
+    sm = SessionManager(lambda: client)
+    await sm.get_or_create("foo.ipynb")
+    calls_before = len(client.calls)
+    removed = sm.invalidate("foo.ipynb")
+    assert removed is True
+    assert not sm.has_session("foo.ipynb")
+    # No additional calls to client
+    assert len(client.calls) == calls_before
+
+
+def test_list_sessions_empty():
+    sm = SessionManager(lambda: FakeClient())
+    assert sm.list_sessions() == []
+
+
+@pytest.mark.asyncio
+async def test_list_sessions_returns_all_mappings():
+    client = FakeClient()
+    sm = SessionManager(lambda: client)
+    await sm.get_or_create("a.ipynb")
+    # Manually inject a second to test listing
+    sm._sessions["b.ipynb"] = "sid-b"
+    listing = sm.list_sessions()
+    paths = {s["notebookPath"] for s in listing}
+    assert paths == {"a.ipynb", "b.ipynb"}
+
+
+@pytest.mark.asyncio
+async def test_concurrent_get_or_create_does_not_double_create():
+    """Two concurrent calls for the same path must share one session."""
+    import asyncio
+
+    client = FakeClient()
+    sm = SessionManager(lambda: client)
+    sids = await asyncio.gather(
+        sm.get_or_create("foo.ipynb"),
+        sm.get_or_create("foo.ipynb"),
+        sm.get_or_create("foo.ipynb"),
+    )
+    assert sids[0] == sids[1] == sids[2]
+    create_calls = [c for c in client.calls if c[0] == "create_session"]
+    assert len(create_calls) == 1, "concurrent get_or_create must not double-create"