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 durable local Chat Sessions (#1618)

Ali Khokhar3739a022e1a2
diff --git a/README.md b/README.md
index 041f0c0a..46de2efe 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,7 @@
- **Keep coding through provider outages.** After retries are exhausted, FCC automatically tries your next configured model without making you restart the turn—across every client.
- **Up to 90% fewer terminal-output tokens.** Optional [RTK](https://github.com/rtk-ai/rtk) filters common command output, while five FCC optimizations handle quota probes, command-prefix detection, titles, suggestions, and filepaths without calling a provider.
- **Terminal, desktop, IDE, or phone.** Work through native launchers, [VS Code](https://code.visualstudio.com/), [Codex App](https://learn.chatgpt.com/docs/app), [JetBrains](https://www.jetbrains.com/), [Discord](https://discord.com/), or [Telegram](https://telegram.org/).
+- **Private local chat.** Use Chat Sessions in Admin to talk with any configured FCC model, with persisted history, thinking controls, streaming, fallback, and compaction.
- **Voice notes in. Code out.** Talk to your agent using local [Whisper](https://github.com/openai/whisper) or [NVIDIA NIM](https://docs.nvidia.com/nim/speech/latest/asr/deploy-asr-models/whisper.html) transcription.
- **Agent capabilities stay intact.** Stream responses, use tools, preserve native interleaved thinking for maximum performance, send images, and route [Fable](https://www.anthropic.com/claude/fable), [Opus](https://www.anthropic.com/claude/opus), [Sonnet](https://www.anthropic.com/claude/sonnet), and [Haiku](https://www.anthropic.com/claude/haiku) independently with compatible models.
diff --git a/e2e/conftest.py b/e2e/conftest.py
index 4fcf7807..dad59cda 100644
--- a/e2e/conftest.py
+++ b/e2e/conftest.py
@@ -5,6 +5,7 @@ import socket
import threading
import time
from collections.abc import AsyncIterator, Iterator
+from dataclasses import replace
from pathlib import Path
import pytest
@@ -12,16 +13,26 @@ import uvicorn
from free_claude_code.api.app import create_app
from free_claude_code.api.ports import ApiServices
+from free_claude_code.application.chat import (
+ ChatContextEstimate,
+ ChatReasoning,
+ ChatService,
+ ChatSessionDetail,
+ ChatSessionPage,
+)
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config import env_migrations, paths
from free_claude_code.config.env_migrations import recognized_env_keys
from free_claude_code.config.loader import clear_settings_cache, get_settings
from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.streaming import format_sse_event
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
from free_claude_code.providers.base import BaseProvider, ProviderConfig
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.chat_sqlite import SQLiteChatStore
from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
@@ -49,6 +60,8 @@ class _ModelListingProvider(BaseProvider):
)
self._model_infos = model_infos
self._error = error
+ self._slow_used = False
+ self._message_attempts: dict[str, int] = {}
def preflight_messages(
self,
@@ -83,8 +96,99 @@ class _ModelListingProvider(BaseProvider):
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
) -> AsyncIterator[str]:
- if False:
- yield ""
+ del input_tokens, request_id, response_model
+ summary = str(request.system).startswith("Summarize")
+ user_content = str(request.messages[-1].content) if request.messages else ""
+ attempt = self._message_attempts.get(user_content, 0) + 1
+ self._message_attempts[user_content] = attempt
+ slow = not self._slow_used and (
+ "[slow]" in user_content
+ or ("[slow-regenerate]" in user_content and attempt > 1)
+ or (summary and "[slow-compaction]" in user_content)
+ )
+ fragmented = "[fragmented]" in user_content
+ self._slow_used = self._slow_used or slow
+ text = "Earlier details retained." if summary else "E2E answer"
+ frames = [
+ format_sse_event(
+ "message_start",
+ {"type": "message_start", "message": {"content": []}},
+ ),
+ format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "thinking", "thinking": ""},
+ },
+ ),
+ format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "thinking_delta", "thinking": "E2E thought"},
+ },
+ ),
+ format_sse_event(
+ "content_block_stop", {"type": "content_block_stop", "index": 0}
+ ),
+ format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 1,
+ "content_block": {"type": "text", "text": ""},
+ },
+ ),
+ ]
+ if not fragmented:
+ frames.append(
+ format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 1,
+ "delta": {"type": "text_delta", "text": text},
+ },
+ )
+ )
+ for frame in frames:
+ yield frame
+ await asyncio.sleep(0)
+ if fragmented:
+ for _index in range(2_000):
+ yield format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 1,
+ "delta": {"type": "text_delta", "text": "abcd"},
+ },
+ )
+ await asyncio.sleep(0)
+ if summary and "[fail-compaction]" in user_content:
+ yield format_sse_event(
+ "error",
+ {
+ "type": "error",
+ "error": {
+ "type": "api_error",
+ "message": "summary provider failed",
+ },
+ },
+ )
+ return
+ if slow:
+ await asyncio.Event().wait()
+ yield format_sse_event(
+ "content_block_stop", {"type": "content_block_stop", "index": 1}
+ )
+ yield format_sse_event(
+ "message_delta",
+ {"type": "message_delta", "delta": {"stop_reason": "end_turn"}},
+ )
+ yield format_sse_event("message_stop", {"type": "message_stop"})
async def stream_responses(
self,
@@ -99,30 +203,6 @@ class _ModelListingProvider(BaseProvider):
yield ""
-def _close_manager(manager: ProviderRuntimeManager) -> None:
- """Close async runtime ownership outside Playwright's active sync loop."""
-
- errors: list[BaseException] = []
-
- def close() -> None:
- try:
- asyncio.run(manager.close())
- except BaseException as exc:
- errors.append(exc)
-
- thread = threading.Thread(
- target=close,
- name="fcc-admin-playwright-cleanup",
- daemon=True,
- )
- thread.start()
- thread.join(timeout=5.0)
- if thread.is_alive():
- pytest.fail("Admin browser-test runtime did not close")
- if errors:
- raise errors[0]
-
-
@pytest.fixture
def admin_base_url(
request: pytest.FixtureRequest,
@@ -159,7 +239,18 @@ def admin_base_url(
frozenset(
{
ProviderModelInfo("vendor/model-a"),
- ProviderModelInfo("vendor/model-b"),
+ ProviderModelInfo(
+ "vendor/model-b",
+ supports_thinking=True,
+ context_window_tokens=100_000,
+ max_output_tokens=20_000,
+ ),
+ ProviderModelInfo(
+ "vendor/small-context",
+ supports_thinking=True,
+ context_window_tokens=8_192,
+ max_output_tokens=4_096,
+ ),
}
)
),
@@ -171,13 +262,122 @@ def admin_base_url(
get_settings(),
runtime_factory=lambda snapshot: ProviderRuntime(snapshot, dict(providers)),
)
- runtime = ApplicationRuntime(manager, transcriber=None)
- app = create_app(
- ApiServices(
- requests=manager,
- admin=runtime,
- tasks=runtime,
+ chat_store = SQLiteChatStore(
+ config_dir / "chat" / "chat.db",
+ config_dir / "chat" / "chat.lock",
+ )
+ chat = ChatService(manager, chat_store)
+ original_estimate = chat.estimate
+ original_get_detail = chat.get_detail
+ original_get_turn_page = chat.get_turn_page
+ original_list_sessions = chat.list_sessions
+ original_update_session = chat.update_session
+ original_begin_send = chat_store.begin_send
+ delayed_estimate_seen = False
+
+ async def estimate_with_delayed_first_result(
+ session_id: str,
+ *,
+ draft: str,
+ ) -> ChatContextEstimate:
+ nonlocal delayed_estimate_seen
+ delay_result = "[delay-first-estimate]" in draft and not delayed_estimate_seen
+ delayed_estimate_seen = delayed_estimate_seen or delay_result
+ try:
+ return await original_estimate(session_id, draft=draft)
+ finally:
+ if delay_result:
+ await asyncio.sleep(0.75)
+
+ monkeypatch.setattr(chat, "estimate", estimate_with_delayed_first_result)
+
+ async def get_detail_with_test_pagination(
+ session_id: str,
+ ) -> ChatSessionDetail:
+ detail = await original_get_detail(session_id)
+ if "[delay-detail]" in detail.session.title:
+ await asyncio.sleep(0.75)
+ if "[delay-older-page]" in detail.session.title and len(detail.turns) > 1:
+ return replace(
+ detail,
+ turns=detail.turns[-1:],
+ next_before=detail.turns[-1].sequence,
+ )
+ return detail
+
+ async def get_turn_page_with_delayed_result(
+ session_id: str,
+ *,
+ before_sequence: int | None,
+ limit: int,
+ ):
+ result = await original_get_turn_page(
+ session_id,
+ before_sequence=before_sequence,
+ limit=limit,
+ )
+ if before_sequence is not None:
+ session = await chat.get_session(session_id)
+ if "[delay-older-page]" in session.title:
+ await asyncio.sleep(0.75)
+ return result
+
+ async def list_sessions_with_delayed_result(
+ *,
+ query: str,
+ cursor: tuple[int, str] | None,
+ limit: int,
+ ) -> ChatSessionPage:
+ result = await original_list_sessions(query=query, cursor=cursor, limit=limit)
+ if query == "race-old":
+ await asyncio.sleep(0.75)
+ elif cursor is not None:
+ await asyncio.sleep(0.5)
+ return result
+
+ monkeypatch.setattr(chat, "get_detail", get_detail_with_test_pagination)
+ monkeypatch.setattr(chat, "get_turn_page", get_turn_page_with_delayed_result)
+ monkeypatch.setattr(chat, "list_sessions", list_sessions_with_delayed_result)
+
+ async def update_session_with_delayed_result(
+ session_id: str,
+ *,
+ expected_revision: int,
+ title: str | None = None,
+ model: str | None = None,
+ reasoning: ChatReasoning | None = None,
+ ):
+ result = await original_update_session(
+ session_id,
+ expected_revision=expected_revision,
+ title=title,
+ model=model,
+ reasoning=reasoning,
)
+ if title is not None and "[delay-title-save]" in title:
+ await asyncio.sleep(0.75)
+ return result
+
+ monkeypatch.setattr(chat, "update_session", update_session_with_delayed_result)
+
+ async def begin_send_with_delayed_ack(*args, **kwargs):
+ result = await original_begin_send(*args, **kwargs)
+ if kwargs.get("user_text") == "[delay-send-ack] keep one draft":
+ await asyncio.sleep(0.75)
+ return result
+
+ monkeypatch.setattr(chat_store, "begin_send", begin_send_with_delayed_ack)
+ runtime = ApplicationRuntime(manager, transcriber=None, chat_service=chat)
+ app = RuntimeASGIApp(
+ create_app(
+ ApiServices(
+ requests=manager,
+ admin=runtime,
+ tasks=runtime,
+ chat=chat,
+ )
+ ),
+ runtime,
)
async def local_provider_result(
@@ -207,7 +407,7 @@ def admin_base_url(
app,
log_level="error",
access_log=False,
- lifespan="off",
+ lifespan="on",
)
)
thread = threading.Thread(
@@ -231,7 +431,6 @@ def admin_base_url(
server.should_exit = True
thread.join(timeout=5.0)
listener.close()
- _close_manager(manager)
clear_settings_cache()
if thread.is_alive():
pytest.fail("Admin browser-test server did not stop")
diff --git a/e2e/test_admin_assets.py b/e2e/test_admin_assets.py
index cc83ebe5..e72a0379 100644
--- a/e2e/test_admin_assets.py
+++ b/e2e/test_admin_assets.py
@@ -31,7 +31,11 @@ def test_admin_loads_current_release_assets_before_rendering_dynamic_content(
versioned_root = f"/admin/assets/{package_version()}"
assert f"{versioned_root}/admin.css" in requested_paths
+ assert f"{versioned_root}/chat_sessions.css" in requested_paths
+ assert f"{versioned_root}/chat_sessions.js" in requested_paths
assert f"{versioned_root}/admin.js" in requested_paths
assert "/admin/assets/admin.css" not in requested_paths
+ assert "/admin/assets/chat_sessions.css" not in requested_paths
+ assert "/admin/assets/chat_sessions.js" not in requested_paths
assert "/admin/assets/admin.js" not in requested_paths
assert page_errors == []
diff --git a/e2e/test_admin_models.py b/e2e/test_admin_models.py
index 9feb0f43..777cae35 100644
--- a/e2e/test_admin_models.py
+++ b/e2e/test_admin_models.py
@@ -15,7 +15,7 @@ def _refresh_openrouter_models(page: Page) -> None:
page.get_by_role("button", name="Providers", exact=True).click()
card = page.locator('[data-provider="open_router"]')
card.get_by_role("button", name="Refresh models", exact=True).click()
- expect(card.locator(".provider-check-result")).to_have_text("2 models available")
+ expect(card.locator(".provider-check-result")).to_have_text("3 models available")
page.get_by_role("button", name="Model Config", exact=True).click()
diff --git a/e2e/test_admin_providers.py b/e2e/test_admin_providers.py
index 3e08c97d..0baab75c 100644
--- a/e2e/test_admin_providers.py
+++ b/e2e/test_admin_providers.py
@@ -86,7 +86,7 @@ def test_configured_provider_check_keeps_readiness_and_adds_models(
expect(card.get_by_role("button", name="Edit", exact=True)).to_be_visible()
card.get_by_role("button", name="Refresh models", exact=True).click()
- expect(card.locator(".provider-check-result")).to_have_text("2 models available")
+ expect(card.locator(".provider-check-result")).to_have_text("3 models available")
expect(badge).to_have_text("Configured")
expect(meta).to_have_text("OPENROUTER_API_KEY")
diff --git a/e2e/test_chat_sessions.py b/e2e/test_chat_sessions.py
new file mode 100644
index 00000000..42a2a859
--- /dev/null
+++ b/e2e/test_chat_sessions.py
@@ -0,0 +1,596 @@
+import json
+import re
+
+from playwright.sync_api import Page, expect
+
+
+def _new_chat(page: Page, admin_base_url: str) -> None:
+ page.goto(f"{admin_base_url}/admin")
+ page.get_by_role("button", name="Chat Sessions").click()
+ expect(page).to_have_url(f"{admin_base_url}/admin/chat")
+ page.get_by_role("button", name="New chat").click()
+ expect(page).to_have_url(re.compile(r"/admin/chat/[0-9a-f-]{36}$"))
+ expect(page.get_by_role("textbox", name="Message", exact=True)).to_be_visible()
+
+
+def test_chat_navigation_create_and_browser_history(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+
+ expect(page.locator(".action-bar")).to_be_hidden()
+ page.get_by_role("button", name="Chats", exact=False).click()
+ expect(page).to_have_url(f"{admin_base_url}/admin/chat")
+ expect(page.locator(".chat-session-card")).to_have_count(1)
+ page.go_back()
+ expect(page.get_by_role("textbox", name="Message", exact=True)).to_be_visible()
+ page.go_forward()
+ expect(page.get_by_role("button", name="New chat", exact=True)).to_be_visible()
+
+
+def test_model_refresh_updates_chat_bootstrap(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ bootstrap = page.request.get(f"{admin_base_url}/admin/api/chat/bootstrap").json()
+ target = "open_router/vendor/model-b"
+ stale_bootstrap = {
+ **bootstrap,
+ "models": [
+ option for option in bootstrap["models"] if option["model_ref"] != target
+ ],
+ }
+ refreshed = False
+
+ def serve_bootstrap(route) -> None:
+ payload = bootstrap if refreshed else stale_bootstrap
+ route.fulfill(
+ status=200,
+ content_type="application/json",
+ body=json.dumps(payload),
+ )
+
+ page.route("**/admin/api/chat/bootstrap", serve_bootstrap)
+ page.goto(f"{admin_base_url}/admin")
+ expect(page.locator("#messageArea")).to_have_text("")
+ session = page.request.post(
+ f"{admin_base_url}/admin/api/chat/sessions",
+ data={},
+ ).json()
+ updated = page.request.patch(
+ f"{admin_base_url}/admin/api/chat/sessions/{session['id']}",
+ data={"expected_revision": session["revision"], "model": target},
+ )
+ assert updated.ok
+
+ refreshed = True
+ card = page.locator('[data-provider="open_router"]')
+ card.get_by_role("button", name="Refresh models", exact=True).click()
+ expect(card.locator(".provider-check-result")).to_have_text("3 models available")
+ page.get_by_role("button", name="Chat Sessions").click()
+ page.locator(".chat-session-card").click()
+
+ expect(page.get_by_label("Selected model")).to_have_value(target)
+ expect(page.get_by_label("Selected model").locator("option:checked")).to_have_text(
+ "vendor/model-b"
+ )
+ page.get_by_role("textbox", name="Message", exact=True).fill("still available")
+ expect(page.get_by_role("button", name="Send")).to_be_enabled()
+
+
+def test_delayed_older_page_cannot_cross_into_another_chat(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ message = page.get_by_role("textbox", name="Message", exact=True)
+ message.fill("A OLD LEAK")
+ page.get_by_role("button", name="Send").click()
+ expect(page.locator(".assistant-message")).to_have_count(1)
+ message.fill("A latest")
+ page.get_by_role("button", name="Send").click()
+ expect(message).to_be_enabled()
+ title = page.get_by_label("Chat title")
+ title.fill("[delay-older-page] Chat A")
+ with page.expect_response(
+ lambda response: (
+ response.request.method == "PATCH"
+ and "/admin/api/chat/sessions/" in response.url
+ )
+ ):
+ title.press("Enter")
+
+ page.get_by_role("button", name="Chats", exact=False).click()
+ page.get_by_role("button", name="New chat", exact=True).click()
+ message = page.get_by_role("textbox", name="Message", exact=True)
+ message.fill("B only")
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_text("B only", exact=True)).to_be_visible()
+
+ page.get_by_role("button", name="Chats", exact=False).click()
+ page.locator(".chat-session-card", has_text="[delay-older-page] Chat A").click()
+ load_older = page.get_by_role("button", name="Load older messages")
+ expect(load_older).to_be_visible()
+ with page.expect_request(lambda request: "/turns?before=" in request.url):
+ load_older.click()
+
+ page.get_by_role("button", name="Chats", exact=False).click()
+ page.locator(".chat-session-card", has_text="B only").click()
+ expect(page.get_by_text("B only", exact=True)).to_be_visible()
+ page.wait_for_timeout(1_000)
+ expect(page.get_by_text("A OLD LEAK", exact=True)).to_have_count(0)
+
+
+def test_out_of_order_library_search_keeps_latest_results(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ page.goto(f"{admin_base_url}/admin")
+ for title in ("race-old result", "race-new result"):
+ session = page.request.post(
+ f"{admin_base_url}/admin/api/chat/sessions",
+ data={},
+ ).json()
+ renamed = page.request.patch(
+ f"{admin_base_url}/admin/api/chat/sessions/{session['id']}",
+ data={"expected_revision": session["revision"], "title": title},
+ )
+ assert renamed.ok
+ page.get_by_role("button", name="Chat Sessions").click()
+ expect(page.locator(".chat-session-card")).to_have_count(2)
+
+ search = page.get_by_role("searchbox", name="Search chats")
+ with page.expect_request(lambda request: "query=race-old" in request.url):
+ search.fill("race-old")
+ with page.expect_response(lambda response: "query=race-new" in response.url):
+ search.fill("race-new")
+
+ expect(
+ page.locator(".chat-session-card", has_text="race-new result")
+ ).to_be_visible()
+ page.wait_for_timeout(1_000)
+ expect(
+ page.locator(".chat-session-card", has_text="race-new result")
+ ).to_be_visible()
+ expect(
+ page.locator(".chat-session-card", has_text="race-old result")
+ ).to_have_count(0)
+
+
+def test_double_load_more_appends_each_session_once(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ page.goto(f"{admin_base_url}/admin")
+ for _index in range(26):
+ created = page.request.post(
+ f"{admin_base_url}/admin/api/chat/sessions",
+ data={},
+ )
+ assert created.ok
+ page.get_by_role("button", name="Chat Sessions").click()
+ expect(page.locator(".chat-session-card")).to_have_count(25)
+ more = page.get_by_role("button", name="Load more")
+ expect(more).to_be_visible()
+
+ more.evaluate("button => { button.click(); button.click(); }")
+
+ expect(page.locator(".chat-session-card")).to_have_count(26, timeout=3_000)
+ page.wait_for_timeout(750)
+ expect(page.locator(".chat-session-card")).to_have_count(26)
+
+
+def test_chat_streams_thinking_and_persists_answer(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+
+ page.get_by_role("textbox", name="Message", exact=True).fill("hello")
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_text("E2E answer")).to_be_visible()
+ expect(page.locator(".chat-thinking summary", has_text="Thinking")).to_be_visible()
+ expect(page.get_by_role("button", name="Regenerate")).to_be_visible()
+ expect(page.locator("#chatContextMeter")).to_contain_text("Context:")
+
+ page.reload()
+ expect(page.get_by_text("E2E answer")).to_be_visible()
+ expect(page.get_by_text("hello", exact=True)).to_be_visible()
+
+
+def test_fragmented_stream_does_not_rebuild_transcript_per_delta(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ page.evaluate(
+ """
+ () => {
+ const original = Element.prototype.replaceChildren;
+ window.__chatTranscriptRenderCount = 0;
+ Element.prototype.replaceChildren = function (...children) {
+ if (this.id === "chatTranscript") {
+ window.__chatTranscriptRenderCount += 1;
+ }
+ return original.apply(this, children);
+ };
+ }
+ """
+ )
+
+ page.get_by_role("textbox", name="Message", exact=True).fill("[fragmented]")
+ page.get_by_role("button", name="Send").click()
+
+ expect(page.get_by_role("button", name="Regenerate")).to_be_visible(timeout=10_000)
+ expect(page.locator(".assistant-message .chat-markdown").last).to_contain_text(
+ "abcd" * 20
+ )
+ render_count = page.evaluate("window.__chatTranscriptRenderCount")
+ assert isinstance(render_count, int)
+ assert render_count < 100
+
+
+def test_rejected_send_preserves_draft_after_stale_revision(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ session_id = page.url.rsplit("/", 1)[-1]
+ renamed = page.request.patch(
+ f"{admin_base_url}/admin/api/chat/sessions/{session_id}",
+ data={"expected_revision": 1, "title": "Changed elsewhere"},
+ )
+ assert renamed.ok
+
+ message = page.get_by_role("textbox", name="Message", exact=True)
+ message.fill("do not discard this draft")
+ page.get_by_role("button", name="Send").click()
+
+ expect(message).to_have_value("do not discard this draft")
+ expect(page.locator("#chatNotice")).to_contain_text("changed in another tab")
+
+
+def test_committed_send_does_not_restore_draft_when_stream_ack_is_lost(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ session_id = page.url.rsplit("/", 1)[-1]
+ message = page.get_by_role("textbox", name="Message", exact=True)
+ message.fill("[delay-send-ack] keep one draft")
+ page.get_by_role("button", name="Send").click()
+
+ turn_url = f"{admin_base_url}/admin/api/chat/sessions/{session_id}"
+ for _attempt in range(50):
+ detail = page.request.get(turn_url).json()
+ if detail["turns"]:
+ break
+ page.wait_for_timeout(20)
+ else:
+ raise AssertionError("The delayed send did not commit its turn.")
+
+ page.get_by_role("button", name="Stop").click()
+ expect(page.get_by_role("button", name="Retry")).to_be_visible()
+
+ expect(page.get_by_role("textbox", name="Message", exact=True)).to_have_value("")
+ expect(
+ page.get_by_text("[delay-send-ack] keep one draft", exact=True)
+ ).to_be_visible()
+
+
+def test_chat_stop_then_retry_uses_one_operation_owner(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+
+ page.get_by_role("textbox", name="Message", exact=True).fill("[slow] please answer")
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_text("E2E answer")).to_be_visible()
+ page.get_by_role("button", name="Stop").click()
+ expect(page.get_by_role("button", name="Retry")).to_be_visible()
+
+ page.get_by_role("button", name="Retry").click()
+ expect(page.get_by_role("button", name="Regenerate")).to_be_visible()
+ expect(page.get_by_text("E2E answer")).to_be_visible()
+
+
+def test_chat_opened_in_another_tab_recovers_when_operation_stops(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ page.get_by_role("textbox", name="Message", exact=True).fill("[slow] wait")
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_role("button", name="Stop")).to_be_visible()
+
+ other = page.context.new_page()
+ try:
+ other.goto(page.url)
+ expect(other.locator("#chatComposerStatus")).to_contain_text(
+ "running in another tab"
+ )
+ page.get_by_role("button", name="Stop").click()
+ expect(page.get_by_role("button", name="Retry")).to_be_visible()
+ expect(other.get_by_role("button", name="Retry")).to_be_visible(timeout=3_000)
+ finally:
+ other.close()
+
+
+def test_active_chat_deleted_in_another_tab_returns_to_library(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ session_url = page.url
+ page.get_by_role("textbox", name="Message", exact=True).fill("[slow] delete me")
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_role("button", name="Stop")).to_be_visible()
+
+ other = page.context.new_page()
+ try:
+ other.goto(session_url)
+ expect(other.locator("#chatComposerStatus")).to_contain_text(
+ "running in another tab"
+ )
+ other.on("dialog", lambda dialog: dialog.accept())
+ other.get_by_role("button", name="Delete").click()
+ expect(other).to_have_url(f"{admin_base_url}/admin/chat")
+
+ expect(page).to_have_url(f"{admin_base_url}/admin/chat", timeout=3_000)
+ expect(page.get_by_role("button", name="New chat", exact=True)).to_be_visible()
+ expect(page.get_by_role("button", name="Stop")).to_have_count(0)
+ finally:
+ other.close()
+
+
+def test_deleted_chat_cannot_render_from_an_inflight_detail_request(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ session_url = page.url
+ title = page.get_by_label("Chat title")
+ title.fill("[delay-detail] delete while loading")
+ with page.expect_response(
+ lambda response: (
+ response.request.method == "PATCH"
+ and "/admin/api/chat/sessions/" in response.url
+ )
+ ):
+ title.press("Enter")
+
+ other = page.context.new_page()
+ try:
+ with other.expect_request(
+ lambda request: (
+ request.method == "GET" and "/admin/api/chat/sessions/" in request.url
+ )
+ ):
+ other.goto(session_url)
+
+ page.on("dialog", lambda dialog: dialog.accept())
+ page.get_by_role("button", name="Delete").click()
+ expect(page).to_have_url(f"{admin_base_url}/admin/chat")
+
+ expect(other).to_have_url(f"{admin_base_url}/admin/chat", timeout=3_000)
+ expect(other.get_by_role("button", name="New chat", exact=True)).to_be_visible()
+ expect(other.get_by_role("textbox", name="Message", exact=True)).to_have_count(
+ 0
+ )
+ finally:
+ other.close()
+
+
+def test_regeneration_is_visible_and_recovers_in_another_tab(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ page.get_by_role("textbox", name="Message", exact=True).fill(
+ "[slow-regenerate] answer twice"
+ )
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_role("button", name="Regenerate")).to_be_visible()
+
+ page.get_by_role("button", name="Regenerate").click()
+ expect(page.get_by_role("button", name="Stop")).to_be_visible()
+ other = page.context.new_page()
+ try:
+ other.goto(page.url)
+ expect(other.locator("#chatComposerStatus")).to_contain_text(
+ "running in another tab"
+ )
+ expect(other.get_by_label("Selected model")).to_be_disabled()
+
+ page.get_by_role("button", name="Stop").click()
+
+ expect(other.get_by_label("Selected model")).to_be_enabled(timeout=3_000)
+ expect(other.get_by_role("button", name="Regenerate")).to_be_visible()
+ finally:
+ other.close()
+
+
+def test_manual_compaction_is_visible_and_recovers_in_another_tab(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ message = page.get_by_role("textbox", name="Message", exact=True)
+ message.fill("[slow-compaction] first")
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_role("button", name="Regenerate")).to_be_visible()
+ message.fill("second")
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_role("button", name="Regenerate")).to_be_visible()
+
+ page.get_by_role("button", name="Compact now").click()
+ expect(page.get_by_role("button", name="Stop")).to_be_visible()
+ other = page.context.new_page()
+ try:
+ other.goto(page.url)
+ expect(other.locator("#chatComposerStatus")).to_contain_text(
+ "running in another tab"
+ )
+ expect(other.get_by_label("Thinking")).to_be_disabled()
+
+ page.get_by_role("button", name="Stop").click()
+
+ expect(other.get_by_label("Thinking")).to_be_enabled(timeout=3_000)
+ finally:
+ other.close()
+
+
+def test_manual_compaction_failure_remains_visible(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ message = page.get_by_role("textbox", name="Message", exact=True)
+ message.fill("[fail-compaction] first")
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_role("button", name="Regenerate")).to_be_visible()
+ message.fill("second")
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_role("button", name="Regenerate")).to_be_visible()
+
+ page.get_by_role("button", name="Compact now").click()
+
+ notice = page.locator("#chatNotice")
+ expect(notice).to_be_visible()
+ expect(notice).to_have_text("summary provider failed")
+
+
+def test_terminal_refresh_preserves_reader_scroll_position(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ long_message = "[slow]\n" + "\n".join(
+ f"line {index}: keep reading here" for index in range(100)
+ )
+ page.get_by_role("textbox", name="Message", exact=True).fill(long_message)
+ page.get_by_role("button", name="Send").click()
+ expect(page.get_by_role("button", name="Stop")).to_be_visible()
+ scroller = page.locator("#chatTranscript")
+ assert scroller.evaluate("node => node.scrollHeight > node.clientHeight")
+ scroller.evaluate("node => { node.scrollTop = 0; }")
+
+ page.get_by_role("button", name="Stop").click()
+
+ expect(page.get_by_role("button", name="Retry")).to_be_visible()
+ assert scroller.evaluate("node => node.scrollTop") < 10
+ expect(page.get_by_role("button", name="Jump to latest")).to_be_visible()
+
+
+def test_chat_rename_prompt_and_delete(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+
+ title = page.get_by_label("Chat title")
+ title.fill("Release notes")
+ title.press("Enter")
+ expect(page.get_by_label("Chat title")).to_have_value("Release notes")
+
+ page.get_by_role("button", name="System prompt").click()
+ prompt = page.get_by_role("dialog").get_by_label("System prompt")
+ prompt.fill("Be concise.")
+ page.get_by_role("dialog").get_by_role("button", name="Save").click()
+ page.get_by_role("button", name="System prompt").click()
+ expect(page.get_by_role("dialog").get_by_label("System prompt")).to_have_value(
+ "Be concise."
+ )
+ page.get_by_role("dialog").get_by_role("button", name="Reset to default").click()
+
+ page.on("dialog", lambda dialog: dialog.accept())
+ page.get_by_role("button", name="Delete").click()
+ expect(page).to_have_url(f"{admin_base_url}/admin/chat")
+ expect(page.locator(".chat-session-card")).to_have_count(0)
+
+
+def test_delayed_title_save_cannot_restore_chat_after_back_navigation(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ title = page.get_by_label("Chat title")
+ title.fill("[delay-title-save] Release notes")
+ with page.expect_request(
+ lambda request: (
+ request.method == "PATCH" and "/admin/api/chat/sessions/" in request.url
+ )
+ ):
+ title.press("Enter")
+
+ page.get_by_role("button", name="Chats", exact=False).click()
+ expect(page).to_have_url(f"{admin_base_url}/admin/chat")
+ expect(page.get_by_role("button", name="New chat", exact=True)).to_be_visible()
+ page.wait_for_timeout(1_000)
+ expect(page.get_by_role("button", name="New chat", exact=True)).to_be_visible()
+ expect(page).to_have_url(f"{admin_base_url}/admin/chat")
+
+
+def test_reset_system_prompt_refreshes_context_and_unblocks_send(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ page.get_by_label("Selected model").select_option(
+ "open_router/vendor/small-context"
+ )
+ message = page.get_by_role("textbox", name="Message", exact=True)
+ message.fill("send after reset")
+
+ page.get_by_role("button", name="System prompt").click()
+ prompt = page.get_by_role("dialog").get_by_label("System prompt")
+ prompt.fill("oversized prompt " * 5_000)
+ page.get_by_role("dialog").get_by_role("button", name="Save").click()
+ expect(page.get_by_role("button", name="Send")).to_be_disabled()
+ expect(page.locator("#chatComposerStatus")).to_contain_text(
+ "exceeds the model context"
+ )
+ message.fill("[delay-first-estimate] send after reset")
+ page.wait_for_timeout(350)
+
+ page.get_by_role("button", name="System prompt").click()
+ page.get_by_role("dialog").get_by_role("button", name="Reset to default").click()
+
+ expect(page.get_by_role("button", name="Send")).to_be_enabled(timeout=3_000)
+ page.wait_for_timeout(800)
+ expect(page.get_by_role("button", name="Send")).to_be_enabled()
+
+
+def test_estimate_from_before_operation_cannot_overwrite_terminal_context(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ _new_chat(page, admin_base_url)
+ message = page.get_by_role("textbox", name="Message", exact=True)
+ message.fill("first")
+ page.get_by_role("button", name="Send").click()
+ expect(page.locator(".assistant-message")).to_have_count(1)
+
+ message.fill("[delay-first-estimate] second")
+ page.wait_for_timeout(350)
+ page.get_by_role("button", name="Send").click()
+
+ expect(page.locator(".assistant-message")).to_have_count(2)
+ compact = page.get_by_role("button", name="Compact now")
+ expect(compact).to_be_enabled(timeout=3_000)
+ page.wait_for_timeout(800)
+ expect(compact).to_be_enabled()
+
+
+def test_chat_remains_usable_at_narrow_viewport(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ page.set_viewport_size({"width": 390, "height": 844})
+ _new_chat(page, admin_base_url)
+
+ expect(page.get_by_label("Selected model")).to_be_visible()
+ expect(page.get_by_label("Thinking")).to_be_visible()
+ expect(page.get_by_role("textbox", name="Message", exact=True)).to_be_in_viewport()
diff --git a/pyproject.toml b/pyproject.toml
index 2293a4bd..6409c158 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,11 +4,12 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.17.5"
+version = "5.18.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
dependencies = [
+ "anyio>=4.12.1",
"fastapi[standard]>=0.141.1",
"uvicorn>=0.52.1",
"httpx[socks]>=0.28.1",
diff --git a/src/free_claude_code/api/admin_routes.py b/src/free_claude_code/api/admin_routes.py
index 1dc8b476..742dc330 100644
--- a/src/free_claude_code/api/admin_routes.py
+++ b/src/free_claude_code/api/admin_routes.py
@@ -1,9 +1,7 @@
"""Local admin UI routes and APIs."""
-import ipaddress
from collections.abc import Mapping
from pathlib import Path
-from urllib.parse import urlsplit
import httpx
from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
@@ -25,6 +23,7 @@ from free_claude_code.config.provider_catalog import (
from free_claude_code.core.json_types import JsonObject, JsonValue
from free_claude_code.core.version import package_version
+from .admin_security import require_loopback_admin
from .dependencies import get_services
from .ports import ApiServices
@@ -32,7 +31,9 @@ router = APIRouter()
STATIC_DIR = Path(__file__).resolve().parent / "admin_static"
_ADMIN_ASSET_VERSION_PLACEHOLDER = "__FCC_VERSION__"
-_ADMIN_ASSET_FILENAMES = frozenset({"admin.css", "admin.js"})
+_ADMIN_ASSET_FILENAMES = frozenset(
+ {"admin.css", "admin.js", "chat_sessions.css", "chat_sessions.js"}
+)
LOCAL_PROVIDER_PATHS = {
"lmstudio": "/models",
"llamacpp": "/models",
@@ -55,37 +56,6 @@ class ConnectedAccountLoginPayload(BaseModel):
mode: ConnectedAccountLoginMode = ConnectedAccountLoginMode.BROWSER
-def _is_loopback_host(host: str | None) -> bool:
- if host is None:
- return False
- normalized = host.strip().strip("[]").lower()
- if normalized == "localhost":
- return True
- try:
- return ipaddress.ip_address(normalized).is_loopback
- except ValueError:
- return False
-
-
-def _origin_is_local(origin: str | None) -> bool:
- if not origin:
- return True
- parsed = urlsplit(origin)
- return _is_loopback_host(parsed.hostname)
-
-
-def require_loopback_admin(request: Request) -> None:
- """Allow admin access only from the local machine."""
-
- client_host = request.client.host if request.client else None
- if not _is_loopback_host(client_host):
- raise HTTPException(status_code=403, detail="Admin UI is local-only")
-
- origin = request.headers.get("origin")
- if not _origin_is_local(origin):
- raise HTTPException(status_code=403, detail="Admin UI is local-only")
-
-
def _asset_path(filename: str) -> Path:
path = STATIC_DIR / filename
if not path.is_file():
@@ -97,7 +67,7 @@ def _asset_response(filename: str) -> FileResponse:
return FileResponse(_asset_path(filename))
-def _admin_page_response() -> HTMLResponse:
+def admin_page_response() -> HTMLResponse:
template = _asset_path("index.html").read_text(encoding="utf-8")
return HTMLResponse(
template.replace(_ADMIN_ASSET_VERSION_PLACEHOLDER, package_version())
@@ -107,7 +77,7 @@ def _admin_page_response() -> HTMLResponse:
@router.get("/admin", include_in_schema=False)
def admin_page(request: Request):
require_loopback_admin(request)
- return _admin_page_response()
+ return admin_page_response()
@router.get("/admin/assets/{version}/{filename}", include_in_schema=False)
diff --git a/src/free_claude_code/api/admin_security.py b/src/free_claude_code/api/admin_security.py
new file mode 100644
index 00000000..f389104b
--- /dev/null
+++ b/src/free_claude_code/api/admin_security.py
@@ -0,0 +1,67 @@
+"""Shared local-only security boundary for Admin product surfaces."""
+
+import ipaddress
+from urllib.parse import urlsplit
+
+from fastapi import HTTPException, Request
+
+
+def _is_loopback_host(host: str | None) -> bool:
+ if host is None:
+ return False
+ normalized = host.strip().strip("[]").lower()
+ if normalized == "localhost":
+ return True
+ try:
+ return ipaddress.ip_address(normalized).is_loopback
+ except ValueError:
+ return False
+
+
+def _origin_is_local(origin: str | None) -> bool:
+ if not origin:
+ return True
+ try:
+ parsed = urlsplit(origin)
+ _ = parsed.port
+ except ValueError:
+ return False
+ return (
+ parsed.scheme in {"http", "https"}
+ and parsed.username is None
+ and parsed.password is None
+ and not parsed.path
+ and not parsed.query
+ and not parsed.fragment
+ and _is_loopback_host(parsed.hostname)
+ )
+
+
+def _authority_is_local(authority: str | None) -> bool:
+ if not authority:
+ return False
+ try:
+ parsed = urlsplit(f"//{authority}")
+ _ = parsed.port
+ except ValueError:
+ return False
+ return (
+ parsed.username is None
+ and parsed.password is None
+ and not parsed.path
+ and not parsed.query
+ and not parsed.fragment
+ and _is_loopback_host(parsed.hostname)
+ )
+
+
+def require_loopback_admin(request: Request) -> None:
+ """Allow Admin access only from the local machine."""
+
+ client_host = request.client.host if request.client else None
+ if not _is_loopback_host(client_host):
+ raise HTTPException(status_code=403, detail="Admin UI is local-only")
+ if not _authority_is_local(request.headers.get("host")):
+ raise HTTPException(status_code=403, detail="Admin UI is local-only")
+ if not _origin_is_local(request.headers.get("origin")):
+ raise HTTPException(status_code=403, detail="Admin UI is local-only")
diff --git a/src/free_claude_code/api/admin_static/admin.css b/src/free_claude_code/api/admin_static/admin.css
index b6abaac0..630506fc 100644
--- a/src/free_claude_code/api/admin_static/admin.css
+++ b/src/free_claude_code/api/admin_static/admin.css
@@ -740,6 +740,10 @@ textarea:focus-visible,
box-shadow: 0 -8px 30px rgba(0, 0, 0, 0.3);
}
+.action-bar[hidden] {
+ display: none;
+}
+
.action-meta {
display: flex;
flex-direction: column;
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index 3c9a89ea..00008a1f 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -4,7 +4,7 @@ const state = {
modelOptions: [],
modelComboboxes: new Set(),
authPollers: new Map(),
- activeView: "providers",
+ activeView: window.location.pathname.startsWith("/admin/chat") ? "chat" : "providers",
};
const MASKED_SECRET = "********";
@@ -31,6 +31,13 @@ const VIEW_GROUPS = [
sections: ["messaging", "voice"],
containerId: "messagingSections",
},
+ {
+ id: "chat",
+ label: "Chat Sessions",
+ title: "Chat Sessions",
+ sections: [],
+ containerId: "chatRoot",
+ },
];
const byId = (id) => document.getElementById(id);
@@ -77,7 +84,9 @@ async function api(path, options = {}) {
} catch {
// The status remains useful when an upstream proxy returns a non-JSON page.
}
- throw new Error(detail || `${response.status} ${response.statusText}`);
+ const error = new Error(detail || `${response.status} ${response.statusText}`);
+ error.status = response.status;
+ throw error;
}
return response.json();
}
@@ -94,6 +103,9 @@ async function load() {
await refreshConnectedAccounts();
await hydrateModelOptions();
await refreshLocalStatus();
+ if (window.ChatSessions) {
+ await window.ChatSessions.initialize(api);
+ }
updateDirtyState();
showMessage("");
}
@@ -111,7 +123,7 @@ function renderNav() {
button.setAttribute("aria-current", "page");
}
button.addEventListener("click", () => {
- setActiveView(view.id, { scroll: true });
+ navigateToView(view.id);
});
nav.appendChild(button);
});
@@ -123,6 +135,11 @@ function setActiveView(viewId, { scroll = false } = {}) {
VIEW_GROUPS.find((view) => view.id === viewId) || VIEW_GROUPS[0];
state.activeView = activeView.id;
byId("pageTitle").textContent = activeView.title;
+ const chatActive = activeView.id === "chat";
+ document.querySelector(".app-shell").classList.toggle("chat-active", chatActive);
+ document.querySelector(".main").classList.toggle("chat-main", chatActive);
+ document.querySelector(".topbar").hidden = chatActive;
+ document.querySelector(".action-bar").hidden = chatActive;
document.querySelectorAll(".nav-link").forEach((link) => {
const selected = link.dataset.view === activeView.id;
@@ -143,6 +160,20 @@ function setActiveView(viewId, { scroll = false } = {}) {
if (scroll) {
window.scrollTo({ top: 0, behavior: "smooth" });
}
+ if (chatActive && window.ChatSessions) {
+ window.ChatSessions.activate(window.location.pathname);
+ }
+}
+
+function navigateToView(viewId) {
+ if (viewId === "chat") {
+ if (window.location.pathname !== "/admin/chat") {
+ window.history.pushState({}, "", "/admin/chat");
+ }
+ } else if (window.location.pathname.startsWith("/admin/chat")) {
+ window.history.pushState({}, "", "/admin");
+ }
+ setActiveView(viewId, { scroll: true });
}
function renderProviders(providerStatus) {
@@ -1126,6 +1157,7 @@ async function loadModelOptions(refresh = false) {
method: refresh ? "POST" : "GET",
});
setModelOptions(result.models);
+ if (window.ChatSessions) await window.ChatSessions.refresh();
return result;
}
@@ -1182,6 +1214,13 @@ document.addEventListener("pointerdown", (event) => {
});
});
+window.addEventListener("popstate", () => {
+ const viewId = window.location.pathname.startsWith("/admin/chat")
+ ? "chat"
+ : "providers";
+ setActiveView(viewId, { scroll: false });
+});
+
load().catch((error) => {
showMessage(error.message, "error");
});
diff --git a/src/free_claude_code/api/admin_static/chat_sessions.css b/src/free_claude_code/api/admin_static/chat_sessions.css
new file mode 100644
index 00000000..53336a4b
--- /dev/null
+++ b/src/free_claude_code/api/admin_static/chat_sessions.css
@@ -0,0 +1,565 @@
+.main.chat-main {
+ height: 100vh;
+ padding: 0;
+ overflow: hidden;
+}
+
+.chat-main .admin-views,
+.chat-main .admin-view,
+.chat-root,
+.chat-session-shell {
+ height: 100%;
+ min-height: 0;
+}
+
+.chat-root {
+ padding: 36px 42px;
+}
+
+.chat-library-header,
+.chat-header-row,
+.chat-controls,
+.chat-composer-actions,
+.chat-dialog-actions,
+.chat-message-label {
+ display: flex;
+ align-items: center;
+}
+
+.chat-library-header,
+.chat-header-row,
+.chat-composer-actions,
+.chat-message-label {
+ justify-content: space-between;
+}
+
+.chat-library-header {
+ gap: 24px;
+ margin: 0 auto 24px;
+ max-width: 920px;
+}
+
+.chat-library-header h2 {
+ margin: 0;
+ font-size: 30px;
+}
+
+.chat-library-header p,
+.chat-session-card p {
+ color: var(--muted);
+}
+
+.chat-library-header p {
+ margin: 7px 0 0;
+}
+
+.chat-search,
+.chat-session-list,
+.chat-load-more,
+.chat-notice {
+ display: block;
+ width: 100%;
+ max-width: 920px;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+.chat-search {
+ min-height: 44px;
+ margin-bottom: 16px;
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius-md);
+ background: var(--input);
+ padding: 10px 14px;
+}
+
+.chat-session-list {
+ display: grid;
+ gap: 10px;
+}
+
+.chat-session-card {
+ display: grid;
+ width: 100%;
+ gap: 7px;
+ border: 1px solid var(--line);
+ border-radius: var(--radius-md);
+ background: var(--panel);
+ padding: 17px 19px;
+ text-align: left;
+ cursor: pointer;
+}
+
+.chat-session-card:hover {
+ border-color: var(--accent-border);
+ background: var(--card-hover);
+}
+
+.chat-session-card p {
+ overflow: hidden;
+ margin: 0;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+
+.chat-session-card span,
+.chat-muted {
+ color: var(--muted);
+ font-size: 12px;
+}
+
+.chat-load-more {
+ margin-top: 18px;
+}
+
+.chat-session-shell {
+ display: grid;
+ grid-template-rows: auto auto minmax(0, 1fr) auto;
+ position: relative;
+ max-width: 1120px;
+ margin: 0 auto;
+}
+
+.chat-session-header {
+ padding-bottom: 16px;
+ border-bottom: 1px solid var(--line);
+}
+
+.chat-header-row {
+ gap: 12px;
+}
+
+.chat-title {
+ flex: 1;
+ min-width: 0;
+ border: 1px solid transparent;
+ border-radius: var(--radius-sm);
+ background: transparent;
+ padding: 7px 10px;
+ color: var(--text-strong);
+ font-size: 19px;
+ font-weight: 700;
+}
+
+.chat-title:hover,
+.chat-title:focus {
+ border-color: var(--line-strong);
+ background: var(--input);
+}
+
+.chat-back-button {
+ border: 0;
+ background: transparent;
+ color: var(--muted);
+ cursor: pointer;
+}
+
+.chat-back-button:hover {
+ color: var(--text);
+}
+
+.chat-controls {
+ flex-wrap: wrap;
+ gap: 10px;
+ margin-top: 14px;
+}
+
+.chat-control {
+ display: grid;
+ gap: 5px;
+ color: var(--muted);
+ font-size: 11px;
+ font-weight: 700;
+ letter-spacing: 0.04em;
+ text-transform: uppercase;
+}
+
+.chat-control select,
+.chat-model-filter {
+ min-height: 38px;
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius-sm);
+ background: var(--input);
+ padding: 7px 10px;
+ color: var(--text);
+ text-transform: none;
+}
+
+.chat-model-control {
+ grid-template-columns: minmax(110px, 160px) minmax(190px, 260px);
+}
+
+.chat-model-control > span {
+ grid-column: 1 / -1;
+}
+
+.chat-context-meter {
+ align-self: end;
+ min-height: 38px;
+ border: 1px solid var(--line);
+ border-radius: var(--radius-sm);
+ padding: 9px 11px;
+ color: var(--muted);
+ font-size: 12px;
+}
+
+.chat-context-meter.warn {
+ border-color: var(--warn-border);
+ color: var(--warn);
+}
+
+.chat-controls > button {
+ align-self: end;
+}
+
+.chat-notice {
+ margin-top: 12px;
+ margin-bottom: 10px;
+ border: 1px solid var(--line);
+ border-radius: var(--radius-sm);
+ padding: 9px 12px;
+ color: var(--muted);
+ font-size: 13px;
+}
+
+.chat-notice.error {
+ border-color: var(--error-border);
+ background: var(--error-bg);
+ color: var(--error);
+}
+
+.chat-transcript {
+ min-height: 0;
+ overflow-y: auto;
+ overscroll-behavior: contain;
+ padding: 24px max(12px, 7vw) 30px;
+ scroll-behavior: auto;
+}
+
+.chat-message {
+ max-width: 780px;
+ margin: 0 auto 22px;
+ border-radius: var(--radius-lg);
+}
+
+.user-message {
+ margin-left: auto;
+ max-width: min(680px, 88%);
+ background: var(--panel-strong);
+ padding: 14px 17px;
+}
+
+.assistant-message {
+ padding: 2px 4px;
+}
+
+.chat-message-label {
+ gap: 12px;
+ margin-bottom: 8px;
+ color: var(--muted);
+ font-size: 12px;
+ font-weight: 700;
+}
+
+.chat-fallback-label {
+ color: var(--info);
+ font-weight: 500;
+}
+
+.chat-message-plain,
+.chat-markdown {
+ overflow-wrap: anywhere;
+ line-height: 1.65;
+ white-space: pre-wrap;
+}
+
+.chat-markdown {
+ white-space: normal;
+}
+
+.chat-markdown > :first-child {
+ margin-top: 0;
+}
+
+.chat-markdown > :last-child {
+ margin-bottom: 0;
+}
+
+.chat-markdown pre {
+ overflow-x: auto;
+ border: 1px solid var(--line);
+ border-radius: var(--radius-sm);
+ background: var(--input);
+ padding: 13px;
+}
+
+.chat-markdown code {
+ border-radius: 4px;
+ background: var(--input);
+ padding: 0.12em 0.3em;
+}
+
+.chat-markdown pre code {
+ padding: 0;
+}
+
+.chat-markdown a {
+ color: var(--info);
+}
+
+.chat-thinking,
+.chat-compaction {
+ margin: 12px 0;
+ border-left: 2px solid var(--line-strong);
+ padding: 4px 0 4px 14px;
+ color: var(--muted);
+}
+
+.chat-thinking summary,
+.chat-compaction summary {
+ cursor: pointer;
+ font-size: 13px;
+ font-weight: 700;
+}
+
+.chat-compaction {
+ max-width: 780px;
+ margin: 0 auto 24px;
+ border: 1px solid var(--line);
+ border-radius: var(--radius-md);
+ padding: 12px 15px;
+}
+
+.chat-generation-status {
+ margin-top: 12px;
+ border: 1px solid var(--warn-border);
+ border-radius: var(--radius-sm);
+ background: var(--warn-bg);
+ padding: 9px 11px;
+ color: var(--warn);
+ font-size: 13px;
+}
+
+.chat-generation-status.failed {
+ border-color: var(--error-border);
+ background: var(--error-bg);
+ color: var(--error);
+}
+
+.chat-message-actions {
+ display: flex;
+ gap: 8px;
+ margin-top: 12px;
+}
+
+.chat-composer {
+ border-top: 1px solid var(--line);
+ background: var(--bg);
+ padding: 16px max(12px, 7vw) 20px;
+}
+
+.chat-composer textarea {
+ display: block;
+ width: 100%;
+ resize: none;
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius-lg);
+ background: var(--input);
+ padding: 13px 15px;
+ line-height: 1.5;
+}
+
+.chat-composer-actions {
+ gap: 12px;
+ margin-top: 9px;
+}
+
+.chat-composer-status {
+ color: var(--muted);
+ font-size: 12px;
+}
+
+.chat-jump {
+ position: absolute;
+ right: 22px;
+ bottom: 104px;
+ z-index: 2;
+ width: auto;
+}
+
+.chat-older {
+ display: block;
+ margin: 0 auto 24px;
+}
+
+.chat-empty {
+ display: grid;
+ place-items: center;
+ gap: 8px;
+ min-height: 220px;
+ color: var(--muted);
+ text-align: center;
+}
+
+.chat-empty h3,
+.chat-empty p {
+ margin: 0;
+}
+
+.chat-transcript-empty {
+ min-height: 100%;
+}
+
+.danger-button {
+ min-height: 38px;
+ border: 1px solid var(--error-border);
+ border-radius: var(--radius-sm);
+ background: var(--error-bg);
+ padding: 8px 13px;
+ color: var(--error);
+ cursor: pointer;
+ font-weight: 700;
+}
+
+.chat-prompt-dialog {
+ width: min(680px, calc(100vw - 32px));
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius-lg);
+ background: var(--panel);
+ padding: 22px;
+ color: var(--text);
+}
+
+.chat-prompt-dialog::backdrop {
+ background: rgba(0, 0, 0, 0.7);
+}
+
+.chat-prompt-dialog h3 {
+ margin-top: 0;
+}
+
+.chat-prompt-dialog textarea {
+ width: 100%;
+ resize: vertical;
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius-sm);
+ background: var(--input);
+ padding: 12px;
+}
+
+.chat-dialog-actions {
+ justify-content: flex-end;
+ gap: 8px;
+ margin-top: 16px;
+}
+
+@media (max-width: 900px) {
+ .app-shell.chat-active {
+ height: 100dvh;
+ min-height: 0;
+ overflow: hidden;
+ }
+
+ .app-shell.chat-active .sidebar {
+ flex: 0 0 auto;
+ }
+
+ .main.chat-main {
+ flex: 1 1 0;
+ height: auto;
+ min-height: 0;
+ }
+
+ .chat-root {
+ padding: 24px 20px;
+ }
+
+ .chat-controls {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ }
+
+ .chat-model-control,
+ .chat-context-meter {
+ grid-column: 1 / -1;
+ }
+}
+
+@media (max-width: 700px) {
+ .chat-main .admin-views,
+ .chat-main .admin-view,
+ .chat-root,
+ .chat-session-shell {
+ height: 100%;
+ min-height: 0;
+ }
+
+ .chat-root {
+ padding: 16px 12px;
+ }
+
+ .chat-session-shell {
+ grid-template-rows: auto auto minmax(0, 1fr) auto;
+ }
+
+ .chat-library-header {
+ align-items: flex-start;
+ }
+
+ .chat-header-row {
+ flex-wrap: wrap;
+ }
+
+ .chat-title {
+ order: 3;
+ flex-basis: 100%;
+ }
+
+ .chat-controls,
+ .chat-model-control {
+ grid-template-columns: 1fr;
+ }
+
+ .chat-model-control > span,
+ .chat-model-control,
+ .chat-context-meter {
+ grid-column: auto;
+ }
+
+ .chat-transcript,
+ .chat-composer {
+ padding-left: 4px;
+ padding-right: 4px;
+ }
+}
+
+@media (max-width: 600px) {
+ .app-shell.chat-active .sidebar {
+ padding: 10px 12px;
+ gap: 8px;
+ }
+
+ .app-shell.chat-active .brand {
+ flex-direction: row;
+ justify-content: flex-start;
+ text-align: left;
+ }
+
+ .app-shell.chat-active .brand-mark {
+ width: 34px;
+ height: 34px;
+ }
+
+ .app-shell.chat-active .section-nav {
+ grid-template-columns: repeat(4, minmax(0, 1fr));
+ gap: 4px;
+ }
+
+ .app-shell.chat-active .nav-link {
+ justify-content: center;
+ min-height: 34px;
+ padding: 6px 4px;
+ text-align: center;
+ font-size: 11px;
+ }
+}
diff --git a/src/free_claude_code/api/admin_static/chat_sessions.js b/src/free_claude_code/api/admin_static/chat_sessions.js
new file mode 100644
index 00000000..612d7273
--- /dev/null
+++ b/src/free_claude_code/api/admin_static/chat_sessions.js
@@ -0,0 +1,1283 @@
+(() => {
+ const state = {
+ api: null,
+ initialized: false,
+ bootstrap: null,
+ bootstrapRequestVersion: 0,
+ session: null,
+ turns: [],
+ compaction: null,
+ nextBefore: null,
+ context: null,
+ contextError: "",
+ libraryCursor: null,
+ libraryItems: [],
+ libraryQuery: "",
+ libraryRequestVersion: 0,
+ libraryLoadMore: null,
+ olderLoad: null,
+ operation: null,
+ draft: "",
+ draftSessionId: null,
+ draftOperationId: null,
+ routeVersion: 0,
+ estimateTimer: null,
+ estimateVersion: 0,
+ foreignPollTimer: null,
+ serverOperationActive: false,
+ eventChannel: null,
+ };
+
+ const root = () => document.getElementById("chatRoot");
+
+ function node(tag, className = "", text = "") {
+ const element = document.createElement(tag);
+ if (className) element.className = className;
+ if (text) element.textContent = text;
+ return element;
+ }
+
+ function button(label, className, action) {
+ const element = node("button", className, label);
+ element.type = "button";
+ element.addEventListener("click", action);
+ return element;
+ }
+
+ function setNotice(message, kind = "") {
+ const area = document.getElementById("chatNotice");
+ if (!area) return;
+ area.textContent = message;
+ area.className = `chat-notice ${kind}`.trim();
+ area.hidden = !message;
+ }
+
+ async function initialize(api) {
+ if (state.initialized) return;
+ state.api = api;
+ if (typeof window.BroadcastChannel === "function") {
+ state.eventChannel = new BroadcastChannel("fcc-chat-sessions");
+ state.eventChannel.addEventListener("message", handleCrossTabEvent);
+ }
+ state.initialized = true;
+ if (chatIsVisible()) {
+ await activate(window.location.pathname);
+ } else {
+ await refresh();
+ }
+ }
+
+ async function refresh(path = window.location.pathname) {
+ if (!state.initialized) return;
+ const requestVersion = ++state.bootstrapRequestVersion;
+ const routeVersion = state.routeVersion;
+ let bootstrap;
+ try {
+ bootstrap = await state.api("/admin/api/chat/bootstrap");
+ } catch (error) {
+ bootstrap = {
+ available: false,
+ message: error.message,
+ models: [],
+ preferences: null,
+ };
+ }
+ if (requestVersion !== state.bootstrapRequestVersion) return;
+ state.bootstrap = bootstrap;
+ if (!chatIsVisible() || routeVersion !== state.routeVersion) return;
+ await route(path);
+ }
+
+ async function activate(path) {
+ if (!state.initialized) {
+ renderLoading();
+ return;
+ }
+ stopForeignOperationPoll();
+ state.routeVersion += 1;
+ renderLoading();
+ await refresh(path);
+ }
+
+ function chatIsVisible() {
+ const view = root()?.closest(".admin-view");
+ return Boolean(view && !view.hidden);
+ }
+
+ async function route(path) {
+ stopForeignOperationPoll();
+ const version = ++state.routeVersion;
+ const sessionId = routedSessionId(path);
+ if (!sessionId) {
+ await showLibrary(version);
+ return;
+ }
+ await showSession(sessionId, version);
+ }
+
+ function routedSessionId(path) {
+ return path.match(/^\/admin\/chat\/([0-9a-f-]+)$/i)?.[1].toLowerCase() || null;
+ }
+
+ function renderLoading() {
+ const container = root();
+ container.replaceChildren(node("div", "chat-empty", "Loading Chat Sessions…"));
+ }
+
+ function renderUnavailable() {
+ const container = node("section", "chat-empty");
+ container.append(
+ node("h3", "", "Chat Sessions unavailable"),
+ node(
+ "p",
+ "",
+ state.bootstrap?.message || "Chat storage could not be opened.",
+ ),
+ );
+ root().replaceChildren(container);
+ }
+
+ async function showLibrary(version) {
+ cancelLocalStream();
+ state.session = null;
+ state.serverOperationActive = false;
+ if (!state.bootstrap?.available) {
+ renderUnavailable();
+ return;
+ }
+ renderLibraryShell();
+ await loadLibrary(true, version);
+ }
+
+ function renderLibraryShell() {
+ const header = node("header", "chat-library-header");
+ const copy = node("div");
+ copy.append(
+ node("h2", "", "Chat Sessions"),
+ node("p", "", "Talk directly to any configured FCC model."),
+ );
+ const newButton = button("New chat", "primary-button", createSession);
+ newButton.dataset.testid = "chat-new";
+ header.append(copy, newButton);
+
+ const search = node("input", "chat-search");
+ search.type = "search";
+ search.placeholder = "Search chats";
+ search.value = state.libraryQuery;
+ search.setAttribute("aria-label", "Search chats");
+ let timer = null;
+ search.addEventListener("input", () => {
+ window.clearTimeout(timer);
+ timer = window.setTimeout(() => {
+ state.libraryQuery = search.value;
+ loadLibrary(true, state.routeVersion);
+ }, 200);
+ });
+
+ const notice = node("div", "chat-notice");
+ notice.id = "chatNotice";
+ notice.hidden = true;
+ const list = node("div", "chat-session-list");
+ list.id = "chatSessionList";
+ const more = button("Load more", "secondary-button chat-load-more", () =>
+ loadLibrary(false, state.routeVersion),
+ );
+ more.id = "chatLoadMore";
+ more.hidden = true;
+ root().replaceChildren(header, search, notice, list, more);
+ }
+
+ async function loadLibrary(reset, version) {
+ const list = document.getElementById("chatSessionList");
+ if (!list) return;
+ const query = state.libraryQuery;
+ const cursor = reset ? null : state.libraryCursor;
+ if (!reset && (!cursor || state.libraryLoadMore)) return;
+ const requestVersion = reset
+ ? ++state.libraryRequestVersion
+ : state.libraryRequestVersion;
+ const loadMore = reset ? null : {};
+ if (reset) {
+ state.libraryItems = [];
+ state.libraryCursor = null;
+ state.libraryLoadMore = null;
+ list.replaceChildren(node("div", "chat-empty", "Loading chats…"));
+ } else {
+ state.libraryLoadMore = loadMore;
+ const more = document.getElementById("chatLoadMore");
+ if (more) more.disabled = true;
+ }
+ const params = new URLSearchParams({ query, limit: "25" });
+ if (cursor) params.set("cursor", cursor);
+ const isCurrent = () =>
+ version === state.routeVersion &&
+ requestVersion === state.libraryRequestVersion &&
+ !state.session &&
+ query === state.libraryQuery &&
+ (reset || state.libraryCursor === cursor);
+ try {
+ const page = await state.api(`/admin/api/chat/sessions?${params}`);
+ if (!isCurrent()) return;
+ state.libraryItems = reset
+ ? page.sessions
+ : [...state.libraryItems, ...page.sessions];
+ state.libraryCursor = page.next_cursor;
+ renderLibraryItems();
+ } catch (error) {
+ if (isCurrent()) setNotice(error.message, "error");
+ } finally {
+ if (loadMore && state.libraryLoadMore === loadMore) {
+ state.libraryLoadMore = null;
+ const more = document.getElementById("chatLoadMore");
+ if (more) more.disabled = false;
+ }
+ }
+ }
+
+ function renderLibraryItems() {
+ const list = document.getElementById("chatSessionList");
+ if (!list) return;
+ list.replaceChildren();
+ if (!state.libraryItems.length) {
+ list.appendChild(
+ node(
+ "div",
+ "chat-empty",
+ state.libraryQuery ? "No matching chats." : "Start your first chat.",
+ ),
+ );
+ }
+ state.libraryItems.forEach((session) => {
+ const item = button("", "chat-session-card", () => openSession(session.id));
+ const heading = node("strong", "", session.title);
+ const preview = node("p", "", session.preview || "No messages yet");
+ const meta = node("span", "", `${session.model} · ${relativeTime(session.updated_at)}`);
+ item.append(heading, preview, meta);
+ list.appendChild(item);
+ });
+ const more = document.getElementById("chatLoadMore");
+ if (more) {
+ more.hidden = !state.libraryCursor;
+ more.disabled = Boolean(state.libraryLoadMore);
+ }
+ }
+
+ async function createSession() {
+ setNotice("Creating chat…");
+ try {
+ const session = await state.api("/admin/api/chat/sessions", {
+ method: "POST",
+ body: "{}",
+ });
+ openSession(session.id);
+ } catch (error) {
+ setNotice(error.message, "error");
+ }
+ }
+
+ function openSession(id) {
+ window.history.pushState({}, "", `/admin/chat/${id}`);
+ route(window.location.pathname);
+ }
+
+ async function showSession(id, version) {
+ if (!state.bootstrap?.available) {
+ renderUnavailable();
+ return;
+ }
+ renderLoading();
+ try {
+ const detail = await state.api(`/admin/api/chat/sessions/${id}`);
+ if (version !== state.routeVersion) return;
+ applyDetail(detail);
+ renderSession();
+ } catch (error) {
+ if (version !== state.routeVersion) return;
+ const empty = node("section", "chat-empty");
+ empty.append(
+ node("h3", "", "Could not open this chat"),
+ node("p", "", error.message),
+ button("Back to chats", "secondary-button", goLibrary),
+ );
+ root().replaceChildren(empty);
+ }
+ }
+
+ function applyDetail(detail) {
+ invalidateEstimate();
+ if (state.draftSessionId !== detail.session.id) {
+ state.draft = "";
+ state.draftSessionId = detail.session.id;
+ state.draftOperationId = null;
+ } else if (
+ state.draftOperationId &&
+ detail.turns.some((turn) => turn.operation_id === state.draftOperationId)
+ ) {
+ state.draft = "";
+ state.draftOperationId = null;
+ }
+ state.session = detail.session;
+ state.turns = detail.turns;
+ state.nextBefore = detail.next_before;
+ state.compaction = detail.compaction;
+ state.context = detail.context;
+ state.contextError = detail.context_error || "";
+ state.serverOperationActive = Boolean(detail.active_operation);
+ if (state.draft && !state.operation) scheduleEstimate(true);
+ }
+
+ function renderSession({ followLatest = true, scrollTop = 0 } = {}) {
+ const session = state.session;
+ if (!session) return;
+ const shell = node("div", "chat-session-shell");
+ const header = renderSessionHeader(session);
+ const notice = node("div", "chat-notice");
+ notice.id = "chatNotice";
+ notice.hidden = true;
+ const scroller = node("div", "chat-transcript");
+ scroller.id = "chatTranscript";
+ scroller.setAttribute("aria-label", "Conversation");
+ const jump = button("Jump to latest", "secondary-button chat-jump", () =>
+ scrollLatest(true),
+ );
+ jump.id = "chatJumpLatest";
+ jump.hidden = true;
+ scroller.addEventListener("scroll", () => {
+ jump.hidden = nearBottom(scroller);
+ });
+ const composer = renderComposer();
+ shell.append(header, notice, scroller, jump, composer);
+ root().replaceChildren(shell);
+ renderTranscript();
+ refreshComposerState();
+ if (followLatest) {
+ scrollLatest(false);
+ } else {
+ scroller.scrollTop = scrollTop;
+ }
+ jump.hidden = nearBottom(scroller);
+ syncForeignOperationPoll();
+ }
+
+ function renderSessionPreservingScroll() {
+ const scroller = document.getElementById("chatTranscript");
+ renderSession({
+ followLatest: !scroller || nearBottom(scroller),
+ scrollTop: scroller?.scrollTop || 0,
+ });
+ }
+
+ function renderSessionHeader(session) {
+ const header = node("header", "chat-session-header");
+ const top = node("div", "chat-header-row");
+ top.appendChild(button("← Chats", "chat-back-button", goLibrary));
+ const title = node("input", "chat-title");
+ title.value = session.title;
+ title.maxLength = 200;
+ title.setAttribute("aria-label", "Chat title");
+ title.addEventListener("change", () => updateSession({ title: title.value }));
+ title.addEventListener("keydown", (event) => {
+ if (event.key === "Enter") title.blur();
+ });
+ top.appendChild(title);
+ top.appendChild(button("Delete", "danger-button", deleteSession));
+
+ const controls = node("div", "chat-controls");
+ const compact = button("Compact now", "secondary-button", compactSession);
+ compact.id = "chatCompact";
+ controls.append(
+ renderModelControl(session),
+ renderReasoningControl(session),
+ renderContextMeter(),
+ compact,
+ button("System prompt", "secondary-button", editSystemPrompt),
+ );
+ header.append(top, controls);
+ return header;
+ }
+
+ function renderModelControl(session) {
+ const group = node("label", "chat-control chat-model-control");
+ group.appendChild(node("span", "", "Model"));
+ const filter = node("input", "chat-model-filter");
+ filter.type = "search";
+ filter.placeholder = "Filter models";
+ filter.setAttribute("aria-label", "Filter models");
+ const select = node("select");
+ select.id = "chatModel";
+ select.setAttribute("aria-label", "Selected model");
+ fillModelOptions(select, "", session.model);
+ filter.addEventListener("input", () =>
+ fillModelOptions(select, filter.value, state.session.model),
+ );
+ select.addEventListener("change", () => updateSession({ model: select.value }));
+ group.append(filter, select);
+ return group;
+ }
+
+ function fillModelOptions(select, query, selected) {
+ const folded = query.trim().toLowerCase();
+ const matches = (state.bootstrap.models || []).filter(
+ (option) => !folded || option.model_ref.toLowerCase().includes(folded),
+ );
+ const groups = new Map();
+ matches.forEach((option) => {
+ if (!groups.has(option.provider_id)) groups.set(option.provider_id, []);
+ groups.get(option.provider_id).push(option);
+ });
+ select.replaceChildren();
+ if (!(state.bootstrap.models || []).some((item) => item.model_ref === selected)) {
+ const unavailable = node("option", "", `${selected} (Unavailable)`);
+ unavailable.value = selected;
+ select.appendChild(unavailable);
+ }
+ [...groups.keys()].sort().forEach((provider) => {
+ const group = document.createElement("optgroup");
+ group.label = provider;
+ groups.get(provider).forEach((option) => {
+ const item = node("option", "", option.model_id);
+ item.value = option.model_ref;
+ group.appendChild(item);
+ });
+ select.appendChild(group);
+ });
+ select.value = selected;
+ }
+
+ function renderReasoningControl(session) {
+ const group = node("label", "chat-control");
+ group.appendChild(node("span", "", "Thinking"));
+ const select = node("select");
+ select.id = "chatReasoning";
+ [
+ ["off", "Off"],
+ ["low", "Low"],
+ ["medium", "Medium"],
+ ["high", "High"],
+ ["xhigh", "Extra High"],
+ ["max", "Max"],
+ ].forEach(([value, label]) => {
+ const option = node("option", "", label);
+ option.value = value;
+ select.appendChild(option);
+ });
+ select.value = session.reasoning;
+ select.addEventListener("change", () =>
+ updateSession({ reasoning: select.value }),
+ );
+ group.appendChild(select);
+ return group;
+ }
+
+ function renderContextMeter() {
+ const meter = node("div", "chat-context-meter");
+ meter.id = "chatContextMeter";
+ updateContextMeter(meter);
+ return meter;
+ }
+
+ function updateContextMeter(element = document.getElementById("chatContextMeter")) {
+ if (!element) return;
+ const context = state.context;
+ if (!context || context.context_window_tokens === null) {
+ element.textContent = "Context: Not reported";
+ element.className = "chat-context-meter unknown";
+ return;
+ }
+ const percent = Math.round((context.usage_ratio || 0) * 100);
+ element.textContent = `Context: ${percent}% · ${formatCount(context.estimated_input_tokens)} input + ${formatCount(context.completion_tokens)} output`;
+ element.className = `chat-context-meter${percent >= 85 ? " warn" : ""}`;
+ }
+
+ function renderComposer() {
+ const wrapper = node("div", "chat-composer");
+ const textarea = node("textarea");
+ textarea.id = "chatComposer";
+ textarea.rows = 3;
+ textarea.placeholder = "Message this model";
+ textarea.value = state.draft;
+ textarea.setAttribute("aria-label", "Message");
+ textarea.addEventListener("input", () => {
+ state.draft = textarea.value;
+ state.draftOperationId = null;
+ refreshComposerState();
+ scheduleEstimate();
+ });
+ textarea.addEventListener("keydown", (event) => {
+ if (event.key === "Enter" && !event.shiftKey) {
+ event.preventDefault();
+ if (!document.getElementById("chatSend")?.disabled) sendMessage();
+ }
+ });
+ const actions = node("div", "chat-composer-actions");
+ const status = node("span", "chat-composer-status");
+ status.id = "chatComposerStatus";
+ status.setAttribute("aria-live", "polite");
+ const send = button("Send", "primary-button", sendMessage);
+ send.id = "chatSend";
+ const stop = button("Stop", "danger-button", stopOperation);
+ stop.id = "chatStop";
+ stop.hidden = true;
+ actions.append(status, send, stop);
+ wrapper.append(textarea, actions);
+ return wrapper;
+ }
+
+ function renderTranscript() {
+ const scroller = document.getElementById("chatTranscript");
+ if (!scroller) return;
+ scroller.replaceChildren();
+ if (state.nextBefore) {
+ scroller.appendChild(
+ button("Load older messages", "secondary-button chat-older", loadOlder),
+ );
+ }
+ if (!state.turns.length && !state.operation) {
+ scroller.appendChild(
+ node("div", "chat-empty chat-transcript-empty", "Start the conversation."),
+ );
+ return;
+ }
+ let dividerRendered = false;
+ state.turns.forEach((turn, index) => {
+ scroller.appendChild(renderUserMessage(turn));
+ const replacingLatest =
+ index === state.turns.length - 1 && state.operation?.action === "retry";
+ if (!replacingLatest) scroller.appendChild(renderAssistantMessage(turn));
+ if (
+ state.compaction &&
+ turn.sequence === state.compaction.covered_through_sequence
+ ) {
+ scroller.appendChild(renderCompaction());
+ dividerRendered = true;
+ }
+ });
+ if (state.operation?.action === "send" && state.operation.userText) {
+ const pending = node("article", "chat-message user-message");
+ pending.append(
+ node("div", "chat-message-label", "You"),
+ node("div", "chat-message-plain", state.operation.userText),
+ );
+ scroller.appendChild(pending);
+ }
+ if (state.compaction && !dividerRendered) {
+ scroller.insertBefore(renderCompaction(), scroller.firstChild);
+ }
+ if (state.operation?.segments?.length) {
+ scroller.appendChild(renderLiveAssistant(state.operation));
+ }
+ }
+
+ function renderUserMessage(turn) {
+ const message = node("article", "chat-message user-message");
+ message.append(node("div", "chat-message-label", "You"));
+ const body = node("div", "chat-message-plain", turn.user_text);
+ message.appendChild(body);
+ return message;
+ }
+
+ function renderAssistantMessage(turn) {
+ const generation = turn.generation;
+ const message = node("article", "chat-message assistant-message");
+ const label = node("div", "chat-message-label", "Assistant");
+ if (
+ generation.actual_model &&
+ generation.actual_model !== generation.requested_model
+ ) {
+ label.appendChild(
+ node("span", "chat-fallback-label", `Answered by ${generation.actual_model}`),
+ );
+ }
+ message.appendChild(label);
+ generation.segments.forEach((segment) => {
+ if (segment.kind === "thinking") {
+ const details = document.createElement("details");
+ details.className = "chat-thinking";
+ details.appendChild(node("summary", "", "Thinking"));
+ const content = node("div", "chat-markdown");
+ content.innerHTML = segment.html;
+ details.appendChild(content);
+ message.appendChild(details);
+ } else {
+ const content = node("div", "chat-markdown");
+ // The server renders this with raw HTML disabled and safe-link rules.
+ content.innerHTML = segment.html;
+ message.appendChild(content);
+ }
+ });
+ if (!generation.segments.length && generation.status === "running") {
+ message.appendChild(node("p", "chat-muted", "Running in another tab…"));
+ }
+ if (generation.status !== "completed" && generation.status !== "running") {
+ const status = node("div", `chat-generation-status ${generation.status}`);
+ status.textContent =
+ generation.error_message || `${capitalize(generation.status)} answer`;
+ message.appendChild(status);
+ }
+ if (turn === state.turns[state.turns.length - 1]) {
+ const actions = node("div", "chat-message-actions");
+ if (["failed", "stopped", "interrupted"].includes(generation.status)) {
+ actions.appendChild(button("Retry", "secondary-button", retryMessage));
+ }
+ if (generation.status === "completed") {
+ actions.appendChild(
+ button("Regenerate", "secondary-button", regenerateMessage),
+ );
+ }
+ message.appendChild(actions);
+ }
+ return message;
+ }
+
+ function renderLiveAssistant(operation) {
+ const message = node("article", "chat-message assistant-message live-message");
+ message.appendChild(node("div", "chat-message-label", "Assistant"));
+ operation.segments.forEach((segment, ordinal) => {
+ const content = node("div", "chat-message-plain");
+ content.dataset.liveSegment = String(ordinal);
+ content.appendChild(document.createTextNode(segment.text));
+ if (segment.kind === "thinking") {
+ const details = document.createElement("details");
+ details.className = "chat-thinking";
+ details.open = true;
+ details.appendChild(node("summary", "", "Thinking"));
+ details.appendChild(content);
+ message.appendChild(details);
+ } else {
+ message.appendChild(content);
+ }
+ });
+ return message;
+ }
+
+ function renderCompaction() {
+ const details = document.createElement("details");
+ details.className = "chat-compaction";
+ details.appendChild(node("summary", "", "Earlier conversation compacted"));
+ const summary = node("div", "chat-markdown");
+ summary.innerHTML = state.compaction.summary_html;
+ details.appendChild(summary);
+ return details;
+ }
+
+ async function loadOlder() {
+ const scroller = document.getElementById("chatTranscript");
+ if (!scroller || !state.nextBefore || !state.session) return;
+ const sessionId = state.session.id;
+ const revision = state.session.revision;
+ const before = state.nextBefore;
+ const routeVersion = state.routeVersion;
+ if (
+ state.olderLoad?.sessionId === sessionId &&
+ state.olderLoad.before === before
+ )
+ return;
+ const request = { sessionId, before };
+ state.olderLoad = request;
+ const button = scroller.querySelector(".chat-older");
+ if (button) button.disabled = true;
+ const oldHeight = scroller.scrollHeight;
+ const isCurrent = () =>
+ routeVersion === state.routeVersion &&
+ state.session?.id === sessionId &&
+ state.session.revision === revision &&
+ state.nextBefore === before &&
+ document.getElementById("chatTranscript") === scroller;
+ try {
+ const page = await state.api(
+ `/admin/api/chat/sessions/${sessionId}/turns?before=${before}&limit=50`,
+ );
+ if (!isCurrent()) return;
+ state.turns = [...page.turns, ...state.turns];
+ state.nextBefore = page.next_before;
+ state.compaction = page.compaction;
+ renderTranscript();
+ scroller.scrollTop += scroller.scrollHeight - oldHeight;
+ } catch (error) {
+ if (isCurrent()) setNotice(error.message, "error");
+ } finally {
+ if (state.olderLoad === request) {
+ state.olderLoad = null;
+ if (button?.isConnected) button.disabled = false;
+ }
+ }
+ }
+
+ async function updateSession(changes) {
+ if (!state.session) return;
+ if (state.operation && (changes.model || changes.reasoning)) return;
+ const sessionId = state.session.id;
+ const expectedRevision = state.session.revision;
+ const routeVersion = state.routeVersion;
+ try {
+ const session = await state.api(
+ `/admin/api/chat/sessions/${sessionId}`,
+ {
+ method: "PATCH",
+ body: JSON.stringify({
+ expected_revision: expectedRevision,
+ ...changes,
+ }),
+ },
+ );
+ if (
+ routeVersion !== state.routeVersion ||
+ state.session?.id !== sessionId ||
+ state.session.revision !== expectedRevision
+ )
+ return;
+ state.session = session;
+ renderSessionPreservingScroll();
+ scheduleEstimate(true);
+ } catch (error) {
+ if (routeVersion !== state.routeVersion || state.session?.id !== sessionId)
+ return;
+ await reloadSession();
+ setNotice(error.message, "error");
+ }
+ }
+
+ async function deleteSession() {
+ if (!state.session) return;
+ if (!window.confirm(`Permanently delete “${state.session.title}”?`)) return;
+ const sessionId = state.session.id;
+ try {
+ await state.api(`/admin/api/chat/sessions/${sessionId}`, {
+ method: "DELETE",
+ body: JSON.stringify({ expected_revision: state.session.revision }),
+ });
+ state.eventChannel?.postMessage({ type: "session.deleted", sessionId });
+ goLibrary();
+ } catch (error) {
+ setNotice(error.message, "error");
+ }
+ }
+
+ function goLibrary() {
+ cancelLocalStream();
+ window.history.pushState({}, "", "/admin/chat");
+ route(window.location.pathname);
+ }
+
+ function handleCrossTabEvent(event) {
+ const message = event.data;
+ if (
+ !message ||
+ message.type !== "session.deleted" ||
+ typeof message.sessionId !== "string" ||
+ (state.session?.id !== message.sessionId &&
+ routedSessionId(window.location.pathname) !== message.sessionId)
+ )
+ return;
+ cancelLocalStream();
+ window.history.replaceState({}, "", "/admin/chat");
+ route(window.location.pathname);
+ }
+
+ function editSystemPrompt() {
+ const current = state.bootstrap.preferences?.system_prompt || "";
+ const dialog = document.createElement("dialog");
+ dialog.className = "chat-prompt-dialog";
+ const form = document.createElement("form");
+ form.method = "dialog";
+ form.append(
+ node("h3", "", "System prompt"),
+ node(
+ "p",
+ "chat-muted",
+ "Shared by every Chat Session and applied on the next turn.",
+ ),
+ );
+ const textarea = node("textarea");
+ textarea.value = current;
+ textarea.rows = 12;
+ textarea.setAttribute("aria-label", "System prompt");
+ form.appendChild(textarea);
+ const actions = node("div", "chat-dialog-actions");
+ const reset = button("Reset to default", "secondary-button", async () => {
+ try {
+ const preferences = await state.api(
+ "/admin/api/chat/preferences/system-prompt",
+ { method: "DELETE" },
+ );
+ state.bootstrap.preferences = preferences;
+ dialog.close();
+ scheduleEstimate(true);
+ } catch (error) {
+ setNotice(error.message, "error");
+ }
+ });
+ const cancel = button("Cancel", "secondary-button", () => dialog.close());
+ const save = button("Save", "primary-button", async () => {
+ try {
+ const preferences = await state.api(
+ "/admin/api/chat/preferences/system-prompt",
+ { method: "PUT", body: JSON.stringify({ value: textarea.value }) },
+ );
+ state.bootstrap.preferences = preferences;
+ dialog.close();
+ scheduleEstimate(true);
+ } catch (error) {
+ setNotice(error.message, "error");
+ }
+ });
+ actions.append(reset, cancel, save);
+ form.appendChild(actions);
+ dialog.appendChild(form);
+ dialog.addEventListener("close", () => dialog.remove());
+ document.body.appendChild(dialog);
+ dialog.showModal();
+ textarea.focus();
+ }
+
+ function invalidateEstimate() {
+ window.clearTimeout(state.estimateTimer);
+ state.estimateTimer = null;
+ state.estimateVersion += 1;
+ }
+
+ function scheduleEstimate(immediate = false) {
+ invalidateEstimate();
+ const version = state.estimateVersion;
+ state.estimateTimer = window.setTimeout(
+ () => updateEstimate(version),
+ immediate ? 0 : 250,
+ );
+ }
+
+ async function updateEstimate(version) {
+ const session = state.session;
+ if (!session || state.operation || version !== state.estimateVersion) return;
+ const textarea = document.getElementById("chatComposer");
+ const revision = session.revision;
+ const draft = textarea?.value || "";
+ try {
+ const context = await state.api(
+ `/admin/api/chat/sessions/${session.id}/estimate`,
+ {
+ method: "POST",
+ body: JSON.stringify({ draft }),
+ },
+ );
+ if (
+ state.session?.id !== session.id ||
+ state.session.revision !== revision ||
+ state.draft !== draft ||
+ state.operation ||
+ version !== state.estimateVersion
+ )
+ return;
+ state.context = context;
+ state.contextError = "";
+ updateContextMeter();
+ refreshComposerState();
+ } catch (error) {
+ if (
+ state.session?.id !== session.id ||
+ state.session.revision !== revision ||
+ state.draft !== draft ||
+ state.operation ||
+ version !== state.estimateVersion
+ )
+ return;
+ state.context = null;
+ state.contextError = error.message;
+ updateContextMeter();
+ refreshComposerState();
+ setNotice(error.message, "error");
+ }
+ }
+
+ function modelOption(modelRef) {
+ return (state.bootstrap.models || []).find(
+ (option) => option.model_ref === modelRef,
+ );
+ }
+
+ function sendBlockReason() {
+ if (!state.session) return "Chat unavailable";
+ if (state.operation) return "A chat operation is already running";
+ const latest = state.turns[state.turns.length - 1];
+ if (
+ state.serverOperationActive ||
+ latest?.generation?.status === "running"
+ ) {
+ return "This chat is running in another tab";
+ }
+ const option = modelOption(state.session.model);
+ if (!option) return "Choose an available model";
+ if (option.supports_reasoning === false && state.session.reasoning !== "off") {
+ return "This model requires Thinking Off";
+ }
+ if (state.contextError) return state.contextError;
+ if (
+ state.context?.usage_ratio !== null &&
+ state.context?.usage_ratio > 1 &&
+ !state.context?.can_compact
+ ) {
+ return "This message exceeds the model context";
+ }
+ return "";
+ }
+
+ function refreshComposerState() {
+ const textarea = document.getElementById("chatComposer");
+ const send = document.getElementById("chatSend");
+ const stop = document.getElementById("chatStop");
+ const compact = document.getElementById("chatCompact");
+ const status = document.getElementById("chatComposerStatus");
+ if (!textarea || !send || !stop || !status) return;
+ const blocked = sendBlockReason();
+ const latest = state.turns[state.turns.length - 1];
+ const busy = Boolean(
+ state.operation ||
+ state.serverOperationActive ||
+ latest?.generation?.status === "running",
+ );
+ send.disabled = Boolean(blocked) || !textarea.value.trim();
+ send.hidden = Boolean(state.operation);
+ stop.hidden = !state.operation;
+ textarea.disabled = Boolean(state.operation);
+ status.textContent = state.operation ? state.operation.status : blocked;
+ document.querySelectorAll(".chat-controls button, .chat-controls select").forEach(
+ (control) => {
+ control.disabled = busy;
+ },
+ );
+ if (compact) {
+ compact.disabled = busy || !state.context?.can_compact;
+ }
+ }
+
+ async function sendMessage() {
+ const textarea = document.getElementById("chatComposer");
+ const text = textarea?.value || "";
+ if (!text.trim() || !state.session) return;
+ await runOperation("send", { text });
+ }
+
+ async function retryMessage() {
+ await runOperation("retry", {});
+ }
+
+ async function regenerateMessage() {
+ await runOperation("regenerate", {});
+ }
+
+ async function compactSession() {
+ await runOperation("compact", {});
+ }
+
+ async function runOperation(action, extra) {
+ if (!state.session || state.operation) return;
+ invalidateEstimate();
+ let failure = null;
+ const operation = {
+ id: crypto.randomUUID(),
+ sessionId: state.session.id,
+ action,
+ controller: new AbortController(),
+ segments: [],
+ sequence: 0,
+ status: action === "compact" ? "Compacting…" : "Thinking…",
+ userText: extra.text || "",
+ accepted: false,
+ failureMessage: "",
+ renderFrame: null,
+ };
+ if (action === "send") {
+ state.draftOperationId = operation.id;
+ }
+ state.operation = operation;
+ renderSessionPreservingScroll();
+ try {
+ const response = await fetch(
+ `/admin/api/chat/sessions/${operation.sessionId}/${action}`,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ expected_revision: state.session.revision,
+ operation_id: operation.id,
+ ...extra,
+ }),
+ cache: "no-store",
+ signal: operation.controller.signal,
+ },
+ );
+ if (!response.ok) throw await responseError(response);
+ if (!response.body) throw new Error("The browser could not open the chat stream.");
+ await consumeEvents(response.body, operation);
+ if (operation.failureMessage) {
+ failure = new Error(operation.failureMessage);
+ }
+ } catch (error) {
+ if (action === "send" && !operation.accepted) {
+ state.draft = operation.userText;
+ state.draftSessionId = operation.sessionId;
+ state.draftOperationId = operation.id;
+ }
+ if (error.name !== "AbortError") failure = error;
+ } finally {
+ cancelOperationRender(operation);
+ if (state.operation === operation) state.operation = null;
+ if (state.session?.id === operation.sessionId) await reloadSession();
+ if (failure) setNotice(failure.message, "error");
+ }
+ }
+
+ async function consumeEvents(body, operation) {
+ const reader = body.getReader();
+ const decoder = new TextDecoder();
+ const frameParts = [];
+ let boundaryTail = "";
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ const chunk = decoder.decode(value || new Uint8Array(), { stream: !done });
+ const probe = boundaryTail + chunk;
+ const boundary = /\r?\n\r?\n/g;
+ const prefixLength = boundaryTail.length;
+ let chunkStart = 0;
+ for (const match of probe.matchAll(boundary)) {
+ const chunkEnd = match.index + match[0].length - prefixLength;
+ frameParts.push(chunk.slice(chunkStart, chunkEnd));
+ applyStreamFrame(frameParts.join(""), operation);
+ frameParts.length = 0;
+ chunkStart = chunkEnd;
+ }
+ const remainder = chunk.slice(chunkStart);
+ if (remainder) frameParts.push(remainder);
+ boundaryTail = chunkStart
+ ? remainder.slice(-3)
+ : (boundaryTail + chunk).slice(-3);
+ if (done) {
+ const finalFrame = frameParts.join("");
+ if (finalFrame.trim()) applyStreamFrame(finalFrame, operation);
+ return;
+ }
+ }
+ } finally {
+ reader.releaseLock();
+ }
+ }
+
+ function applyStreamFrame(frame, operation) {
+ if (state.operation !== operation) return;
+ let event = "message";
+ let sequence = 0;
+ let payload = null;
+ frame.split(/\r?\n/).forEach((line) => {
+ if (line.startsWith("event:")) event = line.slice(6).trim();
+ if (line.startsWith("id:")) sequence = Number.parseInt(line.slice(3), 10);
+ if (line.startsWith("data:")) payload = JSON.parse(line.slice(5).trim());
+ });
+ if (!payload || payload.operation_id !== operation.id) return;
+ if (!Number.isFinite(sequence) || sequence <= operation.sequence) return;
+ if (
+ state.session?.id === operation.sessionId &&
+ Number.isInteger(payload.revision)
+ ) {
+ state.session.revision = payload.revision;
+ }
+ let liveDelta = false;
+ if (event === "turn.started") {
+ operation.accepted = true;
+ if (operation.action === "send") {
+ state.draft = "";
+ state.draftSessionId = operation.sessionId;
+ state.draftOperationId = null;
+ const textarea = document.getElementById("chatComposer");
+ if (textarea) textarea.value = "";
+ }
+ } else if (event === "segment.started") {
+ operation.segments[payload.ordinal] = {
+ kind: payload.kind,
+ text: "",
+ pending: [],
+ };
+ } else if (event === "segment.delta") {
+ const segment = operation.segments[payload.ordinal];
+ if (segment) {
+ segment.pending.push(payload.delta);
+ liveDelta = true;
+ }
+ } else if (event === "compaction.completed") {
+ operation.status = "Compacted";
+ } else if (event === "compaction.failed") {
+ operation.failureMessage = payload.message || "Compaction failed";
+ operation.status = operation.failureMessage;
+ } else if (event === "compaction.stopped") {
+ operation.status = "Stopped";
+ } else if (event === "turn.failed") {
+ operation.failureMessage = payload.message || "Generation failed";
+ operation.status = operation.failureMessage;
+ } else if (event === "turn.stopped") {
+ operation.status = "Stopped";
+ }
+ operation.sequence = sequence;
+ if (liveDelta) {
+ scheduleLiveRender(operation);
+ return;
+ }
+ renderOperationStructure(operation);
+ }
+
+ function commitPendingDeltas(operation) {
+ const updates = [];
+ operation.segments.forEach((segment, ordinal) => {
+ if (!segment?.pending.length) return;
+ const delta = segment.pending.join("");
+ segment.pending.length = 0;
+ segment.text += delta;
+ updates.push({ ordinal, delta });
+ });
+ return updates;
+ }
+
+ function cancelOperationRender(operation) {
+ if (operation.renderFrame === null) return;
+ window.cancelAnimationFrame(operation.renderFrame);
+ operation.renderFrame = null;
+ }
+
+ function scheduleLiveRender(operation) {
+ if (operation.renderFrame !== null) return;
+ operation.renderFrame = window.requestAnimationFrame(() => {
+ operation.renderFrame = null;
+ if (state.operation !== operation) return;
+ const scroller = document.getElementById("chatTranscript");
+ const shouldFollow = scroller ? nearBottom(scroller) : true;
+ commitPendingDeltas(operation).forEach(({ ordinal, delta }) => {
+ const content = scroller?.querySelector(
+ `[data-live-segment="${ordinal}"]`,
+ );
+ const text = content?.firstChild;
+ if (text?.nodeType === Node.TEXT_NODE) {
+ text.appendData(delta);
+ } else if (content) {
+ content.textContent = operation.segments[ordinal].text;
+ }
+ });
+ if (shouldFollow) scrollLatest(false);
+ });
+ }
+
+ function renderOperationStructure(operation) {
+ cancelOperationRender(operation);
+ commitPendingDeltas(operation);
+ const scroller = document.getElementById("chatTranscript");
+ const shouldFollow = scroller ? nearBottom(scroller) : true;
+ renderTranscript();
+ refreshComposerState();
+ if (shouldFollow) scrollLatest(false);
+ }
+
+ async function stopOperation() {
+ const operation = state.operation;
+ if (!operation) return;
+ operation.status = "Stopping…";
+ refreshComposerState();
+ try {
+ await state.api(`/admin/api/chat/sessions/${operation.sessionId}/stop`, {
+ method: "POST",
+ body: JSON.stringify({ operation_id: operation.id }),
+ });
+ } catch (error) {
+ setNotice(error.message, "error");
+ }
+ }
+
+ function cancelLocalStream() {
+ if (!state.operation) return;
+ cancelOperationRender(state.operation);
+ state.operation.controller.abort();
+ state.operation = null;
+ }
+
+ async function reloadSession() {
+ const id = state.session?.id;
+ if (!id) return;
+ try {
+ const detail = await state.api(`/admin/api/chat/sessions/${id}`);
+ if (state.session?.id !== id) return;
+ applyDetail(detail);
+ renderSessionPreservingScroll();
+ } catch (error) {
+ if (error.status === 404 && state.session?.id === id) {
+ cancelLocalStream();
+ window.history.replaceState({}, "", "/admin/chat");
+ await route(window.location.pathname);
+ return;
+ }
+ setNotice(error.message, "error");
+ }
+ }
+
+ function stopForeignOperationPoll() {
+ window.clearTimeout(state.foreignPollTimer);
+ state.foreignPollTimer = null;
+ }
+
+ function syncForeignOperationPoll() {
+ stopForeignOperationPoll();
+ const latest = state.turns[state.turns.length - 1];
+ const chatView = root()?.closest(".admin-view");
+ if (
+ !state.session ||
+ state.operation ||
+ (!state.serverOperationActive &&
+ latest?.generation?.status !== "running") ||
+ chatView?.hidden
+ ) {
+ return;
+ }
+ const sessionId = state.session.id;
+ state.foreignPollTimer = window.setTimeout(async () => {
+ state.foreignPollTimer = null;
+ if (state.session?.id !== sessionId || state.operation) return;
+ await reloadSession();
+ syncForeignOperationPoll();
+ }, 750);
+ }
+
+ async function responseError(response) {
+ try {
+ const payload = await response.json();
+ return new Error(payload.detail || `${response.status} ${response.statusText}`);
+ } catch {
+ return new Error(`${response.status} ${response.statusText}`);
+ }
+ }
+
+ function nearBottom(scroller) {
+ return scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight < 80;
+ }
+
+ function scrollLatest(smooth) {
+ const scroller = document.getElementById("chatTranscript");
+ if (!scroller) return;
+ scroller.scrollTo({
+ top: scroller.scrollHeight,
+ behavior: smooth ? "smooth" : "auto",
+ });
+ }
+
+ function relativeTime(timestamp) {
+ const elapsed = Math.max(0, Date.now() - timestamp);
+ if (elapsed < 60_000) return "just now";
+ if (elapsed < 3_600_000) return `${Math.floor(elapsed / 60_000)}m ago`;
+ if (elapsed < 86_400_000) return `${Math.floor(elapsed / 3_600_000)}h ago`;
+ return new Date(timestamp).toLocaleDateString();
+ }
+
+ function formatCount(value) {
+ return new Intl.NumberFormat(undefined, { notation: "compact" }).format(value);
+ }
+
+ function capitalize(value) {
+ return value ? value[0].toUpperCase() + value.slice(1) : value;
+ }
+
+ window.ChatSessions = { initialize, activate, refresh };
+})();
diff --git a/src/free_claude_code/api/admin_static/index.html b/src/free_claude_code/api/admin_static/index.html
index 649c2257..e39a2c2a 100644
--- a/src/free_claude_code/api/admin_static/index.html
+++ b/src/free_claude_code/api/admin_static/index.html
@@ -6,6 +6,7 @@
<title>Free Claude Code Admin</title>
<link rel="icon" href="data:," />
<link rel="stylesheet" href="/admin/assets/__FCC_VERSION__/admin.css" />
+ <link rel="stylesheet" href="/admin/assets/__FCC_VERSION__/chat_sessions.css" />
</head>
<body>
<div class="app-shell">
@@ -71,6 +72,10 @@
aria-label="Messaging configuration"
></div>
</section>
+
+ <section id="view-chat" class="admin-view" data-view="chat" hidden>
+ <div id="chatRoot" class="chat-root" aria-live="off"></div>
+ </section>
</div>
</main>
@@ -85,6 +90,7 @@
</div>
</footer>
</div>
+ <script src="/admin/assets/__FCC_VERSION__/chat_sessions.js"></script>
<script src="/admin/assets/__FCC_VERSION__/admin.js"></script>
</body>
</html>
diff --git a/src/free_claude_code/api/app.py b/src/free_claude_code/api/app.py
index 83b83ce9..45c16488 100644
--- a/src/free_claude_code/api/app.py
+++ b/src/free_claude_code/api/app.py
@@ -6,6 +6,13 @@ from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from loguru import logger
+from free_claude_code.application.chat import (
+ ChatConflictError,
+ ChatError,
+ ChatNotFoundError,
+ ChatUnavailableError,
+ ChatValidationError,
+)
from free_claude_code.application.errors import ApplicationError
from free_claude_code.core.anthropic import anthropic_error_payload
from free_claude_code.core.diagnostics import (
@@ -21,6 +28,7 @@ from free_claude_code.core.version import package_version
from .admin_cache import AdminNoStoreMiddleware, attach_admin_no_store
from .admin_routes import router as admin_router
+from .chat_routes import router as chat_router
from .ports import ApiServices
from .request_errors import ordinary_application_error_response
from .request_ids import (
@@ -42,8 +50,30 @@ def create_app(services: ApiServices) -> FastAPI:
app.add_middleware(RequestCorrelationMiddleware)
app.include_router(admin_router)
+ app.include_router(chat_router)
app.include_router(router)
+ @app.exception_handler(ChatError)
+ async def chat_error_handler(request: Request, exc: ChatError):
+ """Serialize Chat application failures for the local Admin client."""
+
+ if isinstance(exc, ChatNotFoundError):
+ status_code = 404
+ elif isinstance(exc, ChatConflictError):
+ status_code = 409
+ elif isinstance(exc, ChatValidationError):
+ status_code = 400
+ elif isinstance(exc, ChatUnavailableError):
+ status_code = 503
+ else:
+ status_code = 500
+ response = JSONResponse(
+ status_code=status_code,
+ content={"detail": str(exc), "code": type(exc).__name__},
+ )
+ attach_admin_no_store(response, path=request.url.path)
+ return response
+
@app.exception_handler(RequestValidationError)
async def validation_error_handler(request: Request, exc: RequestValidationError):
"""Log request shape for 422 debugging without content values."""
diff --git a/src/free_claude_code/api/chat_markdown.py b/src/free_claude_code/api/chat_markdown.py
new file mode 100644
index 00000000..8747187f
--- /dev/null
+++ b/src/free_claude_code/api/chat_markdown.py
@@ -0,0 +1,71 @@
+"""Safe Markdown rendering for locally stored model-authored Chat text."""
+
+from collections.abc import Sequence
+from html import escape
+from urllib.parse import urlsplit
+
+from markdown_it import MarkdownIt
+from markdown_it.common.utils import escapeHtml
+from markdown_it.renderer import RendererHTML
+from markdown_it.token import Token
+from markdown_it.utils import EnvType, OptionsDict
+
+
+def _safe_http_url(value: object) -> str | None:
+ if not isinstance(value, str):
+ return None
+ parsed = urlsplit(value)
+ if parsed.scheme.lower() not in {"http", "https"} or not parsed.netloc:
+ return None
+ return value
+
+
+class _ChatRenderer(RendererHTML):
+ def link_open(
+ self,
+ tokens: Sequence[Token],
+ idx: int,
+ options: OptionsDict,
+ env: EnvType,
+ ) -> str:
+ token = tokens[idx]
+ href = _safe_http_url(token.attrGet("href"))
+ if href is None:
+ token.attrSet("href", "#")
+ token.attrSet("aria-disabled", "true")
+ else:
+ token.attrSet("href", href)
+ token.attrSet("target", "_blank")
+ token.attrSet("rel", "noopener noreferrer")
+ return self.renderToken(tokens, idx, options, env)
+
+ def image(
+ self,
+ tokens: Sequence[Token],
+ idx: int,
+ options: OptionsDict,
+ env: EnvType,
+ ) -> str:
+ del self, options, env
+ token = tokens[idx]
+ label = token.content.strip() or "Image"
+ source = _safe_http_url(token.attrGet("src"))
+ if source is None:
+ return escape(label)
+ return (
+ f'<a href="{escape(source, quote=True)}" target="_blank" '
+ f'rel="noopener noreferrer">{escapeHtml(label)}</a>'
+ )
+
+
+_MARKDOWN = MarkdownIt(
+ "commonmark",
+ {"html": False, "linkify": False},
+ renderer_cls=_ChatRenderer,
+)
+
+
+def render_chat_markdown(value: str) -> str:
+ """Render model text without raw HTML or active remote images."""
+
+ return _MARKDOWN.render(value)
diff --git a/src/free_claude_code/api/chat_routes.py b/src/free_claude_code/api/chat_routes.py
new file mode 100644
index 00000000..899fbdad
--- /dev/null
+++ b/src/free_claude_code/api/chat_routes.py
@@ -0,0 +1,497 @@
+"""Loopback-only HTTP adapter for local Chat Sessions."""
+
+import base64
+import json
+import uuid
+from collections.abc import AsyncIterator
+
+from fastapi import APIRouter, Depends, Query, Request
+from pydantic import BaseModel, Field
+
+from free_claude_code.application.chat import (
+ ChatApplicationPort,
+ ChatCompaction,
+ ChatContextEstimate,
+ ChatModelOption,
+ ChatOperationStream,
+ ChatPreferences,
+ ChatReasoning,
+ ChatSession,
+ ChatSessionSummary,
+ ChatStreamEvent,
+ ChatTurn,
+ ChatUnavailableError,
+ ChatValidationError,
+)
+from free_claude_code.core.json_types import JsonObject
+
+from .admin_routes import admin_page_response
+from .admin_security import require_loopback_admin
+from .chat_markdown import render_chat_markdown
+from .dependencies import get_services
+from .ports import ApiServices
+from .response_streams import ManagedStreamingResponse
+
+router = APIRouter()
+
+
+class ChatSessionUpdatePayload(BaseModel):
+ expected_revision: int = Field(gt=0)
+ title: str | None = None
+ model: str | None = None
+ reasoning: ChatReasoning | None = None
+
+
+class ChatRevisionPayload(BaseModel):
+ expected_revision: int = Field(gt=0)
+
+
+class ChatOperationPayload(ChatRevisionPayload):
+ operation_id: str
+
+
+class ChatSendPayload(ChatOperationPayload):
+ text: str = Field(max_length=1_000_000)
+
+
+class ChatEstimatePayload(BaseModel):
+ draft: str = Field(default="", max_length=1_000_000)
+
+
+class ChatStopPayload(BaseModel):
+ operation_id: str
+
+
+class ChatPromptPayload(BaseModel):
+ value: str = Field(max_length=100_000)
+
+
[email protected]("/admin/chat", include_in_schema=False)
[email protected]("/admin/chat/{session_id}", include_in_schema=False)
+def chat_page(request: Request, session_id: str | None = None):
+ del session_id
+ require_loopback_admin(request)
+ return admin_page_response()
+
+
[email protected]("/admin/api/chat/bootstrap")
+async def chat_bootstrap(
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ chat = _chat(services)
+ available, message = chat.availability()
+ payload: JsonObject = {
+ "available": available,
+ "message": message,
+ "models": [_model_payload(option) for option in chat.models()],
+ "preferences": None,
+ }
+ if available:
+ payload["preferences"] = _preferences_payload(await chat.preferences())
+ return payload
+
+
[email protected]("/admin/api/chat/sessions")
+async def list_chat_sessions(
+ request: Request,
+ query: str = Query(default="", max_length=200),
+ cursor: str | None = None,
+ limit: int = Query(default=25, ge=1, le=25),
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ page = await _chat(services).list_sessions(
+ query=query,
+ cursor=_decode_cursor(cursor),
+ limit=limit,
+ )
+ return {
+ "sessions": [_session_summary_payload(session) for session in page.sessions],
+ "next_cursor": _encode_cursor(page.next_cursor),
+ }
+
+
[email protected]("/admin/api/chat/sessions", status_code=201)
+async def create_chat_session(
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ return _session_payload(await _chat(services).create_session())
+
+
[email protected]("/admin/api/chat/sessions/{session_id}")
+async def get_chat_session(
+ session_id: str,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ detail = await _chat(services).get_detail(session_id)
+ return {
+ "session": _session_payload(detail.session),
+ "turns": [_turn_payload(turn) for turn in detail.turns],
+ "next_before": detail.next_before,
+ "compaction": _compaction_payload(detail.compaction),
+ "context": (
+ _estimate_payload(detail.context) if detail.context is not None else None
+ ),
+ "context_error": detail.context_error,
+ "active_operation": detail.active_operation,
+ }
+
+
[email protected]("/admin/api/chat/sessions/{session_id}")
+async def update_chat_session(
+ session_id: str,
+ payload: ChatSessionUpdatePayload,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ if payload.title is None and payload.model is None and payload.reasoning is None:
+ raise ChatValidationError("Choose a chat field to update.")
+ session = await _chat(services).update_session(
+ session_id,
+ expected_revision=payload.expected_revision,
+ title=payload.title,
+ model=payload.model,
+ reasoning=payload.reasoning,
+ )
+ return _session_payload(session)
+
+
[email protected]("/admin/api/chat/sessions/{session_id}")
+async def delete_chat_session(
+ session_id: str,
+ payload: ChatRevisionPayload,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ await _chat(services).delete_session(
+ session_id,
+ expected_revision=payload.expected_revision,
+ )
+ return {"deleted": True}
+
+
[email protected]("/admin/api/chat/sessions/{session_id}/turns")
+async def get_chat_turns(
+ session_id: str,
+ request: Request,
+ before: int | None = Query(default=None, ge=1),
+ limit: int = Query(default=50, ge=1, le=50),
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ turns, next_before, compaction = await _chat(services).get_turn_page(
+ session_id,
+ before_sequence=before,
+ limit=limit,
+ )
+ return {
+ "turns": [_turn_payload(turn) for turn in turns],
+ "next_before": next_before,
+ "compaction": _compaction_payload(compaction),
+ }
+
+
[email protected]("/admin/api/chat/sessions/{session_id}/estimate")
+async def estimate_chat_context(
+ session_id: str,
+ payload: ChatEstimatePayload,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ estimate = await _chat(services).estimate(session_id, draft=payload.draft)
+ return _estimate_payload(estimate)
+
+
[email protected]("/admin/api/chat/sessions/{session_id}/send")
+async def send_chat_message(
+ session_id: str,
+ payload: ChatSendPayload,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+):
+ require_loopback_admin(request)
+ stream = await _chat(services).send(
+ session_id,
+ expected_revision=payload.expected_revision,
+ operation_id=payload.operation_id,
+ text=payload.text,
+ )
+ return _stream_response(stream)
+
+
[email protected]("/admin/api/chat/sessions/{session_id}/retry")
+async def retry_chat_message(
+ session_id: str,
+ payload: ChatOperationPayload,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+):
+ require_loopback_admin(request)
+ stream = await _chat(services).retry(
+ session_id,
+ expected_revision=payload.expected_revision,
+ operation_id=payload.operation_id,
+ )
+ return _stream_response(stream)
+
+
[email protected]("/admin/api/chat/sessions/{session_id}/regenerate")
+async def regenerate_chat_message(
+ session_id: str,
+ payload: ChatOperationPayload,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+):
+ require_loopback_admin(request)
+ stream = await _chat(services).regenerate(
+ session_id,
+ expected_revision=payload.expected_revision,
+ operation_id=payload.operation_id,
+ )
+ return _stream_response(stream)
+
+
[email protected]("/admin/api/chat/sessions/{session_id}/compact")
+async def compact_chat_session(
+ session_id: str,
+ payload: ChatOperationPayload,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+):
+ require_loopback_admin(request)
+ stream = await _chat(services).compact(
+ session_id,
+ expected_revision=payload.expected_revision,
+ operation_id=payload.operation_id,
+ )
+ return _stream_response(stream)
+
+
[email protected]("/admin/api/chat/sessions/{session_id}/stop")
+async def stop_chat_operation(
+ session_id: str,
+ payload: ChatStopPayload,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ stopped = await _chat(services).stop(
+ session_id,
+ operation_id=payload.operation_id,
+ )
+ return {"stopped": stopped}
+
+
[email protected]("/admin/api/chat/preferences")
+async def get_chat_preferences(
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ return _preferences_payload(await _chat(services).preferences())
+
+
[email protected]("/admin/api/chat/preferences/system-prompt")
+async def save_chat_system_prompt(
+ payload: ChatPromptPayload,
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ return _preferences_payload(await _chat(services).save_system_prompt(payload.value))
+
+
[email protected]("/admin/api/chat/preferences/system-prompt")
+async def reset_chat_system_prompt(
+ request: Request,
+ services: ApiServices = Depends(get_services),
+) -> JsonObject:
+ require_loopback_admin(request)
+ return _preferences_payload(await _chat(services).reset_system_prompt())
+
+
+def _chat(services: ApiServices) -> ChatApplicationPort:
+ if services.chat is None:
+ raise ChatUnavailableError("Chat Sessions is unavailable.")
+ return services.chat
+
+
+def _stream_response(stream: ChatOperationStream) -> ManagedStreamingResponse:
+ response = ManagedStreamingResponse(
+ _stream_events(stream),
+ media_type="text/event-stream",
+ headers={
+ "Cache-Control": "no-store",
+ "Connection": "keep-alive",
+ "X-Accel-Buffering": "no",
+ "X-Content-Type-Options": "nosniff",
+ },
+ )
+ response.bind_release(stream.aclose)
+ return response
+
+
+async def _stream_events(stream: ChatOperationStream) -> AsyncIterator[str]:
+ try:
+ async for event in stream:
+ yield _sse_event(event)
+ finally:
+ await stream.aclose()
+
+
+def _sse_event(event: ChatStreamEvent) -> str:
+ data = json.dumps(event.data, ensure_ascii=False, separators=(",", ":"))
+ return f"id: {event.sequence}\nevent: {event.event}\ndata: {data}\n\n"
+
+
+def _encode_cursor(cursor: tuple[int, str] | None) -> str | None:
+ if cursor is None:
+ return None
+ raw = f"{cursor[0]}:{cursor[1]}".encode()
+ return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+def _decode_cursor(cursor: str | None) -> tuple[int, str] | None:
+ if cursor is None:
+ return None
+ try:
+ padded = cursor + "=" * (-len(cursor) % 4)
+ raw = base64.b64decode(padded, altchars=b"-_", validate=True).decode()
+ updated_at_text, separator, session_id = raw.partition(":")
+ updated_at = int(updated_at_text)
+ except (ValueError, UnicodeError) as exc:
+ raise ChatValidationError("Invalid session cursor.") from exc
+ if not separator or updated_at < 0 or not _is_canonical_uuid(session_id):
+ raise ChatValidationError("Invalid session cursor.")
+ return updated_at, session_id
+
+
+def _is_canonical_uuid(value: str) -> bool:
+ try:
+ parsed = uuid.UUID(value)
+ except ValueError, AttributeError:
+ return False
+ return parsed.version == 4 and str(parsed) == value.lower()
+
+
+def _preferences_payload(preferences: ChatPreferences) -> JsonObject:
+ return {
+ "system_prompt": preferences.system_prompt,
+ "last_model": preferences.last_model,
+ "last_reasoning": preferences.last_reasoning.value,
+ "updated_at": preferences.updated_at,
+ }
+
+
+def _model_payload(option: ChatModelOption) -> JsonObject:
+ return {
+ "model_ref": option.model_ref,
+ "provider_id": option.provider_id,
+ "model_id": option.model_id,
+ "supports_reasoning": option.supports_reasoning,
+ "input_modalities": (
+ sorted(modality.value for modality in option.input_modalities)
+ if option.input_modalities is not None
+ else None
+ ),
+ "context_window_tokens": option.context_window_tokens,
+ "max_output_tokens": option.max_output_tokens,
+ }
+
+
+def _session_payload(session: ChatSession) -> JsonObject:
+ return {
+ "id": session.id,
+ "title": session.title,
+ "model": session.model,
+ "reasoning": session.reasoning.value,
+ "revision": session.revision,
+ "created_at": session.created_at,
+ "updated_at": session.updated_at,
+ }
+
+
+def _session_summary_payload(session: ChatSessionSummary) -> JsonObject:
+ return {
+ **_session_payload(
+ ChatSession(
+ id=session.id,
+ title=session.title,
+ model=session.model,
+ reasoning=session.reasoning,
+ revision=session.revision,
+ created_at=session.created_at,
+ updated_at=session.updated_at,
+ )
+ ),
+ "preview": session.preview[:240],
+ }
+
+
+def _turn_payload(turn: ChatTurn) -> JsonObject:
+ generation = turn.generation
+ return {
+ "id": turn.id,
+ "session_id": turn.session_id,
+ "operation_id": turn.operation_id,
+ "sequence": turn.sequence,
+ "user_text": turn.user_text,
+ "created_at": turn.created_at,
+ "generation": {
+ "id": generation.id,
+ "status": generation.status.value,
+ "requested_model": generation.requested_model,
+ "actual_model": generation.actual_model,
+ "reasoning": generation.reasoning.value,
+ "effective_output_limit": generation.effective_output_limit,
+ "stop_reason": generation.stop_reason,
+ "error_code": generation.error_code,
+ "error_message": generation.error_message,
+ "started_at": generation.started_at,
+ "finished_at": generation.finished_at,
+ "segments": [
+ {
+ "ordinal": segment.ordinal,
+ "kind": segment.kind.value,
+ "text": segment.text,
+ "html": render_chat_markdown(segment.text),
+ }
+ for segment in generation.segments
+ ],
+ },
+ }
+
+
+def _compaction_payload(compaction: ChatCompaction | None) -> JsonObject | None:
+ if compaction is None:
+ return None
+ return {
+ "covered_through_sequence": compaction.covered_through_sequence,
+ "summary": compaction.summary,
+ "summary_html": render_chat_markdown(compaction.summary),
+ "estimated_tokens": compaction.estimated_tokens,
+ "requested_model": compaction.requested_model,
+ "actual_model": compaction.actual_model,
+ "updated_at": compaction.updated_at,
+ }
+
+
+def _estimate_payload(estimate: ChatContextEstimate) -> JsonObject:
+ return {
+ "estimated_input_tokens": estimate.estimated_input_tokens,
+ "completion_tokens": estimate.completion_tokens,
+ "context_window_tokens": estimate.context_window_tokens,
+ "usable_input_tokens": estimate.usable_input_tokens,
+ "usage_ratio": estimate.usage_ratio,
+ "should_auto_compact": estimate.should_auto_compact,
+ "can_compact": estimate.can_compact,
+ }
diff --git a/src/free_claude_code/api/handlers/messages.py b/src/free_claude_code/api/handlers/messages.py
index ba7b4347..4fe732a3 100644
--- a/src/free_claude_code/api/handlers/messages.py
+++ b/src/free_claude_code/api/handlers/messages.py
@@ -170,7 +170,9 @@ class MessagesHandler:
# complete JSON Message; the internal pipeline is always SSE, so
# serving that raw here breaks the client SDK's response parse.
try:
- message, error = await aggregate_anthropic_sse_to_message(result.body)
+ message, error, _complete = await aggregate_anthropic_sse_to_message(
+ result.body
+ )
except GeneratorExit:
raise
except asyncio.CancelledError:
diff --git a/src/free_claude_code/api/ports.py b/src/free_claude_code/api/ports.py
index 197a5b60..ba48164d 100644
--- a/src/free_claude_code/api/ports.py
+++ b/src/free_claude_code/api/ports.py
@@ -4,6 +4,7 @@ from collections.abc import Mapping
from dataclasses import dataclass
from typing import Protocol
+from free_claude_code.application.chat import ChatApplicationPort
from free_claude_code.application.connected_accounts import (
ConnectedAccountLoginMode,
ConnectedAccountStatus,
@@ -55,3 +56,4 @@ class ApiServices:
requests: RequestRuntimePort
admin: AdminRuntimePort
tasks: TaskController
+ chat: ChatApplicationPort | None = None
diff --git a/src/free_claude_code/api/request_lifetime.py b/src/free_claude_code/api/request_lifetime.py
index 1a093b65..a2dc4b42 100644
--- a/src/free_claude_code/api/request_lifetime.py
+++ b/src/free_claude_code/api/request_lifetime.py
@@ -5,6 +5,7 @@ import asyncio
from starlette.types import ASGIApp, Message, Receive, Scope, Send
_INFERENCE_PATHS = frozenset({"/v1/messages", "/v1/responses"})
+_CHAT_STREAM_ACTIONS = frozenset({"send", "retry", "regenerate", "compact"})
class InferenceRequestLifetimeMiddleware:
@@ -77,10 +78,23 @@ class InferenceRequestLifetimeMiddleware:
def _owns_inference_lifetime(scope: Scope) -> bool:
+ path = scope.get("path")
return (
scope["type"] == "http"
and scope.get("method") == "POST"
- and scope.get("path") in _INFERENCE_PATHS
+ and (path in _INFERENCE_PATHS or _is_chat_stream_path(path))
+ )
+
+
+def _is_chat_stream_path(path: object) -> bool:
+ if not isinstance(path, str):
+ return False
+ parts = path.split("/")
+ return (
+ len(parts) == 7
+ and parts[1:5] == ["admin", "api", "chat", "sessions"]
+ and bool(parts[5])
+ and parts[6] in _CHAT_STREAM_ACTIONS
)
diff --git a/src/free_claude_code/api/web_tools/automatic_search.py b/src/free_claude_code/api/web_tools/automatic_search.py
index 87903043..170bc552 100644
--- a/src/free_claude_code/api/web_tools/automatic_search.py
+++ b/src/free_claude_code/api/web_tools/automatic_search.py
@@ -56,7 +56,7 @@ async def stream_automatic_web_search_response(
preserved_error=sys.exception(),
)
- message, stream_error = await aggregate_anthropic_sse_to_message(
+ message, stream_error, _complete = await aggregate_anthropic_sse_to_message(
_iterate_chunks(chunks)
)
if stream_error is not None:
diff --git a/src/free_claude_code/application/chat/__init__.py b/src/free_claude_code/application/chat/__init__.py
new file mode 100644
index 00000000..2f294206
--- /dev/null
+++ b/src/free_claude_code/application/chat/__init__.py
@@ -0,0 +1,57 @@
+"""FCC-owned local Chat Sessions capability."""
+
+from .models import (
+ DEFAULT_CHAT_SYSTEM_PROMPT,
+ ChatCompaction,
+ ChatConflictError,
+ ChatContextEstimate,
+ ChatError,
+ ChatGeneration,
+ ChatModelOption,
+ ChatNotFoundError,
+ ChatPreferences,
+ ChatReasoning,
+ ChatSegment,
+ ChatSession,
+ ChatSessionDetail,
+ ChatSessionPage,
+ ChatSessionSummary,
+ ChatStreamEvent,
+ ChatTranscript,
+ ChatTurn,
+ ChatUnavailableError,
+ ChatValidationError,
+ GenerationStatus,
+ SegmentKind,
+)
+from .ports import ChatApplicationPort, ChatOperationStream, ChatStorePort
+from .service import ChatService
+
+__all__ = [
+ "DEFAULT_CHAT_SYSTEM_PROMPT",
+ "ChatApplicationPort",
+ "ChatCompaction",
+ "ChatConflictError",
+ "ChatContextEstimate",
+ "ChatError",
+ "ChatGeneration",
+ "ChatModelOption",
+ "ChatNotFoundError",
+ "ChatOperationStream",
+ "ChatPreferences",
+ "ChatReasoning",
+ "ChatSegment",
+ "ChatService",
+ "ChatSession",
+ "ChatSessionDetail",
+ "ChatSessionPage",
+ "ChatSessionSummary",
+ "ChatStorePort",
+ "ChatStreamEvent",
+ "ChatTranscript",
+ "ChatTurn",
+ "ChatUnavailableError",
+ "ChatValidationError",
+ "GenerationStatus",
+ "SegmentKind",
+]
diff --git a/src/free_claude_code/application/chat/context.py b/src/free_claude_code/application/chat/context.py
new file mode 100644
index 00000000..d86be181
--- /dev/null
+++ b/src/free_claude_code/application/chat/context.py
@@ -0,0 +1,382 @@
+"""Portable request construction and context accounting for Chat Sessions."""
+
+from dataclasses import dataclass
+
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.application.ports import RequestRuntimePort
+from free_claude_code.application.routing import ModelRouter, RoutedMessagesRequest
+from free_claude_code.config.model_refs import (
+ configured_chat_model_refs,
+ split_provider_model_ref,
+)
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic import (
+ ContentBlockText,
+ ContentBlockThinking,
+ Message,
+ MessagesRequest,
+ get_token_count,
+)
+from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
+
+from .models import (
+ ChatContextEstimate,
+ ChatModelOption,
+ ChatReasoning,
+ ChatTranscript,
+ ChatTurn,
+ ChatValidationError,
+ SegmentKind,
+)
+
+_VISIBLE_ANSWER_TOKENS = 16_384
+_MINIMUM_VISIBLE_ANSWER_TOKENS = 1_024
+_MINIMUM_INPUT_TOKENS = 1_024
+_AUTO_COMPACT_RATIO = 0.85
+_COMPACT_TARGET_RATIO = 0.60
+_SUMMARY_SYSTEM_PROMPT = """Summarize the earlier conversation for another assistant.
+Preserve user facts and preferences, decisions, requirements, unresolved work,
+important explanations, and source titles or URLs. Preserve the meaning of any
+described documents or images. Do not include hidden reasoning, chain-of-thought,
+provider errors, or conversational filler. Be concise, factual, and structured.
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedChatRequest:
+ routed: RoutedMessagesRequest
+ estimate: ChatContextEstimate
+ model: ChatModelOption
+
+
+class ChatContextBuilder:
+ """Build exactly one provider-portable request from durable Chat state."""
+
+ def __init__(
+ self,
+ runtime: RequestRuntimePort,
+ *,
+ settings: Settings | None = None,
+ model_infos: tuple[ProviderModelInfo, ...] | None = None,
+ ) -> None:
+ self._runtime = runtime
+ self._settings = settings
+ self._model_infos = model_infos
+
+ def _current_settings(self) -> Settings:
+ return self._settings or self._runtime.current_settings()
+
+ def models(self) -> tuple[ChatModelOption, ...]:
+ """Return configured and discovered direct models with rich metadata."""
+
+ settings = self._current_settings()
+ snapshot = self._model_infos
+ discovered = (
+ self._runtime.cached_prefixed_model_infos()
+ if snapshot is None
+ else snapshot
+ )
+ snapshot_by_ref = (
+ {info.model_id: info for info in snapshot} if snapshot is not None else None
+ )
+ options: dict[str, ChatModelOption] = {}
+ for ref in configured_chat_model_refs(settings):
+ info = (
+ self._runtime.cached_model_info(ref.provider_id, ref.model_id)
+ if snapshot_by_ref is None
+ else snapshot_by_ref.get(ref.model_ref)
+ )
+ options[ref.model_ref] = ChatModelOption(
+ model_ref=ref.model_ref,
+ provider_id=ref.provider_id,
+ model_id=ref.model_id,
+ supports_reasoning=(
+ info.supports_thinking if info is not None else None
+ ),
+ input_modalities=(info.input_modalities if info is not None else None),
+ context_window_tokens=(
+ info.context_window_tokens if info is not None else None
+ ),
+ max_output_tokens=(
+ info.max_output_tokens if info is not None else None
+ ),
+ )
+
+ for info in discovered:
+ try:
+ provider_id, model_id = split_provider_model_ref(info.model_id)
+ except ValueError:
+ continue
+ options[info.model_id] = ChatModelOption(
+ model_ref=info.model_id,
+ provider_id=provider_id,
+ model_id=model_id,
+ supports_reasoning=info.supports_thinking,
+ input_modalities=info.input_modalities,
+ context_window_tokens=info.context_window_tokens,
+ max_output_tokens=info.max_output_tokens,
+ )
+ return tuple(
+ sorted(options.values(), key=lambda item: item.model_ref.casefold())
+ )
+
+ def model(self, model_ref: str) -> ChatModelOption:
+ option = next(
+ (
+ candidate
+ for candidate in self.models()
+ if candidate.model_ref == model_ref
+ ),
+ None,
+ )
+ if option is None:
+ raise ChatValidationError(
+ "The selected model is unavailable. Choose an available model."
+ )
+ return option
+
+ def prepare(
+ self,
+ transcript: ChatTranscript,
+ *,
+ system_prompt: str,
+ draft: str | None = None,
+ exclude_generation_id: str | None = None,
+ ) -> PreparedChatRequest:
+ option = self.model(transcript.session.model)
+ reasoning = transcript.session.reasoning.policy()
+ self._validate_reasoning(option, transcript.session.reasoning)
+ output_limit = self._completion_limit(option, reasoning)
+ request = MessagesRequest(
+ model=transcript.session.model,
+ max_tokens=output_limit,
+ messages=self._messages(
+ transcript,
+ draft=draft,
+ exclude_generation_id=exclude_generation_id,
+ ),
+ system=system_prompt or None,
+ stream=True,
+ )
+ estimate = self._estimate(
+ request,
+ option=option,
+ output_limit=output_limit,
+ can_compact=self.can_compact(transcript),
+ )
+ routed = ModelRouter(
+ self._current_settings()
+ ).resolve_messages_request_with_policy(request, reasoning=reasoning)
+ return PreparedChatRequest(routed=routed, estimate=estimate, model=option)
+
+ def prepare_summary(
+ self,
+ *,
+ model_ref: str,
+ source: str,
+ output_tokens: int,
+ ) -> RoutedMessagesRequest:
+ option = self.model(model_ref)
+ reasoning = (
+ ReasoningPolicy.off()
+ if option.supports_reasoning is False
+ else ReasoningPolicy.on(effort=ReasoningEffort.LOW)
+ )
+ reasoning_tokens = reasoning.numeric_budget_tokens or 0
+ total_output = output_tokens + reasoning_tokens
+ if option.max_output_tokens is not None and option.max_output_tokens > 0:
+ total_output = min(total_output, option.max_output_tokens)
+ if total_output <= reasoning_tokens:
+ raise ChatValidationError(
+ "The selected model cannot reserve enough output for compaction."
+ )
+ request = MessagesRequest(
+ model=model_ref,
+ max_tokens=total_output,
+ messages=[Message(role="user", content=source)],
+ system=_SUMMARY_SYSTEM_PROMPT,
+ stream=True,
+ )
+ return ModelRouter(
+ self._current_settings()
+ ).resolve_messages_request_with_policy(
+ request,
+ reasoning=reasoning,
+ )
+
+ def summary_output_tokens(self, option: ChatModelOption) -> int:
+ if option.context_window_tokens is None:
+ return 4_096
+ return max(1_024, min(8_192, option.context_window_tokens // 20))
+
+ def summary_source_fits(
+ self,
+ *,
+ model_ref: str,
+ source: str,
+ output_tokens: int,
+ ) -> bool:
+ option = self.model(model_ref)
+ if option.context_window_tokens is None:
+ return True
+ routed = self.prepare_summary(
+ model_ref=model_ref,
+ source=source,
+ output_tokens=output_tokens,
+ )
+ estimated = get_token_count(
+ routed.request.messages,
+ routed.request.system,
+ routed.request.tools,
+ )
+ return (
+ estimated + (routed.request.max_tokens or 0) <= option.context_window_tokens
+ )
+
+ @staticmethod
+ def can_compact(transcript: ChatTranscript) -> bool:
+ covered = (
+ transcript.compaction.covered_through_sequence
+ if transcript.compaction is not None
+ else 0
+ )
+ return sum(turn.sequence > covered for turn in transcript.turns) > 1
+
+ @staticmethod
+ def compaction_source(
+ existing_summary: str | None,
+ turns: tuple[ChatTurn, ...],
+ ) -> str:
+ sections: list[str] = []
+ if existing_summary:
+ sections.append(f"CURRENT SUMMARY\n{existing_summary}")
+ for turn in turns:
+ answer = "\n".join(
+ segment.text
+ for segment in turn.generation.segments
+ if segment.kind is SegmentKind.TEXT and segment.text
+ )
+ section = f"USER\n{turn.user_text}"
+ if answer:
+ section = f"{section}\n\nASSISTANT\n{answer}"
+ sections.append(section)
+ return "\n\n--- EXCHANGE ---\n\n".join(sections)
+
+ @staticmethod
+ def _messages(
+ transcript: ChatTranscript,
+ *,
+ draft: str | None,
+ exclude_generation_id: str | None,
+ ) -> list[Message]:
+ messages: list[Message] = []
+ covered = 0
+ if transcript.compaction is not None:
+ covered = transcript.compaction.covered_through_sequence
+ messages.append(
+ Message(
+ role="user",
+ content=(
+ "[Earlier conversation summary]\n"
+ f"{transcript.compaction.summary}\n"
+ "[End earlier conversation summary]"
+ ),
+ )
+ )
+
+ for turn in transcript.turns:
+ if turn.sequence <= covered:
+ continue
+ messages.append(Message(role="user", content=turn.user_text))
+ generation = turn.generation
+ if generation.id == exclude_generation_id:
+ continue
+ blocks: list[ContentBlockText | ContentBlockThinking] = []
+ for segment in generation.segments:
+ if not segment.text:
+ continue
+ if segment.kind is SegmentKind.THINKING:
+ blocks.append(
+ ContentBlockThinking(
+ type="thinking",
+ thinking=segment.text,
+ signature=None,
+ )
+ )
+ else:
+ blocks.append(ContentBlockText(type="text", text=segment.text))
+ if blocks:
+ messages.append(Message(role="assistant", content=blocks))
+
+ if draft is not None:
+ messages.append(Message(role="user", content=draft))
+ return messages
+
+ @staticmethod
+ def _completion_limit(option: ChatModelOption, reasoning: ReasoningPolicy) -> int:
+ reasoning_tokens = reasoning.numeric_budget_tokens or 0
+ desired = _VISIBLE_ANSWER_TOKENS + reasoning_tokens
+ if option.max_output_tokens is not None and option.max_output_tokens > 0:
+ desired = min(desired, option.max_output_tokens)
+ if (
+ option.context_window_tokens is not None
+ and option.context_window_tokens > 0
+ ):
+ desired = min(
+ desired,
+ option.context_window_tokens - _MINIMUM_INPUT_TOKENS,
+ )
+ if desired - reasoning_tokens < _MINIMUM_VISIBLE_ANSWER_TOKENS:
+ raise ChatValidationError(
+ "The selected model cannot fit this thinking level. Lower thinking."
+ )
+ return desired
+
+ @staticmethod
+ def _validate_reasoning(option: ChatModelOption, reasoning: ChatReasoning) -> None:
+ if option.supports_reasoning is False and reasoning is not ChatReasoning.OFF:
+ raise ChatValidationError(
+ "This model does not support reasoning. Set thinking to Off."
+ )
+
+ @staticmethod
+ def _estimate(
+ request: MessagesRequest,
+ *,
+ option: ChatModelOption,
+ output_limit: int,
+ can_compact: bool,
+ ) -> ChatContextEstimate:
+ input_tokens = get_token_count(request.messages, request.system, request.tools)
+ context_window = option.context_window_tokens
+ if context_window is None or context_window <= 0:
+ return ChatContextEstimate(
+ estimated_input_tokens=input_tokens,
+ completion_tokens=output_limit,
+ context_window_tokens=None,
+ usable_input_tokens=None,
+ usage_ratio=None,
+ should_auto_compact=False,
+ can_compact=can_compact,
+ )
+ usable = context_window - output_limit
+ if usable <= 0:
+ raise ChatValidationError(
+ "The selected model's output reserve leaves no input context."
+ )
+ ratio = input_tokens / usable
+ return ChatContextEstimate(
+ estimated_input_tokens=input_tokens,
+ completion_tokens=output_limit,
+ context_window_tokens=context_window,
+ usable_input_tokens=usable,
+ usage_ratio=ratio,
+ should_auto_compact=ratio > _AUTO_COMPACT_RATIO and can_compact,
+ can_compact=can_compact,
+ )
+
+
+def compaction_target_tokens(estimate: ChatContextEstimate) -> int | None:
+ if estimate.usable_input_tokens is None:
+ return None
+ return int(estimate.usable_input_tokens * _COMPACT_TARGET_RATIO)
diff --git a/src/free_claude_code/application/chat/models.py b/src/free_claude_code/application/chat/models.py
new file mode 100644
index 00000000..670a7ed0
--- /dev/null
+++ b/src/free_claude_code/application/chat/models.py
@@ -0,0 +1,197 @@
+"""Precise domain values for local Chat Sessions."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.model_capabilities import ModelInputModality
+from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
+
+DEFAULT_CHAT_SYSTEM_PROMPT = (
+ "You are a helpful assistant. Answer accurately and clearly, using Markdown "
+ "when it improves readability."
+)
+
+
+class ChatReasoning(StrEnum):
+ """Reasoning controls exposed by the Chat UI."""
+
+ OFF = "off"
+ LOW = "low"
+ MEDIUM = "medium"
+ HIGH = "high"
+ XHIGH = "xhigh"
+ MAX = "max"
+
+ def policy(self) -> ReasoningPolicy:
+ """Return the provider-neutral policy for one Chat selection."""
+
+ if self is ChatReasoning.OFF:
+ return ReasoningPolicy.off()
+ return ReasoningPolicy.on(effort=ReasoningEffort(self.value))
+
+
+class GenerationStatus(StrEnum):
+ """Durable terminal and in-progress generation states."""
+
+ RUNNING = "running"
+ COMPLETED = "completed"
+ STOPPED = "stopped"
+ INTERRUPTED = "interrupted"
+ FAILED = "failed"
+
+
+class SegmentKind(StrEnum):
+ """Visible assistant segment kinds retained in exact stream order."""
+
+ THINKING = "thinking"
+ TEXT = "text"
+
+
+@dataclass(frozen=True, slots=True)
+class ChatPreferences:
+ system_prompt: str
+ last_model: str | None
+ last_reasoning: ChatReasoning
+ updated_at: int
+
+
+@dataclass(frozen=True, slots=True)
+class ChatSession:
+ id: str
+ title: str
+ model: str
+ reasoning: ChatReasoning
+ revision: int
+ created_at: int
+ updated_at: int
+
+
+@dataclass(frozen=True, slots=True)
+class ChatSessionSummary:
+ id: str
+ title: str
+ model: str
+ reasoning: ChatReasoning
+ revision: int
+ preview: str
+ created_at: int
+ updated_at: int
+
+
+@dataclass(frozen=True, slots=True)
+class ChatSessionPage:
+ sessions: tuple[ChatSessionSummary, ...]
+ next_cursor: tuple[int, str] | None
+
+
+@dataclass(frozen=True, slots=True)
+class ChatSegment:
+ ordinal: int
+ kind: SegmentKind
+ text: str
+
+
+@dataclass(frozen=True, slots=True)
+class ChatGeneration:
+ id: str
+ status: GenerationStatus
+ requested_model: str
+ actual_model: str | None
+ reasoning: ChatReasoning
+ effective_output_limit: int
+ stop_reason: str | None
+ error_code: str | None
+ error_message: str | None
+ started_at: int
+ finished_at: int | None
+ segments: tuple[ChatSegment, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ChatTurn:
+ id: str
+ session_id: str
+ operation_id: str
+ sequence: int
+ user_text: str
+ created_at: int
+ generation: ChatGeneration
+
+
+@dataclass(frozen=True, slots=True)
+class ChatCompaction:
+ session_id: str
+ covered_through_sequence: int
+ summary: str
+ estimated_tokens: int
+ requested_model: str
+ actual_model: str
+ updated_at: int
+
+
+@dataclass(frozen=True, slots=True)
+class ChatTranscript:
+ session: ChatSession
+ turns: tuple[ChatTurn, ...]
+ compaction: ChatCompaction | None
+
+
+@dataclass(frozen=True, slots=True)
+class ChatModelOption:
+ model_ref: str
+ provider_id: str
+ model_id: str
+ supports_reasoning: bool | None
+ input_modalities: frozenset[ModelInputModality] | None
+ context_window_tokens: int | None
+ max_output_tokens: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class ChatContextEstimate:
+ estimated_input_tokens: int
+ completion_tokens: int
+ context_window_tokens: int | None
+ usable_input_tokens: int | None
+ usage_ratio: float | None
+ should_auto_compact: bool
+ can_compact: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ChatSessionDetail:
+ session: ChatSession
+ turns: tuple[ChatTurn, ...]
+ next_before: int | None
+ compaction: ChatCompaction | None
+ context: ChatContextEstimate | None
+ context_error: str | None
+ active_operation: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ChatStreamEvent:
+ event: str
+ sequence: int
+ data: JsonObject
+
+
+class ChatError(Exception):
+ """Base class for application-owned Chat failures."""
+
+
+class ChatUnavailableError(ChatError):
+ """Chat state or lifecycle is unavailable while the proxy remains usable."""
+
+
+class ChatNotFoundError(ChatError):
+ """A requested Chat-owned resource does not exist."""
+
+
+class ChatConflictError(ChatError):
+ """The requested mutation conflicts with current session state."""
+
+
+class ChatValidationError(ChatError):
+ """The requested Chat operation cannot be executed as supplied."""
diff --git a/src/free_claude_code/application/chat/ports.py b/src/free_claude_code/application/chat/ports.py
new file mode 100644
index 00000000..f22c59d9
--- /dev/null
+++ b/src/free_claude_code/application/chat/ports.py
@@ -0,0 +1,246 @@
+"""Narrow ports owned by the local Chat Sessions application."""
+
+from collections.abc import AsyncIterator
+from typing import Protocol
+
+from .models import (
+ ChatCompaction,
+ ChatContextEstimate,
+ ChatGeneration,
+ ChatModelOption,
+ ChatPreferences,
+ ChatReasoning,
+ ChatSegment,
+ ChatSession,
+ ChatSessionDetail,
+ ChatSessionPage,
+ ChatStreamEvent,
+ ChatTranscript,
+ ChatTurn,
+ GenerationStatus,
+)
+
+
+class ChatStorePort(Protocol):
+ """Transactions required by Chat use cases, independent of SQLite."""
+
+ async def start(self) -> None: ...
+
+ async def close(self) -> None: ...
+
+ async def load_preferences(self) -> ChatPreferences: ...
+
+ async def save_system_prompt(self, system_prompt: str) -> ChatPreferences: ...
+
+ async def create_session(
+ self, *, session_id: str, model: str, reasoning: ChatReasoning
+ ) -> ChatSession: ...
+
+ async def list_sessions(
+ self,
+ *,
+ query: str,
+ cursor: tuple[int, str] | None,
+ limit: int,
+ ) -> ChatSessionPage: ...
+
+ async def get_session(self, session_id: str) -> ChatSession: ...
+
+ async def update_session(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ title: str | None,
+ model: str | None,
+ reasoning: ChatReasoning | None,
+ ) -> ChatSession: ...
+
+ async def delete_session(
+ self, session_id: str, *, expected_revision: int
+ ) -> None: ...
+
+ async def get_transcript(self, session_id: str) -> ChatTranscript: ...
+
+ async def get_turn_page(
+ self,
+ session_id: str,
+ *,
+ before_sequence: int | None,
+ limit: int,
+ ) -> tuple[tuple[ChatTurn, ...], int | None, ChatCompaction | None]: ...
+
+ async def generation_start_committed(
+ self,
+ session_id: str,
+ *,
+ generation_id: str,
+ staged: bool,
+ ) -> bool: ...
+
+ async def begin_send(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ turn_id: str,
+ generation_id: str,
+ operation_id: str,
+ user_text: str,
+ requested_model: str,
+ reasoning: ChatReasoning,
+ effective_output_limit: int,
+ ) -> ChatTurn: ...
+
+ async def begin_retry(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ requested_model: str,
+ reasoning: ChatReasoning,
+ effective_output_limit: int,
+ ) -> ChatGeneration: ...
+
+ async def begin_regenerate(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ generation_id: str,
+ requested_model: str,
+ reasoning: ChatReasoning,
+ effective_output_limit: int,
+ ) -> tuple[ChatTurn, ChatGeneration]: ...
+
+ async def set_generation_actual_model(
+ self, generation_id: str, actual_model: str
+ ) -> None: ...
+
+ async def replace_generation_segments(
+ self, generation_id: str, segments: tuple[ChatSegment, ...]
+ ) -> None: ...
+
+ async def finish_generation(
+ self,
+ generation_id: str,
+ *,
+ status: GenerationStatus,
+ stop_reason: str | None,
+ error_code: str | None,
+ error_message: str | None,
+ ) -> ChatSession: ...
+
+ async def discard_generation(self, generation_id: str) -> None: ...
+
+ async def finish_regeneration(
+ self, generation_id: str, *, stop_reason: str | None
+ ) -> ChatSession: ...
+
+ async def upsert_compaction(
+ self,
+ session_id: str,
+ *,
+ covered_through_sequence: int,
+ summary: str,
+ estimated_tokens: int,
+ requested_model: str,
+ actual_model: str,
+ ) -> ChatCompaction: ...
+
+
+class ChatOperationStream(Protocol):
+ """One initiating browser's event stream and cancellation boundary."""
+
+ operation_id: str
+
+ def __aiter__(self) -> AsyncIterator[ChatStreamEvent]: ...
+
+ async def aclose(self) -> None: ...
+
+
+class ChatApplicationPort(Protocol):
+ """Complete Chat capability consumed by the local HTTP adapter."""
+
+ def availability(self) -> tuple[bool, str | None]: ...
+
+ def models(self) -> tuple[ChatModelOption, ...]: ...
+
+ async def preferences(self) -> ChatPreferences: ...
+
+ async def save_system_prompt(self, value: str) -> ChatPreferences: ...
+
+ async def reset_system_prompt(self) -> ChatPreferences: ...
+
+ async def create_session(self) -> ChatSession: ...
+
+ async def list_sessions(
+ self,
+ *,
+ query: str,
+ cursor: tuple[int, str] | None,
+ limit: int,
+ ) -> ChatSessionPage: ...
+
+ async def get_session(self, session_id: str) -> ChatSession: ...
+
+ async def get_detail(self, session_id: str) -> ChatSessionDetail: ...
+
+ async def update_session(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ title: str | None,
+ model: str | None,
+ reasoning: ChatReasoning | None,
+ ) -> ChatSession: ...
+
+ async def delete_session(
+ self, session_id: str, *, expected_revision: int
+ ) -> None: ...
+
+ async def get_turn_page(
+ self,
+ session_id: str,
+ *,
+ before_sequence: int | None,
+ limit: int,
+ ) -> tuple[tuple[ChatTurn, ...], int | None, ChatCompaction | None]: ...
+
+ async def estimate(self, session_id: str, *, draft: str) -> ChatContextEstimate: ...
+
+ async def send(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ text: str,
+ ) -> ChatOperationStream: ...
+
+ async def retry(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ ) -> ChatOperationStream: ...
+
+ async def regenerate(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ ) -> ChatOperationStream: ...
+
+ async def compact(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ ) -> ChatOperationStream: ...
+
+ async def stop(self, session_id: str, *, operation_id: str) -> bool: ...
diff --git a/src/free_claude_code/application/chat/service.py b/src/free_claude_code/application/chat/service.py
new file mode 100644
index 00000000..ce11f8c8
--- /dev/null
+++ b/src/free_claude_code/application/chat/service.py
@@ -0,0 +1,1628 @@
+"""Application lifecycle and commands for durable local Chat Sessions."""
+
+import asyncio
+import contextlib
+import sys
+import time
+import uuid
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import dataclass, field, replace
+from enum import StrEnum
+
+from loguru import logger
+
+from free_claude_code.application.execution import ProviderExecutor
+from free_claude_code.application.ports import RequestRuntimeLease, RequestRuntimePort
+from free_claude_code.application.routing import ProviderModelTarget
+from free_claude_code.core.anthropic import (
+ ContentBlockText,
+ MessagesResponse,
+ aggregate_anthropic_sse_to_message,
+)
+from free_claude_code.core.anthropic.streaming import AnthropicSSEDecoder
+from free_claude_code.core.anthropic.tokens import estimate_text_tokens
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.trace import close_stream_input
+
+from .context import (
+ ChatContextBuilder,
+ PreparedChatRequest,
+ compaction_target_tokens,
+)
+from .models import (
+ DEFAULT_CHAT_SYSTEM_PROMPT,
+ ChatCompaction,
+ ChatConflictError,
+ ChatContextEstimate,
+ ChatModelOption,
+ ChatPreferences,
+ ChatReasoning,
+ ChatSegment,
+ ChatSession,
+ ChatSessionDetail,
+ ChatSessionPage,
+ ChatStreamEvent,
+ ChatTranscript,
+ ChatTurn,
+ ChatUnavailableError,
+ ChatValidationError,
+ GenerationStatus,
+ SegmentKind,
+)
+from .ports import ChatOperationStream, ChatStorePort
+
+_EVENT_QUEUE_SIZE = 128
+_PERSIST_INTERVAL_SECONDS = 0.25
+_PERSIST_CHARACTER_THRESHOLD = 4_096
+_TURN_PAGE_LIMIT = 50
+_SESSION_PAGE_LIMIT = 25
+_STORAGE_RESTART_MESSAGE = (
+ "Chat storage became unavailable. Restart FCC to repair Chat Sessions."
+)
+
+
+class _OperationKind(StrEnum):
+ SEND = "send"
+ RETRY = "retry"
+ REGENERATE = "regenerate"
+ COMPACT = "compact"
+
+
+class _CancellationReason(StrEnum):
+ STOPPED = "stopped"
+ INTERRUPTED = "interrupted"
+ DELETED = "deleted"
+
+
+class _TerminalPersistenceError(ChatUnavailableError):
+ """A bounded terminal write failed and requires startup repair."""
+
+
+@dataclass(slots=True)
+class _ActiveOperation:
+ session_id: str
+ operation_id: str
+ kind: _OperationKind
+ queue: asyncio.Queue[ChatStreamEvent | None] = field(
+ default_factory=lambda: asyncio.Queue(maxsize=_EVENT_QUEUE_SIZE)
+ )
+ task: asyncio.Task[None] | None = None
+ cancellation_reason: _CancellationReason | None = None
+ generation_id: str | None = None
+ regeneration: bool = False
+ segments: list[ChatSegment] = field(default_factory=list)
+ event_sequence: int = 0
+ actual_model: str | None = None
+ terminal_emitted: bool = False
+
+
+class _OperationStream:
+ """Initiating browser view of one application-owned operation."""
+
+ def __init__(self, service: ChatService, active: _ActiveOperation) -> None:
+ self._service = service
+ self._active = active
+ self.operation_id = active.operation_id
+ self._closed = False
+
+ def __aiter__(self) -> AsyncIterator[ChatStreamEvent]:
+ return self._events()
+
+ async def _events(self) -> AsyncIterator[ChatStreamEvent]:
+ while True:
+ event = await self._active.queue.get()
+ if event is None:
+ return
+ yield event
+
+ async def aclose(self) -> None:
+ if self._closed:
+ return
+ self._closed = True
+ task = self._active.task
+ if task is not None and not task.done():
+ await self._service._cancel_active(
+ self._active,
+ reason=_CancellationReason.STOPPED,
+ )
+
+
+class ChatService:
+ """Single owner of Chat session commands and active provider work."""
+
+ def __init__(self, runtime: RequestRuntimePort, store: ChatStorePort) -> None:
+ self._runtime = runtime
+ self._store = store
+ self._context = ChatContextBuilder(runtime)
+ self._active: dict[str, _ActiveOperation] = {}
+ self._deleting: set[str] = set()
+ self._active_lock = asyncio.Lock()
+ self._started = False
+ self._accepting = False
+ self._unavailable_message: str | None = "Chat Sessions is starting."
+
+ async def start(self) -> None:
+ if self._started:
+ return
+ try:
+ await self._store.start()
+ except asyncio.CancelledError:
+ raise
+ except Exception as exc:
+ self._unavailable_message = (
+ str(exc)
+ if isinstance(exc, ChatUnavailableError)
+ else "Chat storage could not be opened."
+ )
+ logger.warning(
+ "Chat Sessions unavailable: exc_type={}",
+ type(exc).__name__,
+ )
+ return
+ self._started = True
+ self._accepting = True
+ self._unavailable_message = None
+
+ async def close(self) -> None:
+ self._accepting = False
+ async with self._active_lock:
+ active = tuple(self._active.values())
+ await asyncio.gather(
+ *(
+ self._cancel_active(
+ operation,
+ reason=_CancellationReason.INTERRUPTED,
+ )
+ for operation in active
+ )
+ )
+ await self._store.close()
+ self._started = False
+ self._unavailable_message = "Chat Sessions is stopped."
+
+ def availability(self) -> tuple[bool, str | None]:
+ return self._started and self._accepting, self._unavailable_message
+
+ def models(self) -> tuple[ChatModelOption, ...]:
+ return self._context.models()
+
+ async def preferences(self) -> ChatPreferences:
+ self._require_available()
+ return await self._store.load_preferences()
+
+ async def save_system_prompt(self, value: str) -> ChatPreferences:
+ self._require_available()
+ return await self._store.save_system_prompt(value)
+
+ async def reset_system_prompt(self) -> ChatPreferences:
+ self._require_available()
+ return await self._store.save_system_prompt(DEFAULT_CHAT_SYSTEM_PROMPT)
+
+ async def create_session(self) -> ChatSession:
+ self._require_available()
+ preferences = await self._store.load_preferences()
+ options = self.models()
+ if not options:
+ raise ChatUnavailableError(
+ "No configured models are available for Chat Sessions."
+ )
+ available = {option.model_ref: option for option in options}
+ configured_default = self._runtime.current_settings().model
+ model = preferences.last_model
+ if model not in available:
+ model = (
+ configured_default
+ if configured_default in available
+ else options[0].model_ref
+ )
+ reasoning = preferences.last_reasoning
+ if available[model].supports_reasoning is False:
+ reasoning = ChatReasoning.OFF
+ return await self._store.create_session(
+ session_id=str(uuid.uuid4()),
+ model=model,
+ reasoning=reasoning,
+ )
+
+ async def list_sessions(
+ self,
+ *,
+ query: str,
+ cursor: tuple[int, str] | None,
+ limit: int,
+ ) -> ChatSessionPage:
+ self._require_available()
+ return await self._store.list_sessions(
+ query=query,
+ cursor=cursor,
+ limit=max(1, min(_SESSION_PAGE_LIMIT, limit)),
+ )
+
+ async def get_session(self, session_id: str) -> ChatSession:
+ self._require_available()
+ return await self._store.get_session(_canonical_uuid(session_id, "session"))
+
+ async def get_detail(self, session_id: str) -> ChatSessionDetail:
+ self._require_available()
+ session_id = _canonical_uuid(session_id, "session")
+ async with self._active_lock:
+ active_operation = session_id in self._active
+ transcript = await self._store.get_transcript(session_id)
+ prompt = (await self._store.load_preferences()).system_prompt
+ context: ChatContextEstimate | None
+ context_error: str | None = None
+ try:
+ context = self._context.prepare(
+ transcript,
+ system_prompt=prompt,
+ ).estimate
+ except ChatValidationError as exc:
+ context = None
+ context_error = str(exc)
+ has_more = len(transcript.turns) > _TURN_PAGE_LIMIT
+ turns = transcript.turns[-_TURN_PAGE_LIMIT:]
+ next_before = turns[0].sequence if has_more and turns else None
+ return ChatSessionDetail(
+ session=transcript.session,
+ turns=turns,
+ next_before=next_before,
+ compaction=transcript.compaction,
+ context=context,
+ context_error=context_error,
+ active_operation=active_operation,
+ )
+
+ async def update_session(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ title: str | None,
+ model: str | None,
+ reasoning: ChatReasoning | None,
+ ) -> ChatSession:
+ self._require_available()
+ session_id = _canonical_uuid(session_id, "session")
+ if title is not None:
+ title = " ".join(title.split())
+ if not title:
+ raise ChatValidationError("Chat title cannot be empty.")
+ if len(title) > 200:
+ raise ChatValidationError("Chat title cannot exceed 200 characters.")
+ if model is not None:
+ self._context.model(model)
+ async with self._active_lock:
+ if session_id in self._deleting:
+ raise ChatConflictError("This chat is being deleted.")
+ if (
+ model is not None or reasoning is not None
+ ) and session_id in self._active:
+ raise ChatConflictError(
+ "Model and thinking cannot change while this chat is running."
+ )
+ return await self._store.update_session(
+ session_id,
+ expected_revision=expected_revision,
+ title=title,
+ model=model,
+ reasoning=reasoning,
+ )
+
+ async def delete_session(self, session_id: str, *, expected_revision: int) -> None:
+ self._require_available()
+ session_id = _canonical_uuid(session_id, "session")
+ async with self._active_lock:
+ if session_id in self._deleting:
+ raise ChatConflictError("This chat is already being deleted.")
+ self._deleting.add(session_id)
+ active = self._active.get(session_id)
+ try:
+ current = await self._store.get_session(session_id)
+ _expect_revision(current, expected_revision)
+ if active is not None:
+ await self._cancel_active(active, reason=_CancellationReason.DELETED)
+ current = await self._store.get_session(session_id)
+ await self._store.delete_session(
+ session_id,
+ expected_revision=current.revision,
+ )
+ finally:
+ async with self._active_lock:
+ self._deleting.discard(session_id)
+
+ async def get_turn_page(
+ self,
+ session_id: str,
+ *,
+ before_sequence: int | None,
+ limit: int,
+ ) -> tuple[tuple[ChatTurn, ...], int | None, ChatCompaction | None]:
+ self._require_available()
+ if before_sequence is not None and before_sequence <= 0:
+ raise ChatValidationError("Turn cursor must be positive.")
+ return await self._store.get_turn_page(
+ _canonical_uuid(session_id, "session"),
+ before_sequence=before_sequence,
+ limit=max(1, min(_TURN_PAGE_LIMIT, limit)),
+ )
+
+ async def estimate(self, session_id: str, *, draft: str) -> ChatContextEstimate:
+ self._require_available()
+ transcript = await self._store.get_transcript(
+ _canonical_uuid(session_id, "session")
+ )
+ prompt = (await self._store.load_preferences()).system_prompt
+ return self._context.prepare(
+ transcript,
+ system_prompt=prompt,
+ draft=draft,
+ ).estimate
+
+ async def send(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ text: str,
+ ) -> ChatOperationStream:
+ self._require_available()
+ session_id = _canonical_uuid(session_id, "session")
+ operation_id = _canonical_uuid(operation_id, "operation")
+ if not text.strip():
+ raise ChatValidationError("Write a message before sending.")
+ transcript = await self._store.get_transcript(session_id)
+ _expect_revision(transcript.session, expected_revision)
+ prompt = (await self._store.load_preferences()).system_prompt
+ self._context.prepare(transcript, system_prompt=prompt, draft=text)
+ return await self._start_operation(
+ session_id,
+ operation_id=operation_id,
+ kind=_OperationKind.SEND,
+ action=lambda active: self._run_send(
+ active,
+ expected_revision=expected_revision,
+ text=text,
+ ),
+ )
+
+ async def retry(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ ) -> ChatOperationStream:
+ self._require_available()
+ session_id = _canonical_uuid(session_id, "session")
+ operation_id = _canonical_uuid(operation_id, "operation")
+ transcript = await self._store.get_transcript(session_id)
+ _expect_revision(transcript.session, expected_revision)
+ latest = _latest_turn(transcript)
+ if latest.generation.status not in {
+ GenerationStatus.STOPPED,
+ GenerationStatus.INTERRUPTED,
+ GenerationStatus.FAILED,
+ }:
+ raise ChatConflictError("Only the latest unfinished answer can be retried.")
+ prompt = (await self._store.load_preferences()).system_prompt
+ self._context.prepare(
+ transcript,
+ system_prompt=prompt,
+ exclude_generation_id=latest.generation.id,
+ )
+ return await self._start_operation(
+ session_id,
+ operation_id=operation_id,
+ kind=_OperationKind.RETRY,
+ action=lambda active: self._run_retry(
+ active,
+ expected_revision=expected_revision,
+ ),
+ )
+
+ async def regenerate(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ ) -> ChatOperationStream:
+ self._require_available()
+ session_id = _canonical_uuid(session_id, "session")
+ operation_id = _canonical_uuid(operation_id, "operation")
+ transcript = await self._store.get_transcript(session_id)
+ _expect_revision(transcript.session, expected_revision)
+ latest = _latest_turn(transcript)
+ if latest.generation.status is not GenerationStatus.COMPLETED:
+ raise ChatConflictError("Only the latest completed answer can regenerate.")
+ prompt = (await self._store.load_preferences()).system_prompt
+ self._context.prepare(
+ transcript,
+ system_prompt=prompt,
+ exclude_generation_id=latest.generation.id,
+ )
+ return await self._start_operation(
+ session_id,
+ operation_id=operation_id,
+ kind=_OperationKind.REGENERATE,
+ action=lambda active: self._run_regenerate(
+ active,
+ expected_revision=expected_revision,
+ ),
+ )
+
+ async def compact(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ ) -> ChatOperationStream:
+ self._require_available()
+ session_id = _canonical_uuid(session_id, "session")
+ operation_id = _canonical_uuid(operation_id, "operation")
+ transcript = await self._store.get_transcript(session_id)
+ _expect_revision(transcript.session, expected_revision)
+ if not self._context.can_compact(transcript):
+ raise ChatValidationError(
+ "There is not enough older conversation to compact."
+ )
+ return await self._start_operation(
+ session_id,
+ operation_id=operation_id,
+ kind=_OperationKind.COMPACT,
+ action=lambda active: self._run_manual_compaction(
+ active,
+ expected_revision=expected_revision,
+ ),
+ )
+
+ async def stop(self, session_id: str, *, operation_id: str) -> bool:
+ self._require_available()
+ session_id = _canonical_uuid(session_id, "session")
+ operation_id = _canonical_uuid(operation_id, "operation")
+ async with self._active_lock:
+ active = self._active.get(session_id)
+ if active is None:
+ return False
+ if active.operation_id != operation_id:
+ raise ChatConflictError("That operation is no longer active.")
+ await self._cancel_active(active, reason=_CancellationReason.STOPPED)
+ return True
+
+ async def _start_operation(
+ self,
+ session_id: str,
+ *,
+ operation_id: str,
+ kind: _OperationKind,
+ action: Callable[[_ActiveOperation], Awaitable[None]],
+ ) -> _OperationStream:
+ async with self._active_lock:
+ if not self._accepting:
+ raise ChatUnavailableError("Chat Sessions is shutting down.")
+ if session_id in self._deleting:
+ raise ChatConflictError("This chat is being deleted.")
+ if session_id in self._active:
+ raise ChatConflictError("This chat already has an active operation.")
+ active = _ActiveOperation(
+ session_id=session_id,
+ operation_id=operation_id,
+ kind=kind,
+ )
+ self._active[session_id] = active
+ active.task = asyncio.create_task(
+ self._run_active(active, action),
+ name=f"fcc-chat-{kind.value}-{operation_id}",
+ )
+ return _OperationStream(self, active)
+
+ async def _run_active(
+ self,
+ active: _ActiveOperation,
+ action: Callable[[_ActiveOperation], Awaitable[None]],
+ ) -> None:
+ try:
+ await action(active)
+ except asyncio.CancelledError:
+ settlement = asyncio.create_task(
+ self._handle_cancelled(active),
+ name=f"fcc-chat-settle-cancelled-{active.operation_id}",
+ )
+ await _await_task_despite_cancellation(settlement)
+ except Exception as exc:
+ settlement = asyncio.create_task(
+ self._handle_failure(active, exc),
+ name=f"fcc-chat-settle-failed-{active.operation_id}",
+ )
+ await _await_task_despite_cancellation(settlement)
+ finally:
+ release_task = asyncio.create_task(
+ self._release_active(active),
+ name=f"fcc-chat-release-{active.operation_id}",
+ )
+ await _await_task_despite_cancellation(release_task)
+
+ async def _run_send(
+ self,
+ active: _ActiveOperation,
+ *,
+ expected_revision: int,
+ text: str,
+ ) -> None:
+ lease = await self._runtime.acquire(include_model_infos=True)
+ try:
+ builder = ChatContextBuilder(
+ self._runtime,
+ settings=lease.settings,
+ model_infos=lease.model_infos,
+ )
+ prompt = (await self._store.load_preferences()).system_prompt
+ transcript = await self._store.get_transcript(active.session_id)
+ _expect_revision(transcript.session, expected_revision)
+ prepared = builder.prepare(transcript, system_prompt=prompt, draft=text)
+ if prepared.estimate.should_auto_compact:
+ await self._compact_transcript(
+ active,
+ builder=builder,
+ lease=lease,
+ transcript=transcript,
+ prompt=prompt,
+ pending_draft=text,
+ excluded_generation_id=None,
+ )
+ transcript = await self._store.get_transcript(active.session_id)
+ prepared = builder.prepare(
+ transcript,
+ system_prompt=prompt,
+ draft=text,
+ )
+ _require_request_fits(prepared.estimate)
+ generation_id = str(uuid.uuid4())
+ turn_id = str(uuid.uuid4())
+ await _commit_generation_start(
+ active,
+ store=self._store,
+ generation_id=generation_id,
+ operation=self._store.begin_send(
+ active.session_id,
+ expected_revision=transcript.session.revision,
+ turn_id=turn_id,
+ generation_id=generation_id,
+ operation_id=active.operation_id,
+ user_text=text,
+ requested_model=transcript.session.model,
+ reasoning=transcript.session.reasoning,
+ effective_output_limit=prepared.routed.request.max_tokens or 1,
+ ),
+ )
+ await self._emit(
+ active,
+ "turn.started",
+ {
+ "turn_id": turn_id,
+ "generation_id": generation_id,
+ "revision": transcript.session.revision + 1,
+ },
+ )
+ await self._execute_generation(active, prepared=prepared, lease=lease)
+ finally:
+ await lease.release()
+
+ async def _run_retry(
+ self,
+ active: _ActiveOperation,
+ *,
+ expected_revision: int,
+ ) -> None:
+ lease = await self._runtime.acquire(include_model_infos=True)
+ try:
+ builder = ChatContextBuilder(
+ self._runtime,
+ settings=lease.settings,
+ model_infos=lease.model_infos,
+ )
+ prompt = (await self._store.load_preferences()).system_prompt
+ transcript = await self._store.get_transcript(active.session_id)
+ _expect_revision(transcript.session, expected_revision)
+ latest = _latest_turn(transcript)
+ prepared = builder.prepare(
+ transcript,
+ system_prompt=prompt,
+ exclude_generation_id=latest.generation.id,
+ )
+ if prepared.estimate.should_auto_compact:
+ await self._compact_transcript(
+ active,
+ builder=builder,
+ lease=lease,
+ transcript=transcript,
+ prompt=prompt,
+ pending_draft=None,
+ excluded_generation_id=latest.generation.id,
+ )
+ transcript = await self._store.get_transcript(active.session_id)
+ latest = _latest_turn(transcript)
+ prepared = builder.prepare(
+ transcript,
+ system_prompt=prompt,
+ exclude_generation_id=latest.generation.id,
+ )
+ _require_request_fits(prepared.estimate)
+ generation_id = latest.generation.id
+ await _commit_generation_start(
+ active,
+ store=self._store,
+ generation_id=generation_id,
+ operation=self._store.begin_retry(
+ active.session_id,
+ expected_revision=transcript.session.revision,
+ requested_model=transcript.session.model,
+ reasoning=transcript.session.reasoning,
+ effective_output_limit=prepared.routed.request.max_tokens or 1,
+ ),
+ )
+ await self._emit(
+ active,
+ "turn.started",
+ {
+ "turn_id": latest.id,
+ "generation_id": generation_id,
+ "revision": transcript.session.revision + 1,
+ },
+ )
+ await self._execute_generation(active, prepared=prepared, lease=lease)
+ finally:
+ await lease.release()
+
+ async def _run_regenerate(
+ self,
+ active: _ActiveOperation,
+ *,
+ expected_revision: int,
+ ) -> None:
+ lease = await self._runtime.acquire(include_model_infos=True)
+ try:
+ builder = ChatContextBuilder(
+ self._runtime,
+ settings=lease.settings,
+ model_infos=lease.model_infos,
+ )
+ prompt = (await self._store.load_preferences()).system_prompt
+ transcript = await self._store.get_transcript(active.session_id)
+ _expect_revision(transcript.session, expected_revision)
+ latest = _latest_turn(transcript)
+ prepared = builder.prepare(
+ transcript,
+ system_prompt=prompt,
+ exclude_generation_id=latest.generation.id,
+ )
+ if prepared.estimate.should_auto_compact:
+ await self._compact_transcript(
+ active,
+ builder=builder,
+ lease=lease,
+ transcript=transcript,
+ prompt=prompt,
+ pending_draft=None,
+ excluded_generation_id=latest.generation.id,
+ )
+ transcript = await self._store.get_transcript(active.session_id)
+ latest = _latest_turn(transcript)
+ prepared = builder.prepare(
+ transcript,
+ system_prompt=prompt,
+ exclude_generation_id=latest.generation.id,
+ )
+ _require_request_fits(prepared.estimate)
+ generation_id = str(uuid.uuid4())
+ await _commit_generation_start(
+ active,
+ store=self._store,
+ generation_id=generation_id,
+ regeneration=True,
+ operation=self._store.begin_regenerate(
+ active.session_id,
+ expected_revision=transcript.session.revision,
+ generation_id=generation_id,
+ requested_model=transcript.session.model,
+ reasoning=transcript.session.reasoning,
+ effective_output_limit=prepared.routed.request.max_tokens or 1,
+ ),
+ )
+ await self._emit(
+ active,
+ "turn.started",
+ {
+ "turn_id": latest.id,
+ "generation_id": generation_id,
+ "revision": transcript.session.revision + 1,
+ "regeneration": True,
+ },
+ )
+ await self._execute_generation(active, prepared=prepared, lease=lease)
+ finally:
+ await lease.release()
+
+ async def _run_manual_compaction(
+ self,
+ active: _ActiveOperation,
+ *,
+ expected_revision: int,
+ ) -> None:
+ lease = await self._runtime.acquire(include_model_infos=True)
+ try:
+ builder = ChatContextBuilder(
+ self._runtime,
+ settings=lease.settings,
+ model_infos=lease.model_infos,
+ )
+ transcript = await self._store.get_transcript(active.session_id)
+ _expect_revision(transcript.session, expected_revision)
+ prompt = (await self._store.load_preferences()).system_prompt
+ await self._compact_transcript(
+ active,
+ builder=builder,
+ lease=lease,
+ transcript=transcript,
+ prompt=prompt,
+ pending_draft=None,
+ excluded_generation_id=None,
+ )
+ finally:
+ await lease.release()
+
+ async def _execute_generation(
+ self,
+ active: _ActiveOperation,
+ *,
+ prepared: PreparedChatRequest,
+ lease: RequestRuntimeLease,
+ ) -> None:
+ generation_id = active.generation_id
+ if generation_id is None:
+ raise RuntimeError("Chat generation was not initialized.")
+ executor = ProviderExecutor(
+ lease.resolve_provider,
+ progress_timeout_seconds=lease.settings.provider_progress_timeout,
+ generation_id=lease.generation_id,
+ log_raw_payloads=lease.settings.log_raw_api_payloads,
+ )
+
+ async def selected(target_model: ProviderModelTarget) -> None:
+ active.actual_model = target_model.provider_model_ref
+ await self._store.set_generation_actual_model(
+ generation_id, target_model.provider_model_ref
+ )
+
+ stream = executor.stream_messages(
+ prepared.routed,
+ raw_log_payload=prepared.routed.request.model_dump(mode="json"),
+ request_id=active.operation_id,
+ candidate_selected=selected,
+ )
+ decoder = AnthropicSSEDecoder()
+ block_segments: dict[int, int] = {}
+ saw_message_stop = False
+ stop_reason: str | None = None
+ last_flush = time.monotonic()
+ pending_characters = 0
+ try:
+ async for chunk in stream:
+ for event in decoder.feed(chunk):
+ (
+ delta_characters,
+ event_stop,
+ event_reason,
+ ) = await self._handle_sse_event(
+ active,
+ event_name=event.event,
+ data=event.data,
+ block_segments=block_segments,
+ )
+ pending_characters += delta_characters
+ saw_message_stop = saw_message_stop or event_stop
+ stop_reason = event_reason or stop_reason
+ now = time.monotonic()
+ if (
+ pending_characters >= _PERSIST_CHARACTER_THRESHOLD
+ or now - last_flush >= _PERSIST_INTERVAL_SECONDS
+ ):
+ await self._flush_segments(active)
+ last_flush = now
+ pending_characters = 0
+ for event in decoder.finish():
+ (
+ delta_characters,
+ event_stop,
+ event_reason,
+ ) = await self._handle_sse_event(
+ active,
+ event_name=event.event,
+ data=event.data,
+ block_segments=block_segments,
+ )
+ pending_characters += delta_characters
+ saw_message_stop = saw_message_stop or event_stop
+ stop_reason = event_reason or stop_reason
+ finally:
+ await close_stream_input(
+ stream,
+ owner="chat_sessions",
+ source="application",
+ preserved_error=sys.exception(),
+ )
+
+ if not saw_message_stop:
+ raise ChatValidationError("The provider stream ended before completing.")
+
+ async def commit_completion() -> ChatSession:
+ await self._flush_terminal_segments(active)
+ if active.regeneration:
+ return await self._finish_regeneration(
+ generation_id, stop_reason=stop_reason
+ )
+ return await self._finish_generation(
+ generation_id,
+ status=GenerationStatus.COMPLETED,
+ stop_reason=stop_reason,
+ error_code=None,
+ error_message=None,
+ )
+
+ commit_task = asyncio.create_task(
+ commit_completion(),
+ name=f"fcc-chat-generation-commit-{generation_id}",
+ )
+ session, _cancellation = await _await_task_despite_cancellation(commit_task)
+ self._emit_terminal_nowait(
+ active,
+ "turn.completed",
+ {
+ "generation_id": generation_id,
+ "revision": session.revision,
+ "actual_model": active.actual_model,
+ },
+ )
+
+ async def _handle_sse_event(
+ self,
+ active: _ActiveOperation,
+ *,
+ event_name: str,
+ data: dict[str, object],
+ block_segments: dict[int, int],
+ ) -> tuple[int, bool, str | None]:
+ payload_type = _optional_string(data.get("type"))
+ if event_name == "error" or payload_type == "error":
+ error = data.get("error")
+ message = "The provider returned an error."
+ if isinstance(error, dict):
+ candidate = error.get("message")
+ if isinstance(candidate, str) and candidate.strip():
+ message = candidate
+ raise ExecutionFailure(
+ kind=FailureKind.UPSTREAM,
+ status_code=502,
+ message=message,
+ retryable=False,
+ )
+ if payload_type == "content_block_start":
+ index = _required_index(data)
+ block = data.get("content_block")
+ if not isinstance(block, dict):
+ raise ChatValidationError(
+ "The provider emitted a malformed content block."
+ )
+ block_type = _optional_string(block.get("type"))
+ if block_type == "redacted_thinking":
+ return 0, False, None
+ if block_type not in {"text", "thinking"}:
+ raise ChatValidationError(
+ "The provider emitted an unsupported tool or content block."
+ )
+ kind = (
+ SegmentKind.THINKING if block_type == "thinking" else SegmentKind.TEXT
+ )
+ ordinal = len(active.segments)
+ active.segments.append(ChatSegment(ordinal=ordinal, kind=kind, text=""))
+ block_segments[index] = ordinal
+ await self._emit(
+ active,
+ "segment.started",
+ {"ordinal": ordinal, "kind": kind.value},
+ )
+ eager_key = "thinking" if kind is SegmentKind.THINKING else "text"
+ eager = _optional_string(block.get(eager_key)) or ""
+ if eager:
+ await self._append_delta(active, ordinal, eager)
+ return len(eager), False, None
+ if payload_type == "content_block_delta":
+ index = _required_index(data)
+ delta = data.get("delta")
+ if not isinstance(delta, dict):
+ raise ChatValidationError(
+ "The provider emitted a malformed content delta."
+ )
+ ordinal = block_segments.get(index)
+ if ordinal is None:
+ raise ChatValidationError(
+ "The provider emitted a delta for no open block."
+ )
+ delta_type = _optional_string(delta.get("type"))
+ if delta_type == "signature_delta":
+ return 0, False, None
+ key = "thinking" if delta_type == "thinking_delta" else "text"
+ if delta_type not in {"thinking_delta", "text_delta"}:
+ raise ChatValidationError(
+ "The provider emitted an unsupported content delta."
+ )
+ text = _optional_string(delta.get(key)) or ""
+ if text:
+ await self._append_delta(active, ordinal, text)
+ return len(text), False, None
+ if payload_type == "content_block_stop":
+ index = _required_index(data)
+ ordinal = block_segments.pop(index, None)
+ if ordinal is not None:
+ await self._flush_segments(active)
+ await self._emit(active, "segment.completed", {"ordinal": ordinal})
+ return 0, False, None
+ if payload_type == "message_delta":
+ delta = data.get("delta")
+ reason = None
+ if isinstance(delta, dict):
+ reason = _optional_string(delta.get("stop_reason"))
+ return 0, False, reason
+ if payload_type == "message_stop":
+ return 0, True, None
+ return 0, False, None
+
+ async def _append_delta(
+ self, active: _ActiveOperation, ordinal: int, delta: str
+ ) -> None:
+ current = active.segments[ordinal]
+ active.segments[ordinal] = replace(current, text=f"{current.text}{delta}")
+ await self._emit(
+ active,
+ "segment.delta",
+ {"ordinal": ordinal, "kind": current.kind.value, "delta": delta},
+ )
+
+ async def _flush_segments(self, active: _ActiveOperation) -> None:
+ if active.generation_id is None:
+ return
+ await self._store.replace_generation_segments(
+ active.generation_id,
+ tuple(active.segments),
+ )
+
+ async def _compact_transcript(
+ self,
+ active: _ActiveOperation,
+ *,
+ builder: ChatContextBuilder,
+ lease: RequestRuntimeLease,
+ transcript: ChatTranscript,
+ prompt: str,
+ pending_draft: str | None,
+ excluded_generation_id: str | None,
+ ) -> ChatCompaction:
+ covered = (
+ transcript.compaction.covered_through_sequence
+ if transcript.compaction is not None
+ else 0
+ )
+ remaining = tuple(turn for turn in transcript.turns if turn.sequence > covered)
+ if len(remaining) <= 1:
+ raise ChatValidationError(
+ "There is not enough older conversation to compact."
+ )
+ await self._emit(active, "compaction.started", {})
+ option = builder.model(transcript.session.model)
+ output_tokens = builder.summary_output_tokens(option)
+ retain_count = min(4, len(remaining) - 1)
+ initial_count = len(remaining) - retain_count
+ next_turns = remaining[:initial_count]
+ summary = transcript.compaction.summary if transcript.compaction else None
+ summary, actual_model = await self._summarize_turns(
+ active,
+ builder=builder,
+ lease=lease,
+ model_ref=transcript.session.model,
+ existing_summary=summary,
+ turns=next_turns,
+ output_tokens=output_tokens,
+ )
+ covered = next_turns[-1].sequence
+
+ while True:
+ candidate = ChatCompaction(
+ session_id=transcript.session.id,
+ covered_through_sequence=covered,
+ summary=summary,
+ estimated_tokens=estimate_text_tokens(summary),
+ requested_model=transcript.session.model,
+ actual_model=actual_model,
+ updated_at=0,
+ )
+ virtual = replace(transcript, compaction=candidate)
+ estimate = builder.prepare(
+ virtual,
+ system_prompt=prompt,
+ draft=pending_draft,
+ exclude_generation_id=excluded_generation_id,
+ ).estimate
+ target = compaction_target_tokens(estimate)
+ if target is None or estimate.estimated_input_tokens <= target:
+ break
+ later = tuple(turn for turn in remaining if turn.sequence > covered)
+ if len(later) <= 1:
+ raise ChatValidationError(
+ "The newest exchange cannot fit this model. Shorten the system "
+ "prompt, lower thinking, or choose a larger-context model."
+ )
+ summary, actual_model = await self._summarize_turns(
+ active,
+ builder=builder,
+ lease=lease,
+ model_ref=transcript.session.model,
+ existing_summary=summary,
+ turns=(later[0],),
+ output_tokens=output_tokens,
+ )
+ covered = later[0].sequence
+
+ async def commit_compaction() -> ChatCompaction:
+ return await self._retry_terminal_persistence(
+ lambda: self._store.upsert_compaction(
+ transcript.session.id,
+ covered_through_sequence=covered,
+ summary=summary,
+ estimated_tokens=estimate_text_tokens(summary),
+ requested_model=transcript.session.model,
+ actual_model=actual_model,
+ ),
+ label=(
+ f"compaction session_id={transcript.session.id} "
+ f"covered_through_sequence={covered}"
+ ),
+ )
+
+ commit_task = asyncio.create_task(
+ commit_compaction(),
+ name=f"fcc-chat-compaction-commit-{transcript.session.id}",
+ )
+ compaction, cancellation = await _await_task_despite_cancellation(commit_task)
+ completion: JsonObject = {
+ "covered_through_sequence": covered,
+ "revision": transcript.session.revision + 1,
+ }
+ if active.kind is _OperationKind.COMPACT:
+ self._emit_terminal_nowait(active, "compaction.completed", completion)
+ else:
+ self._emit_nowait(active, "compaction.completed", completion)
+ if cancellation is not None:
+ raise cancellation
+ return compaction
+
+ async def _summarize_turns(
+ self,
+ active: _ActiveOperation,
+ *,
+ builder: ChatContextBuilder,
+ lease: RequestRuntimeLease,
+ model_ref: str,
+ existing_summary: str | None,
+ turns: tuple[ChatTurn, ...],
+ output_tokens: int,
+ ) -> tuple[str, str]:
+ summary = existing_summary
+ pending = list(turns)
+ actual_model = model_ref
+ while pending:
+ take = len(pending)
+ if builder.model(model_ref).context_window_tokens is not None:
+ take = 0
+ for candidate_count in range(1, len(pending) + 1):
+ source = builder.compaction_source(
+ summary,
+ tuple(pending[:candidate_count]),
+ )
+ if not builder.summary_source_fits(
+ model_ref=model_ref,
+ source=source,
+ output_tokens=output_tokens,
+ ):
+ break
+ take = candidate_count
+ if take == 0:
+ take = 1
+ source = builder.compaction_source(summary, tuple(pending[:take]))
+ summary, actual_model = await self._execute_summary(
+ active,
+ builder=builder,
+ lease=lease,
+ model_ref=model_ref,
+ source=source,
+ output_tokens=output_tokens,
+ )
+ del pending[:take]
+ if summary is None:
+ raise ChatValidationError("Compaction produced no summary.")
+ return summary, actual_model
+
+ async def _execute_summary(
+ self,
+ active: _ActiveOperation,
+ *,
+ builder: ChatContextBuilder,
+ lease: RequestRuntimeLease,
+ model_ref: str,
+ source: str,
+ output_tokens: int,
+ ) -> tuple[str, str]:
+ routed = builder.prepare_summary(
+ model_ref=model_ref,
+ source=source,
+ output_tokens=output_tokens,
+ )
+ executor = ProviderExecutor(
+ lease.resolve_provider,
+ progress_timeout_seconds=lease.settings.provider_progress_timeout,
+ generation_id=lease.generation_id,
+ log_raw_payloads=lease.settings.log_raw_api_payloads,
+ )
+ selected_model: str | None = None
+
+ def selected(target_model: ProviderModelTarget) -> None:
+ nonlocal selected_model
+ selected_model = target_model.provider_model_ref
+
+ stream = executor.stream_messages(
+ routed,
+ raw_log_payload=routed.request.model_dump(mode="json"),
+ request_id=str(uuid.uuid4()),
+ candidate_selected=selected,
+ )
+ try:
+ body, error, complete = await aggregate_anthropic_sse_to_message(stream)
+ finally:
+ await close_stream_input(
+ stream,
+ owner="chat_compaction",
+ source="application",
+ preserved_error=sys.exception(),
+ )
+ if error is not None:
+ message = error.get("message")
+ raise ExecutionFailure(
+ kind=FailureKind.UPSTREAM,
+ status_code=502,
+ message=message if isinstance(message, str) else "Compaction failed.",
+ retryable=False,
+ )
+ if not complete:
+ raise ChatValidationError("The provider stream ended before completing.")
+ response = MessagesResponse.model_validate(body)
+ summary = "\n".join(
+ block.text
+ for block in response.content
+ if isinstance(block, ContentBlockText)
+ ).strip()
+ if not summary:
+ raise ChatValidationError("The model returned an empty compaction summary.")
+ if selected_model is None:
+ raise ChatValidationError(
+ "The provider did not identify the compaction model."
+ )
+ await self._emit(
+ active,
+ "compaction.progress",
+ {"covered_exchange_count": 1},
+ )
+ return summary, selected_model
+
+ async def _handle_cancelled(self, active: _ActiveOperation) -> None:
+ reason = active.cancellation_reason or _CancellationReason.STOPPED
+ if active.generation_id is not None:
+ try:
+ if active.regeneration:
+ await self._discard_regeneration(active.generation_id)
+ else:
+ await self._flush_terminal_segments(active)
+ status = (
+ GenerationStatus.INTERRUPTED
+ if reason is _CancellationReason.INTERRUPTED
+ else GenerationStatus.STOPPED
+ )
+ await self._finish_generation(
+ active.generation_id,
+ status=status,
+ stop_reason=reason.value,
+ error_code=None,
+ error_message=None,
+ )
+ except Exception as exc:
+ if reason is _CancellationReason.INTERRUPTED:
+ logger.warning(
+ "Chat shutdown could not persist terminal state: "
+ "session_id={} operation_id={} exc_type={}",
+ active.session_id,
+ active.operation_id,
+ type(exc).__name__,
+ )
+ return
+ self._disable_after_terminal_write_failure(active, exc)
+ if reason is _CancellationReason.DELETED:
+ raise
+ self._emit_terminal_nowait(
+ active,
+ "turn.failed",
+ {
+ "code": "chat_storage_unavailable",
+ "message": _STORAGE_RESTART_MESSAGE,
+ },
+ )
+ return
+ if reason is _CancellationReason.DELETED:
+ return
+ event = (
+ "compaction.stopped"
+ if active.kind is _OperationKind.COMPACT
+ else "turn.stopped"
+ )
+ self._emit_terminal_nowait(active, event, {"reason": reason.value})
+
+ async def _handle_failure(self, active: _ActiveOperation, exc: Exception) -> None:
+ if isinstance(exc, _TerminalPersistenceError):
+ self._disable_after_terminal_write_failure(active, exc)
+ event = (
+ "compaction.failed"
+ if active.kind is _OperationKind.COMPACT
+ else "turn.failed"
+ )
+ self._emit_terminal_nowait(
+ active,
+ event,
+ {
+ "code": "chat_storage_unavailable",
+ "message": _STORAGE_RESTART_MESSAGE,
+ },
+ )
+ return
+ code = "chat_error"
+ message = "Chat operation failed."
+ if isinstance(exc, ExecutionFailure):
+ code = exc.kind.value
+ message = exc.message
+ elif isinstance(
+ exc,
+ (ChatValidationError, ChatConflictError, ChatUnavailableError),
+ ):
+ code = type(exc).__name__
+ message = str(exc)
+ else:
+ logger.warning(
+ "Chat operation failed: session_id={} operation_id={} exc_type={}",
+ active.session_id,
+ active.operation_id,
+ type(exc).__name__,
+ )
+ if active.generation_id is not None:
+ try:
+ if active.regeneration:
+ await self._discard_regeneration(active.generation_id)
+ else:
+ await self._flush_terminal_segments(active)
+ await self._finish_generation(
+ active.generation_id,
+ status=GenerationStatus.FAILED,
+ stop_reason=None,
+ error_code=code,
+ error_message=message,
+ )
+ except Exception as persistence_exc:
+ self._disable_after_terminal_write_failure(
+ active,
+ persistence_exc,
+ )
+ code = "chat_storage_unavailable"
+ message = _STORAGE_RESTART_MESSAGE
+ event = (
+ "compaction.failed"
+ if active.kind is _OperationKind.COMPACT
+ else "turn.failed"
+ )
+ self._emit_terminal_nowait(active, event, {"code": code, "message": message})
+
+ async def _flush_terminal_segments(self, active: _ActiveOperation) -> None:
+ await self._retry_terminal_persistence(
+ lambda: self._flush_segments(active),
+ label=(
+ f"segment flush session_id={active.session_id} "
+ f"operation_id={active.operation_id}"
+ ),
+ )
+
+ async def _finish_generation(
+ self,
+ generation_id: str,
+ *,
+ status: GenerationStatus,
+ stop_reason: str | None,
+ error_code: str | None,
+ error_message: str | None,
+ ) -> ChatSession:
+ return await self._retry_terminal_persistence(
+ lambda: self._store.finish_generation(
+ generation_id,
+ status=status,
+ stop_reason=stop_reason,
+ error_code=error_code,
+ error_message=error_message,
+ ),
+ label=f"generation_id={generation_id} status={status.value}",
+ )
+
+ async def _finish_regeneration(
+ self,
+ generation_id: str,
+ *,
+ stop_reason: str | None,
+ ) -> ChatSession:
+ return await self._retry_terminal_persistence(
+ lambda: self._store.finish_regeneration(
+ generation_id,
+ stop_reason=stop_reason,
+ ),
+ label=f"regeneration_id={generation_id} status=completed",
+ )
+
+ async def _discard_regeneration(self, generation_id: str) -> None:
+ await self._retry_terminal_persistence(
+ lambda: self._store.discard_generation(generation_id),
+ label=f"regeneration_id={generation_id} status=discarded",
+ )
+
+ @staticmethod
+ async def _retry_terminal_persistence[T](
+ operation: Callable[[], Awaitable[T]],
+ *,
+ label: str,
+ ) -> T:
+ try:
+ return await operation()
+ except ChatUnavailableError:
+ logger.warning(
+ "Retrying transient Chat terminal persistence failure: {}",
+ label,
+ )
+ try:
+ return await operation()
+ except ChatUnavailableError as exc:
+ raise _TerminalPersistenceError(_STORAGE_RESTART_MESSAGE) from exc
+
+ def _disable_after_terminal_write_failure(
+ self,
+ active: _ActiveOperation,
+ exc: Exception,
+ ) -> None:
+ self._accepting = False
+ self._unavailable_message = _STORAGE_RESTART_MESSAGE
+ logger.error(
+ "Chat Sessions disabled after terminal persistence failure: "
+ "session_id={} operation_id={} exc_type={}",
+ active.session_id,
+ active.operation_id,
+ type(exc).__name__,
+ )
+
+ async def _emit(
+ self, active: _ActiveOperation, event: str, data: JsonObject
+ ) -> None:
+ active.event_sequence += 1
+ payload: JsonObject = {
+ "session_id": active.session_id,
+ "operation_id": active.operation_id,
+ **data,
+ }
+ await active.queue.put(
+ ChatStreamEvent(
+ event=event,
+ sequence=active.event_sequence,
+ data=payload,
+ )
+ )
+
+ def _emit_terminal_nowait(
+ self, active: _ActiveOperation, event: str, data: JsonObject
+ ) -> None:
+ if active.terminal_emitted:
+ return
+ self._emit_nowait(active, event, data)
+ active.terminal_emitted = True
+
+ def _emit_nowait(
+ self, active: _ActiveOperation, event: str, data: JsonObject
+ ) -> None:
+ active.event_sequence += 1
+ payload: JsonObject = {
+ "session_id": active.session_id,
+ "operation_id": active.operation_id,
+ **data,
+ }
+ _make_queue_room(active.queue)
+ active.queue.put_nowait(
+ ChatStreamEvent(
+ event=event,
+ sequence=active.event_sequence,
+ data=payload,
+ )
+ )
+
+ async def _cancel_active(
+ self,
+ active: _ActiveOperation,
+ *,
+ reason: _CancellationReason,
+ ) -> None:
+ task = active.task
+ if task is None or task.done():
+ return
+ if active.cancellation_reason is None:
+ active.cancellation_reason = reason
+ task.cancel()
+ cancellation: asyncio.CancelledError | None = None
+ try:
+ _result, cancellation = await _await_task_despite_cancellation(task)
+ except asyncio.CancelledError:
+ current = asyncio.current_task()
+ if current is not None and current.cancelling():
+ raise
+ finally:
+ await self._release_active(active)
+ if cancellation is not None:
+ raise cancellation
+
+ async def _release_active(self, active: _ActiveOperation) -> None:
+ async with self._active_lock:
+ if self._active.get(active.session_id) is not active:
+ return
+ self._active.pop(active.session_id, None)
+ _make_queue_room(active.queue)
+ active.queue.put_nowait(None)
+
+ def _require_available(self) -> None:
+ if not self._started or not self._accepting:
+ raise ChatUnavailableError(
+ self._unavailable_message or "Chat Sessions is unavailable."
+ )
+
+
+async def _commit_generation_start(
+ active: _ActiveOperation,
+ *,
+ store: ChatStorePort,
+ generation_id: str,
+ operation: Awaitable[object],
+ regeneration: bool = False,
+) -> None:
+ """Publish durable generation ownership before restoring cancellation."""
+
+ async def run() -> None:
+ await operation
+
+ task = asyncio.create_task(
+ run(),
+ name=f"fcc-chat-generation-start-{generation_id}",
+ )
+ cancellation = await _wait_task_despite_cancellation(task)
+ try:
+ task.result()
+ except ChatUnavailableError:
+
+ async def reconcile() -> bool:
+ return await store.generation_start_committed(
+ active.session_id,
+ generation_id=generation_id,
+ staged=regeneration,
+ )
+
+ reconciliation_task = asyncio.create_task(
+ reconcile(),
+ name=f"fcc-chat-generation-reconcile-{generation_id}",
+ )
+ try:
+ (
+ committed,
+ reconciliation_cancellation,
+ ) = await _await_task_despite_cancellation(reconciliation_task)
+ except ChatUnavailableError as exc:
+ raise _TerminalPersistenceError(_STORAGE_RESTART_MESSAGE) from exc
+ cancellation = cancellation or reconciliation_cancellation
+ if not committed:
+ raise
+ active.generation_id = generation_id
+ active.regeneration = regeneration
+ if cancellation is not None:
+ raise cancellation
+
+
+async def _wait_task_despite_cancellation[T](
+ task: asyncio.Task[T],
+) -> asyncio.CancelledError | None:
+ """Wait for a child outcome while retaining cancellation for its caller."""
+
+ current = asyncio.current_task()
+ cancellation: asyncio.CancelledError | None = None
+ while not task.done():
+ try:
+ await asyncio.shield(task)
+ except asyncio.CancelledError as exc:
+ if current is not None and current.cancelling():
+ cancellation = cancellation or exc
+ except Exception:
+ break
+ return cancellation
+
+
+async def _await_task_despite_cancellation[T](
+ task: asyncio.Task[T],
+) -> tuple[T, asyncio.CancelledError | None]:
+ """Wait for an already-started task before restoring caller cancellation."""
+
+ cancellation = await _wait_task_despite_cancellation(task)
+ result = task.result()
+ return result, cancellation
+
+
+def _latest_turn(transcript: ChatTranscript) -> ChatTurn:
+ if not transcript.turns:
+ raise ChatConflictError("This chat has no answer to operate on.")
+ return transcript.turns[-1]
+
+
+def _expect_revision(session: ChatSession, expected: int) -> None:
+ if expected <= 0 or session.revision != expected:
+ raise ChatConflictError("This chat changed in another tab. Refresh it.")
+
+
+def _require_request_fits(estimate: ChatContextEstimate) -> None:
+ if (
+ estimate.usable_input_tokens is not None
+ and estimate.estimated_input_tokens > estimate.usable_input_tokens
+ ):
+ raise ChatValidationError(
+ "This turn cannot fit the selected model. Shorten the message or system "
+ "prompt, lower thinking, or choose a larger-context model."
+ )
+
+
+def _canonical_uuid(value: str, label: str) -> str:
+ try:
+ parsed = uuid.UUID(value)
+ except (ValueError, AttributeError) as exc:
+ raise ChatValidationError(f"Invalid {label} ID.") from exc
+ if parsed.version != 4 or str(parsed) != value.lower():
+ raise ChatValidationError(f"Invalid {label} ID.")
+ return str(parsed)
+
+
+def _required_index(data: dict[str, object]) -> int:
+ value = data.get("index")
+ if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+ raise ChatValidationError("The provider emitted an invalid content index.")
+ return value
+
+
+def _optional_string(value: object) -> str | None:
+ return value if isinstance(value, str) else None
+
+
+def _make_queue_room(queue: asyncio.Queue[ChatStreamEvent | None]) -> None:
+ if queue.full():
+ with contextlib.suppress(asyncio.QueueEmpty):
+ queue.get_nowait()
diff --git a/src/free_claude_code/application/execution.py b/src/free_claude_code/application/execution.py
index 76f98781..f1fc457f 100644
--- a/src/free_claude_code/application/execution.py
+++ b/src/free_claude_code/application/execution.py
@@ -1,9 +1,10 @@
"""Provider execution shared by inbound API adapters."""
import asyncio
+import inspect
import math
import sys
-from collections.abc import AsyncIterator, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable
from typing import Literal
from loguru import logger
@@ -42,6 +43,7 @@ TokenCounter = Callable[
ResponsesTokenCounter = Callable[[OpenAIResponsesRequest], int]
WireApi = Literal["messages", "responses"]
CandidateStreamOpener = Callable[[int, ProviderModelTarget], AsyncIterator[str]]
+CandidateSelected = Callable[[ProviderModelTarget], Awaitable[None] | None]
class ProviderExecutor:
@@ -160,6 +162,7 @@ class ProviderExecutor:
*,
raw_log_payload: object,
request_id: str,
+ candidate_selected: CandidateSelected | None = None,
) -> AsyncIterator[str]:
"""Preflight and execute one Anthropic Messages request."""
@@ -214,6 +217,7 @@ class ProviderExecutor:
ingress_count=len(routed.request.messages),
request_id=request_id,
open_candidate=open_candidate,
+ candidate_selected=candidate_selected,
)
def stream_responses(
@@ -282,6 +286,7 @@ class ProviderExecutor:
ingress_count=input_item_count,
request_id=request_id,
open_candidate=open_candidate,
+ candidate_selected=None,
)
def _stream_candidates(
@@ -297,6 +302,7 @@ class ProviderExecutor:
ingress_count: int,
request_id: str,
open_candidate: CandidateStreamOpener,
+ candidate_selected: CandidateSelected | None,
) -> AsyncIterator[str]:
"""Run one protocol-blind candidate lifecycle after eager preflight."""
@@ -398,6 +404,10 @@ class ProviderExecutor:
continue
if not candidate_committed:
candidate_committed = True
+ if candidate_selected is not None:
+ selected_result = candidate_selected(target)
+ if inspect.isawaitable(selected_result):
+ await selected_result
if index > 0:
self._trace_fallback_selected(
request_id=request_id,
@@ -432,6 +442,10 @@ class ProviderExecutor:
) from exc
if candidate_failure is None:
+ if not candidate_committed and candidate_selected is not None:
+ selected_result = candidate_selected(target)
+ if inspect.isawaitable(selected_result):
+ await selected_result
return
if candidate_committed or index + 1 >= len(candidates):
raise candidate_failure
diff --git a/src/free_claude_code/application/ports.py b/src/free_claude_code/application/ports.py
index 4fa63463..51066402 100644
--- a/src/free_claude_code/application/ports.py
+++ b/src/free_claude_code/application/ports.py
@@ -62,6 +62,9 @@ class RequestRuntimeLease(Protocol):
@property
def settings(self) -> Settings: ...
+ @property
+ def model_infos(self) -> tuple[ProviderModelInfo, ...]: ...
+
def is_provider_cached(self, provider_id: str) -> bool: ...
def resolve_provider(self, provider_id: str) -> ProviderPort: ...
@@ -72,7 +75,9 @@ class RequestRuntimeLease(Protocol):
class RequestRuntimePort(Protocol):
"""Provider generation and model metadata required by application requests."""
- async def acquire(self) -> RequestRuntimeLease: ...
+ async def acquire(
+ self, *, include_model_infos: bool = False
+ ) -> RequestRuntimeLease: ...
def current_settings(self) -> Settings: ...
diff --git a/src/free_claude_code/application/routing.py b/src/free_claude_code/application/routing.py
index 863b0806..86b57f2c 100644
--- a/src/free_claude_code/application/routing.py
+++ b/src/free_claude_code/application/routing.py
@@ -211,6 +211,25 @@ class ModelRouter:
),
)
+ def resolve_messages_request_with_policy(
+ self,
+ request: MessagesRequest,
+ *,
+ reasoning: ReasoningPolicy,
+ ) -> RoutedMessagesRequest:
+ """Route an application-owned Messages request with resolved intent."""
+
+ resolved = self.resolve(request.model)
+ routed = request.model_copy(
+ update={"model": resolved.primary.provider_model},
+ deep=True,
+ )
+ return RoutedMessagesRequest(
+ request=routed,
+ resolved=resolved,
+ reasoning=reasoning,
+ )
+
def resolve_token_count_request(
self, request: TokenCountRequest
) -> RoutedTokenCountRequest:
diff --git a/src/free_claude_code/config/paths.py b/src/free_claude_code/config/paths.py
index 9d385bab..2d6af8f7 100644
--- a/src/free_claude_code/config/paths.py
+++ b/src/free_claude_code/config/paths.py
@@ -16,6 +16,9 @@ OPENAI_AUTH_LOCK_FILENAME = "openai.lock"
CONFIG_LOCK_FILENAME = "config.lock"
FCC_TEMP_DIRNAME = "tmp"
AIDER_TEMP_DIRNAME = "aider"
+CHAT_STATE_DIRNAME = "chat"
+CHAT_DATABASE_FILENAME = "chat.db"
+CHAT_LOCK_FILENAME = "chat.lock"
def config_dir_path() -> Path:
@@ -42,6 +45,24 @@ def aider_temp_dir_path() -> Path:
return config_dir_path() / FCC_TEMP_DIRNAME / AIDER_TEMP_DIRNAME
+def chat_state_dir_path() -> Path:
+ """Return the managed Chat Sessions state directory."""
+
+ return config_dir_path() / CHAT_STATE_DIRNAME
+
+
+def chat_database_path() -> Path:
+ """Return the managed Chat Sessions database path."""
+
+ return chat_state_dir_path() / CHAT_DATABASE_FILENAME
+
+
+def chat_lock_path() -> Path:
+ """Return the exclusive Chat Sessions process-lock path."""
+
+ return chat_state_dir_path() / CHAT_LOCK_FILENAME
+
+
def legacy_env_paths() -> tuple[Path, ...]:
"""Return legacy user env paths that can be migrated to ~/.fcc/.env."""
diff --git a/src/free_claude_code/core/anthropic/sse_aggregation.py b/src/free_claude_code/core/anthropic/sse_aggregation.py
index 9ddb336e..896c7bea 100644
--- a/src/free_claude_code/core/anthropic/sse_aggregation.py
+++ b/src/free_claude_code/core/anthropic/sse_aggregation.py
@@ -12,27 +12,30 @@ import uuid
from collections.abc import AsyncIterator
from typing import Any
-from .stream_contracts import parse_sse_text
+from .stream_contracts import SSEEvent
+from .streaming.decoder import AnthropicSSEDecoder
__all__ = ["aggregate_anthropic_sse_to_message"]
async def aggregate_anthropic_sse_to_message(
stream: AsyncIterator[str],
-) -> tuple[dict[str, Any], dict[str, Any] | None]:
+) -> tuple[dict[str, Any], dict[str, Any] | None, bool]:
"""Assemble a complete Messages JSON body from an Anthropic SSE stream.
- Returns ``(message_body, error)`` where ``error`` is the payload of a
- top-level ``event: error`` if one arrived, else ``None``.
+ Returns ``(message_body, error, complete)`` where ``error`` is the payload
+ of a top-level ``event: error`` if one arrived and ``complete`` records
+ whether the stream emitted ``message_stop``.
"""
- buffer = ""
+ decoder = AnthropicSSEDecoder()
message: dict[str, Any] = {}
blocks: dict[int, dict[str, Any]] = {}
parts: dict[int, list[str]] = {}
error: dict[str, Any] | None = None
+ complete = False
def handle_payload(payload: dict[str, Any]) -> None:
- nonlocal message, error
+ nonlocal message, error, complete
ptype = payload.get("type")
if ptype == "message_start":
started = payload.get("message")
@@ -86,13 +89,17 @@ async def aggregate_anthropic_sse_to_message(
if isinstance(err, dict)
else {"type": "api_error", "message": "provider error"}
)
+ elif ptype == "message_stop":
+ complete = True
+
+ def handle_event(event: SSEEvent) -> None:
+ handle_payload(event.data)
async for chunk in stream:
- buffer += chunk
- while "\n\n" in buffer:
- raw_event, buffer = buffer.split("\n\n", 1)
- for event in parse_sse_text(raw_event + "\n\n"):
- handle_payload(event.data)
+ for event in decoder.feed(chunk):
+ handle_event(event)
+ for event in decoder.finish():
+ handle_event(event)
content: list[dict[str, Any]] = []
for idx in sorted(blocks):
@@ -125,4 +132,4 @@ async def aggregate_anthropic_sse_to_message(
usage.setdefault("input_tokens", 0)
usage.setdefault("output_tokens", 0)
message["usage"] = usage
- return message, error
+ return message, error, complete
diff --git a/src/free_claude_code/core/anthropic/streaming/__init__.py b/src/free_claude_code/core/anthropic/streaming/__init__.py
index afe31200..7deb34d4 100644
--- a/src/free_claude_code/core/anthropic/streaming/__init__.py
+++ b/src/free_claude_code/core/anthropic/streaming/__init__.py
@@ -1,5 +1,6 @@
"""Shared Anthropic streaming engine."""
+from .decoder import AnthropicSSEDecoder
from .emitter import (
ANTHROPIC_SSE_RESPONSE_HEADERS,
AnthropicSseEmitter,
@@ -22,6 +23,7 @@ from .recovery import (
__all__ = [
"ANTHROPIC_SSE_RESPONSE_HEADERS",
+ "AnthropicSSEDecoder",
"AnthropicSseEmitter",
"AnthropicStreamLedger",
"StreamBlockLedger",
diff --git a/src/free_claude_code/core/anthropic/streaming/decoder.py b/src/free_claude_code/core/anthropic/streaming/decoder.py
new file mode 100644
index 00000000..33027f2a
--- /dev/null
+++ b/src/free_claude_code/core/anthropic/streaming/decoder.py
@@ -0,0 +1,49 @@
+"""Incremental framing for Anthropic-compatible SSE streams."""
+
+import re
+
+from ..stream_contracts import SSEEvent, parse_sse_text
+
+_EVENT_BOUNDARY = re.compile(r"\r?\n\r?\n")
+
+
+class AnthropicSSEDecoder:
+ """Decode arbitrarily split SSE text without losing frame order."""
+
+ def __init__(self) -> None:
+ self._parts: list[str] = []
+ self._boundary_tail = ""
+
+ def feed(self, chunk: str) -> tuple[SSEEvent, ...]:
+ """Consume one wire chunk and return every complete event."""
+
+ events: list[SSEEvent] = []
+ probe = self._boundary_tail + chunk
+ prefix_length = len(self._boundary_tail)
+ chunk_start = 0
+ for match in _EVENT_BOUNDARY.finditer(probe):
+ chunk_end = match.end() - prefix_length
+ self._parts.append(chunk[chunk_start:chunk_end])
+ raw = "".join(self._parts)
+ self._parts.clear()
+ events.extend(parse_sse_text(raw))
+ chunk_start = chunk_end
+
+ remainder = chunk[chunk_start:]
+ if remainder:
+ self._parts.append(remainder)
+ if chunk_start:
+ self._boundary_tail = remainder[-3:]
+ else:
+ self._boundary_tail = (self._boundary_tail + chunk)[-3:]
+ return tuple(events)
+
+ def finish(self) -> tuple[SSEEvent, ...]:
+ """Return a final unterminated event, if one is present."""
+
+ remainder = "".join(self._parts)
+ self._parts.clear()
+ self._boundary_tail = ""
+ if not remainder.strip():
+ return ()
+ return tuple(parse_sse_text(remainder))
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index dc0aea37..88444a22 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -13,6 +13,7 @@ from loguru import logger
import free_claude_code.cli.managed as cli_managed
import free_claude_code.messaging.session as messaging_session
import free_claude_code.messaging.workflow as messaging_workflow_module
+from free_claude_code.application.chat import ChatService
from free_claude_code.application.connected_accounts import (
ConnectedAccountLoginMode,
ConnectedAccountPort,
@@ -102,10 +103,12 @@ class ApplicationRuntime:
provider_manager: ProviderRuntimeManager,
*,
transcriber: Transcriber | None,
+ chat_service: ChatService | None = None,
restart_callback: RestartCallback | None = None,
connected_accounts: Mapping[str, ConnectedAccountPort] | None = None,
) -> None:
self.provider_manager = provider_manager
+ self._chat_service = chat_service
self._transcriber = transcriber
self._restart_callback = restart_callback
self._connected_accounts = dict(connected_accounts or {})
@@ -142,6 +145,8 @@ class ApplicationRuntime:
try:
await self.provider_manager.warm_referenced_model_cache()
self.provider_manager.start_model_list_refresh()
+ if self._chat_service is not None:
+ await self._chat_service.start()
await self._start_messaging_if_configured()
logging.getLogger("uvicorn.error").info(
"Admin UI: %s (local-only)",
@@ -436,9 +441,15 @@ class ApplicationRuntime:
async def _close_owned_resources(self) -> bool:
if not await self._cleanup_messaging():
return False
+ verbose = self.settings.log_api_error_tracebacks
+ if self._chat_service is not None and not await best_effort(
+ "chat_service.close",
+ self._chat_service.close(),
+ log_verbose_errors=verbose,
+ ):
+ return False
if not await self._cleanup_transcriber():
return False
- verbose = self.settings.log_api_error_tracebacks
if not self._provider_manager_closed:
self._provider_manager_closed = await best_effort(
"provider_manager.close",
diff --git a/src/free_claude_code/runtime/bootstrap.py b/src/free_claude_code/runtime/bootstrap.py
index 2277f58f..4a55b722 100644
--- a/src/free_claude_code/runtime/bootstrap.py
+++ b/src/free_claude_code/runtime/bootstrap.py
@@ -6,8 +6,13 @@ from pathlib import Path
from free_claude_code.api.app import create_app
from free_claude_code.api.ports import ApiServices
+from free_claude_code.application.chat import ChatService
from free_claude_code.config.logging_config import configure_logging
-from free_claude_code.config.paths import server_log_path
+from free_claude_code.config.paths import (
+ chat_database_path,
+ chat_lock_path,
+ server_log_path,
+)
from free_claude_code.config.settings import Settings
from free_claude_code.messaging.transcription import TranscriptionService
from free_claude_code.messaging.voice import Transcriber
@@ -23,6 +28,7 @@ from free_claude_code.providers.runtime.factory import create_provider
from .application import ApplicationRuntime, RestartCallback
from .asgi import RuntimeASGIApp
+from .chat_sqlite import SQLiteChatStore
from .codex_catalog import CodexModelCatalogPublisher
from .provider_manager import ProviderRuntimeManager
@@ -54,8 +60,13 @@ def build_asgi_app(
connected_provider_ids=openai_auth.connected_provider_ids,
model_catalog_publisher=CodexModelCatalogPublisher(),
)
+ chat_service = ChatService(
+ provider_manager,
+ SQLiteChatStore(chat_database_path(), chat_lock_path()),
+ )
runtime = ApplicationRuntime(
provider_manager,
+ chat_service=chat_service,
transcriber=_create_transcriber(settings),
restart_callback=restart_callback,
connected_accounts={"openai": openai_auth},
@@ -64,6 +75,7 @@ def build_asgi_app(
requests=provider_manager,
admin=runtime,
tasks=runtime,
+ chat=chat_service,
)
return RuntimeASGIApp(create_app(services), runtime)
diff --git a/src/free_claude_code/runtime/chat_sqlite.py b/src/free_claude_code/runtime/chat_sqlite.py
new file mode 100644
index 00000000..8d7d25cb
--- /dev/null
+++ b/src/free_claude_code/runtime/chat_sqlite.py
@@ -0,0 +1,1176 @@
+"""SQLite persistence owned exclusively by local Chat Sessions."""
+
+import os
+import sqlite3
+import time
+from collections.abc import Callable
+from functools import partial
+from pathlib import Path
+from typing import TypeVar
+
+import anyio.to_thread
+
+from free_claude_code.application.chat.models import (
+ DEFAULT_CHAT_SYSTEM_PROMPT,
+ ChatCompaction,
+ ChatConflictError,
+ ChatGeneration,
+ ChatNotFoundError,
+ ChatPreferences,
+ ChatReasoning,
+ ChatSegment,
+ ChatSession,
+ ChatSessionPage,
+ ChatSessionSummary,
+ ChatTranscript,
+ ChatTurn,
+ ChatUnavailableError,
+ GenerationStatus,
+ SegmentKind,
+)
+from free_claude_code.core.interprocess_lock import InterprocessFileLock
+
+T = TypeVar("T")
+
+_SCHEMA_VERSION = 1
+_BUSY_TIMEOUT_MS = 5_000
+_NEW_CHAT_TITLE = "New chat"
+
+
+class SQLiteChatStore:
+ """Short per-operation SQLite transactions behind one process lock."""
+
+ def __init__(self, database_path: Path, lock_path: Path) -> None:
+ self._database_path = database_path
+ self._lock = InterprocessFileLock(lock_path)
+ self._started = False
+
+ async def start(self) -> None:
+ if self._started:
+ return
+ directory = self._database_path.parent
+ await anyio.to_thread.run_sync(
+ partial(directory.mkdir, parents=True, exist_ok=True)
+ )
+ _owner_only(directory, 0o700)
+ acquired = await anyio.to_thread.run_sync(self._lock.acquire)
+ if not acquired:
+ raise ChatUnavailableError(
+ "Chat Sessions is already open in another FCC server process."
+ )
+ try:
+ await anyio.to_thread.run_sync(self._run_sync, self._migrate_and_repair)
+ _owner_only(self._database_path, 0o600)
+ for suffix in ("-wal", "-shm"):
+ sidecar = Path(f"{self._database_path}{suffix}")
+ if sidecar.exists():
+ _owner_only(sidecar, 0o600)
+ except sqlite3.Error as exc:
+ self._lock.release()
+ raise ChatUnavailableError("Chat storage is unavailable.") from exc
+ except BaseException:
+ self._lock.release()
+ raise
+ self._started = True
+
+ async def close(self) -> None:
+ self._started = False
+ await anyio.to_thread.run_sync(self._lock.release)
+
+ async def load_preferences(self) -> ChatPreferences:
+ return await self._run(self._load_preferences)
+
+ async def save_system_prompt(self, system_prompt: str) -> ChatPreferences:
+ def operation(connection: sqlite3.Connection) -> ChatPreferences:
+ now = _now_ms()
+ connection.execute("BEGIN IMMEDIATE")
+ connection.execute(
+ "UPDATE chat_settings SET system_prompt = ?, updated_at = ? WHERE id = 1",
+ (system_prompt, now),
+ )
+ connection.commit()
+ return self._load_preferences(connection)
+
+ return await self._run(operation)
+
+ async def create_session(
+ self, *, session_id: str, model: str, reasoning: ChatReasoning
+ ) -> ChatSession:
+ def operation(connection: sqlite3.Connection) -> ChatSession:
+ now = _now_ms()
+ connection.execute("BEGIN IMMEDIATE")
+ connection.execute(
+ """
+ INSERT INTO chat_sessions (
+ id, title, title_search, auto_title_pending, model, reasoning,
+ revision, created_at, updated_at
+ ) VALUES (?, ?, ?, 1, ?, ?, 1, ?, ?)
+ """,
+ (
+ session_id,
+ _NEW_CHAT_TITLE,
+ _NEW_CHAT_TITLE.casefold(),
+ model,
+ reasoning.value,
+ now,
+ now,
+ ),
+ )
+ connection.execute(
+ """
+ UPDATE chat_settings
+ SET last_model = ?, last_reasoning = ?, updated_at = ?
+ WHERE id = 1
+ """,
+ (model, reasoning.value, now),
+ )
+ connection.commit()
+ return self._get_session(connection, session_id)
+
+ return await self._run(operation)
+
+ async def list_sessions(
+ self,
+ *,
+ query: str,
+ cursor: tuple[int, str] | None,
+ limit: int,
+ ) -> ChatSessionPage:
+ def operation(connection: sqlite3.Connection) -> ChatSessionPage:
+ clauses: list[str] = []
+ parameters: list[object] = []
+ folded = query.strip().casefold()
+ if folded:
+ clauses.append("instr(s.title_search, ?) > 0")
+ parameters.append(folded)
+ if cursor is not None:
+ clauses.append("(s.updated_at < ? OR (s.updated_at = ? AND s.id < ?))")
+ parameters.extend((cursor[0], cursor[0], cursor[1]))
+ where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+ rows = connection.execute(
+ f"""
+ SELECT s.*,
+ COALESCE((
+ SELECT t.user_text FROM chat_turns AS t
+ WHERE t.session_id = s.id
+ ORDER BY t.sequence DESC LIMIT 1
+ ), '') AS preview
+ FROM chat_sessions AS s
+ {where}
+ ORDER BY s.updated_at DESC, s.id DESC
+ LIMIT ?
+ """,
+ (*parameters, limit + 1),
+ ).fetchall()
+ has_more = len(rows) > limit
+ selected = rows[:limit]
+ sessions = tuple(_session_summary_from_row(row) for row in selected)
+ next_cursor = None
+ if has_more and selected:
+ last = selected[-1]
+ next_cursor = (_row_int(last, "updated_at"), _row_str(last, "id"))
+ return ChatSessionPage(sessions=sessions, next_cursor=next_cursor)
+
+ return await self._run(operation)
+
+ async def get_session(self, session_id: str) -> ChatSession:
+ return await self._run(
+ lambda connection: self._get_session(connection, session_id)
+ )
+
+ async def update_session(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ title: str | None,
+ model: str | None,
+ reasoning: ChatReasoning | None,
+ ) -> ChatSession:
+ def operation(connection: sqlite3.Connection) -> ChatSession:
+ connection.execute("BEGIN IMMEDIATE")
+ current = self._get_session(connection, session_id)
+ _expect_revision(current, expected_revision)
+ next_title = current.title if title is None else title
+ next_model = current.model if model is None else model
+ next_reasoning = current.reasoning if reasoning is None else reasoning
+ now = _now_ms()
+ cursor = connection.execute(
+ """
+ UPDATE chat_sessions
+ SET title = ?, title_search = ?,
+ auto_title_pending = CASE
+ WHEN ? IS NULL THEN auto_title_pending ELSE 0
+ END,
+ model = ?, reasoning = ?,
+ revision = revision + 1, updated_at = ?
+ WHERE id = ? AND revision = ?
+ """,
+ (
+ next_title,
+ next_title.casefold(),
+ title,
+ next_model,
+ next_reasoning.value,
+ now,
+ session_id,
+ expected_revision,
+ ),
+ )
+ if cursor.rowcount != 1:
+ connection.rollback()
+ raise ChatConflictError("This chat changed in another tab. Refresh it.")
+ if model is not None or reasoning is not None:
+ connection.execute(
+ """
+ UPDATE chat_settings
+ SET last_model = ?, last_reasoning = ?, updated_at = ?
+ WHERE id = 1
+ """,
+ (next_model, next_reasoning.value, now),
+ )
+ connection.commit()
+ return self._get_session(connection, session_id)
+
+ return await self._run(operation)
+
+ async def delete_session(self, session_id: str, *, expected_revision: int) -> None:
+ def operation(connection: sqlite3.Connection) -> None:
+ connection.execute("BEGIN IMMEDIATE")
+ cursor = connection.execute(
+ "DELETE FROM chat_sessions WHERE id = ? AND revision = ?",
+ (session_id, expected_revision),
+ )
+ if cursor.rowcount != 1:
+ exists = connection.execute(
+ "SELECT 1 FROM chat_sessions WHERE id = ?", (session_id,)
+ ).fetchone()
+ connection.rollback()
+ if exists is None:
+ raise ChatNotFoundError("Chat session not found.")
+ raise ChatConflictError("This chat changed in another tab. Refresh it.")
+ connection.commit()
+
+ await self._run(operation)
+
+ async def get_transcript(self, session_id: str) -> ChatTranscript:
+ def operation(connection: sqlite3.Connection) -> ChatTranscript:
+ connection.execute("BEGIN")
+ try:
+ session = self._get_session(connection, session_id)
+ rows = connection.execute(
+ "SELECT * FROM chat_turns WHERE session_id = ? ORDER BY sequence",
+ (session_id,),
+ ).fetchall()
+ turns = tuple(self._turn_from_row(connection, row) for row in rows)
+ transcript = ChatTranscript(
+ session=session,
+ turns=turns,
+ compaction=self._get_compaction(connection, session_id),
+ )
+ connection.commit()
+ return transcript
+ except BaseException:
+ connection.rollback()
+ raise
+
+ return await self._run(operation)
+
+ async def get_turn_page(
+ self,
+ session_id: str,
+ *,
+ before_sequence: int | None,
+ limit: int,
+ ) -> tuple[tuple[ChatTurn, ...], int | None, ChatCompaction | None]:
+ def operation(
+ connection: sqlite3.Connection,
+ ) -> tuple[tuple[ChatTurn, ...], int | None, ChatCompaction | None]:
+ self._get_session(connection, session_id)
+ parameters: list[object] = [session_id]
+ before = ""
+ if before_sequence is not None:
+ before = "AND sequence < ?"
+ parameters.append(before_sequence)
+ rows = connection.execute(
+ f"""
+ SELECT * FROM chat_turns
+ WHERE session_id = ? {before}
+ ORDER BY sequence DESC LIMIT ?
+ """,
+ (*parameters, limit + 1),
+ ).fetchall()
+ has_more = len(rows) > limit
+ selected = rows[:limit]
+ selected.reverse()
+ turns = tuple(self._turn_from_row(connection, row) for row in selected)
+ next_before = turns[0].sequence if has_more and turns else None
+ return turns, next_before, self._get_compaction(connection, session_id)
+
+ return await self._run(operation)
+
+ async def generation_start_committed(
+ self,
+ session_id: str,
+ *,
+ generation_id: str,
+ staged: bool,
+ ) -> bool:
+ def operation(connection: sqlite3.Connection) -> bool:
+ row = connection.execute(
+ """
+ SELECT g.visible, g.status
+ FROM chat_generations AS g
+ JOIN chat_turns AS t ON t.id = g.turn_id
+ WHERE g.id = ? AND t.session_id = ?
+ """,
+ (generation_id, session_id),
+ ).fetchone()
+ if row is None:
+ return False
+ expected_visibility = 0 if staged else 1
+ return (
+ _row_int(row, "visible") == expected_visibility
+ and _row_str(row, "status") == GenerationStatus.RUNNING.value
+ )
+
+ return await self._run(operation)
+
+ async def begin_send(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ turn_id: str,
+ generation_id: str,
+ operation_id: str,
+ user_text: str,
+ requested_model: str,
+ reasoning: ChatReasoning,
+ effective_output_limit: int,
+ ) -> ChatTurn:
+ def operation(connection: sqlite3.Connection) -> ChatTurn:
+ connection.execute("BEGIN IMMEDIATE")
+ session = self._get_session(connection, session_id)
+ _expect_revision(session, expected_revision)
+ row = connection.execute(
+ "SELECT COALESCE(MAX(sequence), 0) + 1 AS next_sequence "
+ "FROM chat_turns WHERE session_id = ?",
+ (session_id,),
+ ).fetchone()
+ if row is None:
+ raise ChatUnavailableError("Could not allocate the next chat turn.")
+ sequence = _row_int(row, "next_sequence")
+ auto_title_row = connection.execute(
+ "SELECT auto_title_pending FROM chat_sessions WHERE id = ?",
+ (session_id,),
+ ).fetchone()
+ if auto_title_row is None:
+ raise ChatNotFoundError("Chat session not found.")
+ now = _now_ms()
+ title = session.title
+ if _row_int(auto_title_row, "auto_title_pending") == 1:
+ title = _title_from_text(user_text)
+ connection.execute(
+ """
+ INSERT INTO chat_turns (
+ id, session_id, operation_id, sequence, user_text, created_at
+ ) VALUES (?, ?, ?, ?, ?, ?)
+ """,
+ (turn_id, session_id, operation_id, sequence, user_text, now),
+ )
+ connection.execute(
+ """
+ INSERT INTO chat_generations (
+ id, turn_id, visible, status, requested_model, actual_model,
+ reasoning, effective_output_limit, stop_reason, error_code,
+ error_message, started_at, finished_at
+ ) VALUES (?, ?, 1, ?, ?, NULL, ?, ?, NULL, NULL, NULL, ?, NULL)
+ """,
+ (
+ generation_id,
+ turn_id,
+ GenerationStatus.RUNNING.value,
+ requested_model,
+ reasoning.value,
+ effective_output_limit,
+ now,
+ ),
+ )
+ cursor = connection.execute(
+ """
+ UPDATE chat_sessions
+ SET title = ?, title_search = ?, auto_title_pending = 0,
+ revision = revision + 1, updated_at = ?
+ WHERE id = ? AND revision = ?
+ """,
+ (title, title.casefold(), now, session_id, expected_revision),
+ )
+ if cursor.rowcount != 1:
+ connection.rollback()
+ raise ChatConflictError("This chat changed in another tab. Refresh it.")
+ turn = self._turn_by_id(connection, turn_id)
+ connection.commit()
+ return turn
+
+ return await self._run(operation)
+
+ async def begin_retry(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ requested_model: str,
+ reasoning: ChatReasoning,
+ effective_output_limit: int,
+ ) -> ChatGeneration:
+ def operation(connection: sqlite3.Connection) -> ChatGeneration:
+ connection.execute("BEGIN IMMEDIATE")
+ session = self._get_session(connection, session_id)
+ _expect_revision(session, expected_revision)
+ row = self._latest_visible_generation_row(connection, session_id)
+ if _row_str(row, "status") not in {
+ GenerationStatus.STOPPED.value,
+ GenerationStatus.INTERRUPTED.value,
+ GenerationStatus.FAILED.value,
+ }:
+ raise ChatConflictError(
+ "Only the latest unfinished answer can be retried."
+ )
+ generation_id = _row_str(row, "id")
+ now = _now_ms()
+ connection.execute(
+ "DELETE FROM chat_generation_segments WHERE generation_id = ?",
+ (generation_id,),
+ )
+ connection.execute(
+ """
+ UPDATE chat_generations
+ SET status = ?, requested_model = ?, actual_model = NULL,
+ reasoning = ?, effective_output_limit = ?, stop_reason = NULL,
+ error_code = NULL, error_message = NULL, started_at = ?,
+ finished_at = NULL
+ WHERE id = ?
+ """,
+ (
+ GenerationStatus.RUNNING.value,
+ requested_model,
+ reasoning.value,
+ effective_output_limit,
+ now,
+ generation_id,
+ ),
+ )
+ self._bump_session(connection, session_id, expected_revision, now)
+ generation = self._generation_by_id(connection, generation_id)
+ connection.commit()
+ return generation
+
+ return await self._run(operation)
+
+ async def begin_regenerate(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ generation_id: str,
+ requested_model: str,
+ reasoning: ChatReasoning,
+ effective_output_limit: int,
+ ) -> tuple[ChatTurn, ChatGeneration]:
+ def operation(
+ connection: sqlite3.Connection,
+ ) -> tuple[ChatTurn, ChatGeneration]:
+ connection.execute("BEGIN IMMEDIATE")
+ session = self._get_session(connection, session_id)
+ _expect_revision(session, expected_revision)
+ visible = self._latest_visible_generation_row(connection, session_id)
+ if _row_str(visible, "status") != GenerationStatus.COMPLETED.value:
+ raise ChatConflictError(
+ "Only the latest completed answer can regenerate."
+ )
+ turn_id = _row_str(visible, "turn_id")
+ now = _now_ms()
+ connection.execute(
+ """
+ INSERT INTO chat_generations (
+ id, turn_id, visible, status, requested_model, actual_model,
+ reasoning, effective_output_limit, stop_reason, error_code,
+ error_message, started_at, finished_at
+ ) VALUES (?, ?, 0, ?, ?, NULL, ?, ?, NULL, NULL, NULL, ?, NULL)
+ """,
+ (
+ generation_id,
+ turn_id,
+ GenerationStatus.RUNNING.value,
+ requested_model,
+ reasoning.value,
+ effective_output_limit,
+ now,
+ ),
+ )
+ self._bump_session(connection, session_id, expected_revision, now)
+ turn = self._turn_by_id(connection, turn_id)
+ generation = self._generation_by_id(connection, generation_id)
+ connection.commit()
+ return turn, generation
+
+ return await self._run(operation)
+
+ async def set_generation_actual_model(
+ self, generation_id: str, actual_model: str
+ ) -> None:
+ def operation(connection: sqlite3.Connection) -> None:
+ connection.execute("BEGIN IMMEDIATE")
+ cursor = connection.execute(
+ "UPDATE chat_generations SET actual_model = ? WHERE id = ?",
+ (actual_model, generation_id),
+ )
+ if cursor.rowcount != 1:
+ connection.rollback()
+ raise ChatNotFoundError("Chat generation not found.")
+ connection.commit()
+
+ await self._run(operation)
+
+ async def replace_generation_segments(
+ self, generation_id: str, segments: tuple[ChatSegment, ...]
+ ) -> None:
+ def operation(connection: sqlite3.Connection) -> None:
+ connection.execute("BEGIN IMMEDIATE")
+ if (
+ connection.execute(
+ "SELECT 1 FROM chat_generations WHERE id = ?", (generation_id,)
+ ).fetchone()
+ is None
+ ):
+ connection.rollback()
+ raise ChatNotFoundError("Chat generation not found.")
+ connection.execute(
+ "DELETE FROM chat_generation_segments WHERE generation_id = ?",
+ (generation_id,),
+ )
+ connection.executemany(
+ """
+ INSERT INTO chat_generation_segments
+ (generation_id, ordinal, kind, text)
+ VALUES (?, ?, ?, ?)
+ """,
+ (
+ (generation_id, segment.ordinal, segment.kind.value, segment.text)
+ for segment in segments
+ ),
+ )
+ connection.commit()
+
+ await self._run(operation)
+
+ async def finish_generation(
+ self,
+ generation_id: str,
+ *,
+ status: GenerationStatus,
+ stop_reason: str | None,
+ error_code: str | None,
+ error_message: str | None,
+ ) -> ChatSession:
+ if status is GenerationStatus.RUNNING:
+ raise ValueError("A generation cannot finish in Running state.")
+
+ def operation(connection: sqlite3.Connection) -> ChatSession:
+ connection.execute("BEGIN IMMEDIATE")
+ row = connection.execute(
+ """
+ SELECT g.visible, g.status, t.session_id
+ FROM chat_generations AS g
+ JOIN chat_turns AS t ON t.id = g.turn_id
+ WHERE g.id = ?
+ """,
+ (generation_id,),
+ ).fetchone()
+ if row is None:
+ raise ChatNotFoundError("Chat generation not found.")
+ session_id = _row_str(row, "session_id")
+ visible = bool(_row_int(row, "visible"))
+ if not visible:
+ connection.rollback()
+ raise ChatConflictError(
+ "Staged regenerations must finish through finish_regeneration."
+ )
+ if _row_str(row, "status") != GenerationStatus.RUNNING.value:
+ connection.rollback()
+ return self._get_session(connection, session_id)
+ now = _now_ms()
+ cursor = connection.execute(
+ """
+ UPDATE chat_generations
+ SET status = ?, stop_reason = ?, error_code = ?, error_message = ?,
+ finished_at = ?
+ WHERE id = ? AND status = ?
+ """,
+ (
+ status.value,
+ stop_reason,
+ error_code,
+ error_message,
+ now,
+ generation_id,
+ GenerationStatus.RUNNING.value,
+ ),
+ )
+ if cursor.rowcount != 1:
+ connection.rollback()
+ return self._get_session(connection, session_id)
+ connection.execute(
+ """
+ UPDATE chat_sessions
+ SET revision = revision + 1, updated_at = ? WHERE id = ?
+ """,
+ (now, session_id),
+ )
+ connection.commit()
+ return self._get_session(connection, session_id)
+
+ return await self._run(operation)
+
+ async def discard_generation(self, generation_id: str) -> None:
+ def operation(connection: sqlite3.Connection) -> None:
+ connection.execute("BEGIN IMMEDIATE")
+ row = connection.execute(
+ "SELECT visible FROM chat_generations WHERE id = ?",
+ (generation_id,),
+ ).fetchone()
+ if row is None:
+ connection.rollback()
+ return
+ if _row_int(row, "visible") != 0:
+ connection.rollback()
+ raise ChatConflictError("Visible answers cannot be discarded.")
+ connection.execute(
+ "DELETE FROM chat_generations WHERE id = ?",
+ (generation_id,),
+ )
+ connection.commit()
+
+ await self._run(operation)
+
+ async def finish_regeneration(
+ self, generation_id: str, *, stop_reason: str | None
+ ) -> ChatSession:
+ def operation(connection: sqlite3.Connection) -> ChatSession:
+ connection.execute("BEGIN IMMEDIATE")
+ row = connection.execute(
+ """
+ SELECT g.turn_id, g.visible, g.status, t.session_id
+ FROM chat_generations AS g
+ JOIN chat_turns AS t ON t.id = g.turn_id
+ WHERE g.id = ?
+ """,
+ (generation_id,),
+ ).fetchone()
+ if row is None:
+ connection.rollback()
+ raise ChatConflictError("Staged regeneration is unavailable.")
+ session_id = _row_str(row, "session_id")
+ if bool(_row_int(row, "visible")):
+ if _row_str(row, "status") == GenerationStatus.COMPLETED.value:
+ connection.rollback()
+ return self._get_session(connection, session_id)
+ connection.rollback()
+ raise ChatConflictError("Staged regeneration is unavailable.")
+ if _row_str(row, "status") != GenerationStatus.RUNNING.value:
+ connection.rollback()
+ raise ChatConflictError("Staged regeneration is not running.")
+ turn_id = _row_str(row, "turn_id")
+ now = _now_ms()
+ connection.execute(
+ "UPDATE chat_generations SET visible = 0 WHERE turn_id = ? AND visible = 1",
+ (turn_id,),
+ )
+ connection.execute(
+ """
+ UPDATE chat_generations
+ SET visible = 1, status = ?, stop_reason = ?, error_code = NULL,
+ error_message = NULL, finished_at = ?
+ WHERE id = ? AND visible = 0 AND status = ?
+ """,
+ (
+ GenerationStatus.COMPLETED.value,
+ stop_reason,
+ now,
+ generation_id,
+ GenerationStatus.RUNNING.value,
+ ),
+ )
+ connection.execute(
+ "DELETE FROM chat_generations WHERE turn_id = ? AND id != ?",
+ (turn_id, generation_id),
+ )
+ connection.execute(
+ """
+ UPDATE chat_sessions
+ SET revision = revision + 1, updated_at = ? WHERE id = ?
+ """,
+ (now, session_id),
+ )
+ connection.commit()
+ return self._get_session(connection, session_id)
+
+ return await self._run(operation)
+
+ async def upsert_compaction(
+ self,
+ session_id: str,
+ *,
+ covered_through_sequence: int,
+ summary: str,
+ estimated_tokens: int,
+ requested_model: str,
+ actual_model: str,
+ ) -> ChatCompaction:
+ def operation(connection: sqlite3.Connection) -> ChatCompaction:
+ connection.execute("BEGIN IMMEDIATE")
+ self._get_session(connection, session_id)
+ current = self._get_compaction(connection, session_id)
+ if current is not None and (
+ current.covered_through_sequence == covered_through_sequence
+ and current.summary == summary
+ and current.estimated_tokens == estimated_tokens
+ and current.requested_model == requested_model
+ and current.actual_model == actual_model
+ ):
+ connection.rollback()
+ return current
+ now = _now_ms()
+ connection.execute(
+ """
+ INSERT INTO chat_compactions (
+ session_id, covered_through_sequence, summary,
+ estimated_tokens, requested_model, actual_model, updated_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT(session_id) DO UPDATE SET
+ covered_through_sequence = excluded.covered_through_sequence,
+ summary = excluded.summary,
+ estimated_tokens = excluded.estimated_tokens,
+ requested_model = excluded.requested_model,
+ actual_model = excluded.actual_model,
+ updated_at = excluded.updated_at
+ """,
+ (
+ session_id,
+ covered_through_sequence,
+ summary,
+ estimated_tokens,
+ requested_model,
+ actual_model,
+ now,
+ ),
+ )
+ connection.execute(
+ """
+ UPDATE chat_sessions
+ SET revision = revision + 1, updated_at = ? WHERE id = ?
+ """,
+ (now, session_id),
+ )
+ compaction = self._get_compaction(connection, session_id)
+ if compaction is None:
+ connection.rollback()
+ raise ChatUnavailableError("Could not persist chat compaction.")
+ connection.commit()
+ return compaction
+
+ return await self._run(operation)
+
+ async def _run(self, operation: Callable[[sqlite3.Connection], T]) -> T:
+ if not self._started:
+ raise ChatUnavailableError("Chat storage is not available.")
+ try:
+ return await anyio.to_thread.run_sync(lambda: self._run_sync(operation))
+ except sqlite3.Error as exc:
+ raise ChatUnavailableError("Chat storage is unavailable.") from exc
+
+ def _run_sync(self, operation: Callable[[sqlite3.Connection], T]) -> T:
+ connection = sqlite3.connect(
+ self._database_path,
+ timeout=_BUSY_TIMEOUT_MS / 1_000,
+ isolation_level=None,
+ )
+ connection.row_factory = sqlite3.Row
+ try:
+ connection.execute("PRAGMA foreign_keys = ON")
+ connection.execute(f"PRAGMA busy_timeout = {_BUSY_TIMEOUT_MS}")
+ connection.execute("PRAGMA journal_mode = WAL")
+ return operation(connection)
+ finally:
+ connection.close()
+
+ def _migrate_and_repair(self, connection: sqlite3.Connection) -> None:
+ version_row = connection.execute("PRAGMA user_version").fetchone()
+ if version_row is None:
+ raise ChatUnavailableError("Could not read the Chat database schema.")
+ version_value: object = version_row[0]
+ if not isinstance(version_value, int):
+ raise ChatUnavailableError("Chat database schema is invalid.")
+ if version_value > _SCHEMA_VERSION:
+ raise ChatUnavailableError(
+ "Chat data was created by a newer FCC version. Update FCC to open it."
+ )
+ if version_value == 0:
+ try:
+ connection.executescript(_SCHEMA_V1)
+ connection.execute(
+ """
+ INSERT INTO chat_settings (
+ id, system_prompt, last_model, last_reasoning, updated_at
+ ) VALUES (1, ?, NULL, 'medium', 0)
+ """,
+ (DEFAULT_CHAT_SYSTEM_PROMPT,),
+ )
+ connection.execute(f"PRAGMA user_version = {_SCHEMA_VERSION}")
+ connection.commit()
+ except BaseException:
+ connection.rollback()
+ raise
+ elif version_value != _SCHEMA_VERSION:
+ raise ChatUnavailableError("Chat database schema is unsupported.")
+
+ now = _now_ms()
+ connection.execute("BEGIN IMMEDIATE")
+ connection.execute(
+ """
+ DELETE FROM chat_generations
+ WHERE visible = 0
+ """
+ )
+ affected = connection.execute(
+ """
+ SELECT DISTINCT t.session_id
+ FROM chat_generations AS g
+ JOIN chat_turns AS t ON t.id = g.turn_id
+ WHERE g.visible = 1 AND g.status = 'running'
+ """
+ ).fetchall()
+ connection.execute(
+ """
+ UPDATE chat_generations
+ SET status = 'interrupted', stop_reason = 'server_restart',
+ finished_at = ?
+ WHERE visible = 1 AND status = 'running'
+ """,
+ (now,),
+ )
+ connection.executemany(
+ """
+ UPDATE chat_sessions
+ SET revision = revision + 1, updated_at = ? WHERE id = ?
+ """,
+ ((_now_ms(), _row_str(row, "session_id")) for row in affected),
+ )
+ connection.commit()
+
+ @staticmethod
+ def _load_preferences(connection: sqlite3.Connection) -> ChatPreferences:
+ row = connection.execute("SELECT * FROM chat_settings WHERE id = 1").fetchone()
+ if row is None:
+ raise ChatUnavailableError("Chat settings are unavailable.")
+ return ChatPreferences(
+ system_prompt=_row_str(row, "system_prompt"),
+ last_model=_row_optional_str(row, "last_model"),
+ last_reasoning=ChatReasoning(_row_str(row, "last_reasoning")),
+ updated_at=_row_int(row, "updated_at"),
+ )
+
+ @staticmethod
+ def _get_session(connection: sqlite3.Connection, session_id: str) -> ChatSession:
+ row = connection.execute(
+ "SELECT * FROM chat_sessions WHERE id = ?", (session_id,)
+ ).fetchone()
+ if row is None:
+ raise ChatNotFoundError("Chat session not found.")
+ return _session_from_row(row)
+
+ @staticmethod
+ def _latest_visible_generation_row(
+ connection: sqlite3.Connection, session_id: str
+ ) -> sqlite3.Row:
+ row = connection.execute(
+ """
+ SELECT g.* FROM chat_generations AS g
+ JOIN chat_turns AS t ON t.id = g.turn_id
+ WHERE t.session_id = ? AND g.visible = 1
+ ORDER BY t.sequence DESC LIMIT 1
+ """,
+ (session_id,),
+ ).fetchone()
+ if row is None:
+ raise ChatConflictError("This chat has no answer to operate on.")
+ return row
+
+ def _turn_by_id(self, connection: sqlite3.Connection, turn_id: str) -> ChatTurn:
+ row = connection.execute(
+ "SELECT * FROM chat_turns WHERE id = ?", (turn_id,)
+ ).fetchone()
+ if row is None:
+ raise ChatNotFoundError("Chat turn not found.")
+ return self._turn_from_row(connection, row)
+
+ def _turn_from_row(
+ self, connection: sqlite3.Connection, row: sqlite3.Row
+ ) -> ChatTurn:
+ generation_row = connection.execute(
+ """
+ SELECT * FROM chat_generations
+ WHERE turn_id = ? AND visible = 1
+ """,
+ (_row_str(row, "id"),),
+ ).fetchone()
+ if generation_row is None:
+ raise ChatUnavailableError("Chat turn has no visible generation.")
+ return ChatTurn(
+ id=_row_str(row, "id"),
+ session_id=_row_str(row, "session_id"),
+ operation_id=_row_str(row, "operation_id"),
+ sequence=_row_int(row, "sequence"),
+ user_text=_row_str(row, "user_text"),
+ created_at=_row_int(row, "created_at"),
+ generation=self._generation_from_row(connection, generation_row),
+ )
+
+ def _generation_by_id(
+ self, connection: sqlite3.Connection, generation_id: str
+ ) -> ChatGeneration:
+ row = connection.execute(
+ "SELECT * FROM chat_generations WHERE id = ?", (generation_id,)
+ ).fetchone()
+ if row is None:
+ raise ChatNotFoundError("Chat generation not found.")
+ return self._generation_from_row(connection, row)
+
+ @staticmethod
+ def _generation_from_row(
+ connection: sqlite3.Connection, row: sqlite3.Row
+ ) -> ChatGeneration:
+ segment_rows = connection.execute(
+ """
+ SELECT * FROM chat_generation_segments
+ WHERE generation_id = ? ORDER BY ordinal
+ """,
+ (_row_str(row, "id"),),
+ ).fetchall()
+ return ChatGeneration(
+ id=_row_str(row, "id"),
+ status=GenerationStatus(_row_str(row, "status")),
+ requested_model=_row_str(row, "requested_model"),
+ actual_model=_row_optional_str(row, "actual_model"),
+ reasoning=ChatReasoning(_row_str(row, "reasoning")),
+ effective_output_limit=_row_int(row, "effective_output_limit"),
+ stop_reason=_row_optional_str(row, "stop_reason"),
+ error_code=_row_optional_str(row, "error_code"),
+ error_message=_row_optional_str(row, "error_message"),
+ started_at=_row_int(row, "started_at"),
+ finished_at=_row_optional_int(row, "finished_at"),
+ segments=tuple(
+ ChatSegment(
+ ordinal=_row_int(segment, "ordinal"),
+ kind=SegmentKind(_row_str(segment, "kind")),
+ text=_row_str(segment, "text"),
+ )
+ for segment in segment_rows
+ ),
+ )
+
+ @staticmethod
+ def _get_compaction(
+ connection: sqlite3.Connection, session_id: str
+ ) -> ChatCompaction | None:
+ row = connection.execute(
+ "SELECT * FROM chat_compactions WHERE session_id = ?", (session_id,)
+ ).fetchone()
+ if row is None:
+ return None
+ return ChatCompaction(
+ session_id=session_id,
+ covered_through_sequence=_row_int(row, "covered_through_sequence"),
+ summary=_row_str(row, "summary"),
+ estimated_tokens=_row_int(row, "estimated_tokens"),
+ requested_model=_row_str(row, "requested_model"),
+ actual_model=_row_str(row, "actual_model"),
+ updated_at=_row_int(row, "updated_at"),
+ )
+
+ @staticmethod
+ def _bump_session(
+ connection: sqlite3.Connection,
+ session_id: str,
+ expected_revision: int,
+ now: int,
+ ) -> None:
+ cursor = connection.execute(
+ """
+ UPDATE chat_sessions
+ SET revision = revision + 1, updated_at = ?
+ WHERE id = ? AND revision = ?
+ """,
+ (now, session_id, expected_revision),
+ )
+ if cursor.rowcount != 1:
+ connection.rollback()
+ raise ChatConflictError("This chat changed in another tab. Refresh it.")
+
+
+def _session_from_row(row: sqlite3.Row) -> ChatSession:
+ return ChatSession(
+ id=_row_str(row, "id"),
+ title=_row_str(row, "title"),
+ model=_row_str(row, "model"),
+ reasoning=ChatReasoning(_row_str(row, "reasoning")),
+ revision=_row_int(row, "revision"),
+ created_at=_row_int(row, "created_at"),
+ updated_at=_row_int(row, "updated_at"),
+ )
+
+
+def _session_summary_from_row(row: sqlite3.Row) -> ChatSessionSummary:
+ return ChatSessionSummary(
+ id=_row_str(row, "id"),
+ title=_row_str(row, "title"),
+ model=_row_str(row, "model"),
+ reasoning=ChatReasoning(_row_str(row, "reasoning")),
+ revision=_row_int(row, "revision"),
+ preview=_row_str(row, "preview"),
+ created_at=_row_int(row, "created_at"),
+ updated_at=_row_int(row, "updated_at"),
+ )
+
+
+def _expect_revision(session: ChatSession, expected: int) -> None:
+ if session.revision != expected:
+ raise ChatConflictError("This chat changed in another tab. Refresh it.")
+
+
+def _title_from_text(text: str) -> str:
+ collapsed = " ".join(text.split())
+ if len(collapsed) <= 64:
+ return collapsed
+ return f"{collapsed[:61].rstrip()}..."
+
+
+def _row_str(row: sqlite3.Row, key: str) -> str:
+ value: object = row[key]
+ if not isinstance(value, str):
+ raise ChatUnavailableError(f"Chat database field {key!r} is invalid.")
+ return value
+
+
+def _row_optional_str(row: sqlite3.Row, key: str) -> str | None:
+ value: object = row[key]
+ if value is None:
+ return None
+ if not isinstance(value, str):
+ raise ChatUnavailableError(f"Chat database field {key!r} is invalid.")
+ return value
+
+
+def _row_int(row: sqlite3.Row, key: str) -> int:
+ value: object = row[key]
+ if not isinstance(value, int) or isinstance(value, bool):
+ raise ChatUnavailableError(f"Chat database field {key!r} is invalid.")
+ return value
+
+
+def _row_optional_int(row: sqlite3.Row, key: str) -> int | None:
+ value: object = row[key]
+ if value is None:
+ return None
+ if not isinstance(value, int) or isinstance(value, bool):
+ raise ChatUnavailableError(f"Chat database field {key!r} is invalid.")
+ return value
+
+
+def _now_ms() -> int:
+ return time.time_ns() // 1_000_000
+
+
+def _owner_only(path: Path, mode: int) -> None:
+ if os.name != "nt" and path.exists():
+ path.chmod(mode)
+
+
+_SCHEMA_V1 = """
+BEGIN EXCLUSIVE;
+CREATE TABLE IF NOT EXISTS chat_settings (
+ id INTEGER PRIMARY KEY CHECK (id = 1),
+ system_prompt TEXT NOT NULL,
+ last_model TEXT,
+ last_reasoning TEXT NOT NULL CHECK (
+ last_reasoning IN ('off', 'low', 'medium', 'high', 'xhigh', 'max')
+ ),
+ updated_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS chat_sessions (
+ id TEXT PRIMARY KEY,
+ title TEXT NOT NULL,
+ title_search TEXT NOT NULL,
+ auto_title_pending INTEGER NOT NULL CHECK (auto_title_pending IN (0, 1)),
+ model TEXT NOT NULL,
+ reasoning TEXT NOT NULL CHECK (
+ reasoning IN ('off', 'low', 'medium', 'high', 'xhigh', 'max')
+ ),
+ revision INTEGER NOT NULL CHECK (revision > 0),
+ created_at INTEGER NOT NULL,
+ updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS chat_sessions_updated_idx
+ ON chat_sessions(updated_at DESC, id DESC);
+
+CREATE TABLE IF NOT EXISTS chat_turns (
+ id TEXT PRIMARY KEY,
+ session_id TEXT NOT NULL REFERENCES chat_sessions(id) ON DELETE CASCADE,
+ operation_id TEXT NOT NULL,
+ sequence INTEGER NOT NULL CHECK (sequence > 0),
+ user_text TEXT NOT NULL,
+ created_at INTEGER NOT NULL,
+ UNIQUE(session_id, sequence)
+);
+
+CREATE TABLE IF NOT EXISTS chat_generations (
+ id TEXT PRIMARY KEY,
+ turn_id TEXT NOT NULL REFERENCES chat_turns(id) ON DELETE CASCADE,
+ visible INTEGER NOT NULL CHECK (visible IN (0, 1)),
+ status TEXT NOT NULL CHECK (
+ status IN ('running', 'completed', 'stopped', 'interrupted', 'failed')
+ ),
+ requested_model TEXT NOT NULL,
+ actual_model TEXT,
+ reasoning TEXT NOT NULL CHECK (
+ reasoning IN ('off', 'low', 'medium', 'high', 'xhigh', 'max')
+ ),
+ effective_output_limit INTEGER NOT NULL CHECK (effective_output_limit > 0),
+ stop_reason TEXT,
+ error_code TEXT,
+ error_message TEXT,
+ started_at INTEGER NOT NULL,
+ finished_at INTEGER
+);
+CREATE UNIQUE INDEX IF NOT EXISTS chat_visible_generation_idx
+ ON chat_generations(turn_id) WHERE visible = 1;
+
+CREATE TABLE IF NOT EXISTS chat_generation_segments (
+ generation_id TEXT NOT NULL REFERENCES chat_generations(id) ON DELETE CASCADE,
+ ordinal INTEGER NOT NULL CHECK (ordinal >= 0),
+ kind TEXT NOT NULL CHECK (kind IN ('thinking', 'text')),
+ text TEXT NOT NULL,
+ PRIMARY KEY(generation_id, ordinal)
+);
+
+CREATE TABLE IF NOT EXISTS chat_compactions (
+ session_id TEXT PRIMARY KEY REFERENCES chat_sessions(id) ON DELETE CASCADE,
+ covered_through_sequence INTEGER NOT NULL CHECK (covered_through_sequence > 0),
+ summary TEXT NOT NULL,
+ estimated_tokens INTEGER NOT NULL CHECK (estimated_tokens > 0),
+ requested_model TEXT NOT NULL,
+ actual_model TEXT NOT NULL,
+ updated_at INTEGER NOT NULL
+);
+"""
diff --git a/src/free_claude_code/runtime/provider_manager.py b/src/free_claude_code/runtime/provider_manager.py
index 7f04cb60..81248a56 100644
--- a/src/free_claude_code/runtime/provider_manager.py
+++ b/src/free_claude_code/runtime/provider_manager.py
@@ -58,9 +58,11 @@ class ProviderGenerationLease:
self,
manager: ProviderRuntimeManager,
generation: _ProviderGeneration,
+ model_infos: tuple[ProviderModelInfo, ...],
) -> None:
self._manager = manager
self._generation = generation
+ self._model_infos = model_infos
self._released = False
@property
@@ -71,6 +73,10 @@ class ProviderGenerationLease:
def settings(self) -> Settings:
return self._generation.settings
+ @property
+ def model_infos(self) -> tuple[ProviderModelInfo, ...]:
+ return self._model_infos
+
def is_provider_cached(self, provider_id: str) -> bool:
return self._generation.runtime.is_cached(provider_id)
@@ -126,13 +132,19 @@ class ProviderRuntimeManager:
def current_generation_id(self) -> int:
return self._current.generation_id
- async def acquire(self) -> ProviderGenerationLease:
+ async def acquire(
+ self, *, include_model_infos: bool = False
+ ) -> ProviderGenerationLease:
if self._closing or self._closed:
raise ApplicationUnavailableError("Provider runtime is shutting down.")
generation = self._current
+ model_infos: tuple[ProviderModelInfo, ...] = ()
+ if include_model_infos:
+ self._synchronize_model_cache_scope()
+ model_infos = self._model_cache.cached_prefixed_model_infos()
generation.active_leases += 1
generation.drained.clear()
- return ProviderGenerationLease(self, generation)
+ return ProviderGenerationLease(self, generation, model_infos)
def current_settings(self) -> Settings:
return self._current.settings
diff --git a/tests/api/support.py b/tests/api/support.py
index 44ecc509..3b343ed5 100644
--- a/tests/api/support.py
+++ b/tests/api/support.py
@@ -6,6 +6,7 @@ from fastapi import FastAPI
from free_claude_code.api.app import create_app
from free_claude_code.api.ports import ApiServices
+from free_claude_code.application.chat import ChatApplicationPort
from free_claude_code.application.connected_accounts import ConnectedAccountPort
from free_claude_code.config.settings import Settings
from free_claude_code.providers.base import BaseProvider
@@ -20,6 +21,7 @@ def create_test_app(
providers: MutableMapping[str, BaseProvider] | None = None,
restart_callback: RestartCallback | None = None,
connected_accounts: Mapping[str, ConnectedAccountPort] | None = None,
+ chat: ChatApplicationPort | None = None,
) -> FastAPI:
"""Build an API app with explicit in-memory runtime services."""
settings = settings or Settings()
@@ -57,6 +59,7 @@ def create_test_app(
requests=manager,
admin=runtime,
tasks=runtime,
+ chat=chat,
)
)
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index 38aa552a..fc83c7f0 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -23,7 +23,11 @@ from tests.api.support import create_test_app, provider_manager_for_app, runtime
def _local_client(app):
- return TestClient(app, client=("127.0.0.1", 50000))
+ return TestClient(
+ app,
+ base_url="http://127.0.0.1",
+ client=("127.0.0.1", 50000),
+ )
def _set_home(monkeypatch, tmp_path: Path) -> None:
@@ -102,14 +106,23 @@ def test_admin_page_uses_installed_version(monkeypatch, tmp_path):
assert response.status_code == 200
assert "<p>Server Control · v9.8.7</p>" in response.text
assert 'href="/admin/assets/9.8.7/admin.css"' in response.text
+ assert 'href="/admin/assets/9.8.7/chat_sessions.css"' in response.text
+ assert 'src="/admin/assets/9.8.7/chat_sessions.js"' in response.text
assert 'src="/admin/assets/9.8.7/admin.js"' in response.text
assert 'href="/admin/assets/admin.css"' not in response.text
+ assert 'href="/admin/assets/chat_sessions.css"' not in response.text
+ assert 'src="/admin/assets/chat_sessions.js"' not in response.text
assert 'src="/admin/assets/admin.js"' not in response.text
@pytest.mark.parametrize(
("filename", "media_type"),
- (("admin.css", "text/css"), ("admin.js", "text/javascript")),
+ (
+ ("admin.css", "text/css"),
+ ("admin.js", "text/javascript"),
+ ("chat_sessions.css", "text/css"),
+ ("chat_sessions.js", "text/javascript"),
+ ),
)
def test_admin_versioned_assets_serve_packaged_files(
monkeypatch,
@@ -141,6 +154,8 @@ def test_admin_versioned_assets_serve_packaged_files(
"/admin",
f"/admin/assets/{package_version()}/admin.css",
f"/admin/assets/{package_version()}/admin.js",
+ f"/admin/assets/{package_version()}/chat_sessions.css",
+ f"/admin/assets/{package_version()}/chat_sessions.js",
"/admin/api/config",
),
)
@@ -182,7 +197,11 @@ def test_admin_http_errors_are_never_cached(
expected_status,
):
_set_home(monkeypatch, tmp_path)
- client = TestClient(create_test_app(), client=(client_host, 50000))
+ client = TestClient(
+ create_test_app(),
+ base_url="http://127.0.0.1",
+ client=(client_host, 50000),
+ )
response = client.get(path)
@@ -207,6 +226,7 @@ def test_admin_unexpected_errors_are_never_cached(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
client = TestClient(
create_test_app(),
+ base_url="http://127.0.0.1",
client=("127.0.0.1", 50000),
raise_server_exceptions=False,
)
diff --git a/tests/api/test_chat_markdown.py b/tests/api/test_chat_markdown.py
new file mode 100644
index 00000000..fdee0d7e
--- /dev/null
+++ b/tests/api/test_chat_markdown.py
@@ -0,0 +1,20 @@
+from free_claude_code.api.chat_markdown import render_chat_markdown
+
+
+def test_chat_markdown_escapes_html_and_never_loads_remote_images():
+ rendered = render_chat_markdown(
+ '<script>alert("x")</script>\n\n![diagram](https://example.com/image.png)'
+ )
+
+ assert "<script>" not in rendered
+ assert "&lt;script&gt;" in rendered
+ assert "<img" not in rendered
+ assert 'href="https://example.com/image.png"' in rendered
+ assert 'rel="noopener noreferrer"' in rendered
+
+
+def test_chat_markdown_disables_non_http_links():
+ rendered = render_chat_markdown("[unsafe](javascript:alert(1))")
+
+ assert "href=" not in rendered
+ assert "unsafe" in rendered
diff --git a/tests/api/test_chat_routes.py b/tests/api/test_chat_routes.py
new file mode 100644
index 00000000..8e0a7c00
--- /dev/null
+++ b/tests/api/test_chat_routes.py
@@ -0,0 +1,489 @@
+import asyncio
+import base64
+from collections.abc import AsyncIterator
+from dataclasses import replace
+from typing import cast
+
+import pytest
+from fastapi.testclient import TestClient
+from starlette.types import Message, Scope
+
+from free_claude_code.api.chat_routes import _stream_response
+from free_claude_code.application.chat import (
+ ChatCompaction,
+ ChatContextEstimate,
+ ChatModelOption,
+ ChatPreferences,
+ ChatReasoning,
+ ChatSegment,
+ ChatSession,
+ ChatSessionDetail,
+ ChatSessionPage,
+ ChatSessionSummary,
+ ChatStreamEvent,
+ ChatTurn,
+ ChatValidationError,
+ GenerationStatus,
+ SegmentKind,
+)
+from free_claude_code.application.chat.models import ChatGeneration
+from free_claude_code.core.model_capabilities import ModelInputModality
+from tests.api.support import create_test_app
+
+SESSION_ID = "29e3b8fd-8744-4377-b8cf-4c9d48daf962"
+OPERATION_ID = "7cd43d62-c1aa-42f8-9963-6c0811c0dfaf"
+
+
+class StubStream:
+ operation_id = OPERATION_ID
+
+ def __init__(self) -> None:
+ self.closed = False
+
+ def __aiter__(self) -> AsyncIterator[ChatStreamEvent]:
+ return self._events()
+
+ async def _events(self) -> AsyncIterator[ChatStreamEvent]:
+ yield ChatStreamEvent(
+ event="turn.completed",
+ sequence=1,
+ data={"operation_id": OPERATION_ID, "session_id": SESSION_ID},
+ )
+
+ async def aclose(self) -> None:
+ self.closed = True
+
+
+class StubChat:
+ def __init__(self) -> None:
+ self.session = ChatSession(
+ id=SESSION_ID,
+ title="Example",
+ model="groq/model",
+ reasoning=ChatReasoning.MEDIUM,
+ revision=1,
+ created_at=1,
+ updated_at=2,
+ )
+ generation = ChatGeneration(
+ id="generation",
+ status=GenerationStatus.COMPLETED,
+ requested_model="groq/model",
+ actual_model="open_router/fallback",
+ reasoning=ChatReasoning.MEDIUM,
+ effective_output_limit=1024,
+ stop_reason="end_turn",
+ error_code=None,
+ error_message=None,
+ started_at=1,
+ finished_at=2,
+ segments=(ChatSegment(0, SegmentKind.TEXT, "**safe** <script>x</script>"),),
+ )
+ self.turn = ChatTurn(
+ id="turn",
+ session_id=SESSION_ID,
+ operation_id="operation",
+ sequence=1,
+ user_text="hello",
+ created_at=1,
+ generation=generation,
+ )
+ self.preferences_value = ChatPreferences(
+ system_prompt="prompt",
+ last_model=self.session.model,
+ last_reasoning=self.session.reasoning,
+ updated_at=1,
+ )
+ self.last_stream: StubStream | None = None
+ self.deleted = False
+ self.active_operation = False
+
+ def availability(self) -> tuple[bool, str | None]:
+ return True, None
+
+ def models(self) -> tuple[ChatModelOption, ...]:
+ return (
+ ChatModelOption(
+ model_ref="groq/model",
+ provider_id="groq",
+ model_id="model",
+ supports_reasoning=True,
+ input_modalities=frozenset({ModelInputModality.TEXT}),
+ context_window_tokens=32_000,
+ max_output_tokens=8_000,
+ ),
+ )
+
+ async def preferences(self) -> ChatPreferences:
+ return self.preferences_value
+
+ async def save_system_prompt(self, value: str) -> ChatPreferences:
+ self.preferences_value = replace(self.preferences_value, system_prompt=value)
+ return self.preferences_value
+
+ async def reset_system_prompt(self) -> ChatPreferences:
+ return await self.save_system_prompt("default")
+
+ async def create_session(self) -> ChatSession:
+ return self.session
+
+ async def get_detail(self, session_id: str) -> ChatSessionDetail:
+ session = await self.get_session(session_id)
+ turns, next_before, compaction = await self.get_turn_page(
+ session_id,
+ before_sequence=None,
+ limit=50,
+ )
+ context: ChatContextEstimate | None
+ context_error: str | None = None
+ try:
+ context = await self.estimate(session_id, draft="")
+ except ChatValidationError as exc:
+ context = None
+ context_error = str(exc)
+ return ChatSessionDetail(
+ session=session,
+ turns=turns,
+ next_before=next_before,
+ compaction=compaction,
+ context=context,
+ context_error=context_error,
+ active_operation=self.active_operation,
+ )
+
+ async def list_sessions(
+ self,
+ *,
+ query: str,
+ cursor: tuple[int, str] | None,
+ limit: int,
+ ) -> ChatSessionPage:
+ del query, cursor, limit
+ return ChatSessionPage(
+ sessions=(
+ ChatSessionSummary(
+ id=self.session.id,
+ title=self.session.title,
+ model=self.session.model,
+ reasoning=self.session.reasoning,
+ revision=self.session.revision,
+ preview="hello",
+ created_at=self.session.created_at,
+ updated_at=self.session.updated_at,
+ ),
+ ),
+ next_cursor=None,
+ )
+
+ async def get_session(self, session_id: str) -> ChatSession:
+ assert session_id == SESSION_ID
+ return self.session
+
+ async def update_session(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ title: str | None,
+ model: str | None,
+ reasoning: ChatReasoning | None,
+ ) -> ChatSession:
+ assert session_id == SESSION_ID
+ assert expected_revision == self.session.revision
+ self.session = replace(
+ self.session,
+ title=title or self.session.title,
+ model=model or self.session.model,
+ reasoning=reasoning or self.session.reasoning,
+ revision=self.session.revision + 1,
+ )
+ return self.session
+
+ async def delete_session(self, session_id: str, *, expected_revision: int) -> None:
+ assert session_id == SESSION_ID
+ assert expected_revision == self.session.revision
+ self.deleted = True
+
+ async def get_turn_page(
+ self,
+ session_id: str,
+ *,
+ before_sequence: int | None,
+ limit: int,
+ ) -> tuple[tuple[ChatTurn, ...], int | None, ChatCompaction | None]:
+ assert session_id == SESSION_ID
+ del before_sequence, limit
+ return (self.turn,), None, None
+
+ async def estimate(self, session_id: str, *, draft: str) -> ChatContextEstimate:
+ assert session_id == SESSION_ID
+ del draft
+ return ChatContextEstimate(100, 1_024, 32_000, 30_976, 0.01, False, False)
+
+ async def send(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ text: str,
+ ) -> StubStream:
+ assert (session_id, expected_revision, operation_id, text) == (
+ SESSION_ID,
+ self.session.revision,
+ OPERATION_ID,
+ "hello",
+ )
+ self.last_stream = StubStream()
+ return self.last_stream
+
+ async def retry(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ ) -> StubStream:
+ del session_id, expected_revision, operation_id
+ return StubStream()
+
+ async def regenerate(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ ) -> StubStream:
+ del session_id, expected_revision, operation_id
+ return StubStream()
+
+ async def compact(
+ self,
+ session_id: str,
+ *,
+ expected_revision: int,
+ operation_id: str,
+ ) -> StubStream:
+ del session_id, expected_revision, operation_id
+ return StubStream()
+
+ async def stop(self, session_id: str, *, operation_id: str) -> bool:
+ return (session_id, operation_id) == (SESSION_ID, OPERATION_ID)
+
+
+class UnestimatableChat(StubChat):
+ async def estimate(self, session_id: str, *, draft: str) -> ChatContextEstimate:
+ assert session_id == SESSION_ID
+ del draft
+ raise ChatValidationError(
+ "This model does not support reasoning. Set thinking to Off."
+ )
+
+
+def _client(chat: StubChat | None = None) -> TestClient:
+ return TestClient(
+ create_test_app(chat=chat),
+ base_url="http://127.0.0.1",
+ client=("127.0.0.1", 50000),
+ )
+
+
+def test_chat_deep_links_serve_the_versioned_admin_shell():
+ response = _client().get(f"/admin/chat/{SESSION_ID}")
+
+ assert response.status_code == 200
+ assert "chat_sessions.js" in response.text
+ assert "Chat Sessions" not in response.headers.get("cache-control", "")
+ assert response.headers["cache-control"] == "no-store"
+
+
+def test_chat_bootstrap_and_detail_project_rich_models_and_safe_markdown():
+ chat = StubChat()
+ chat.active_operation = True
+ client = _client(chat)
+
+ bootstrap = client.get("/admin/api/chat/bootstrap").json()
+ detail = client.get(f"/admin/api/chat/sessions/{SESSION_ID}").json()
+
+ assert bootstrap["models"][0]["supports_reasoning"] is True
+ assert bootstrap["models"][0]["input_modalities"] == ["text"]
+ segment = detail["turns"][0]["generation"]["segments"][0]
+ assert segment["text"] == "**safe** <script>x</script>"
+ assert "<strong>safe</strong>" in segment["html"]
+ assert "<script>" not in segment["html"]
+ assert detail["turns"][0]["generation"]["actual_model"] == ("open_router/fallback")
+ assert detail["turns"][0]["operation_id"] == "operation"
+ assert detail["active_operation"] is True
+
+
+def test_chat_detail_stays_readable_when_context_controls_need_repair():
+ response = _client(UnestimatableChat()).get(
+ f"/admin/api/chat/sessions/{SESSION_ID}"
+ )
+
+ assert response.status_code == 200
+ assert response.json()["context"] is None
+ assert response.json()["context_error"] == (
+ "This model does not support reasoning. Set thinking to Off."
+ )
+
+
+def test_chat_crud_and_prompt_routes_use_application_port():
+ chat = StubChat()
+ client = _client(chat)
+
+ created = client.post("/admin/api/chat/sessions", json={})
+ renamed = client.patch(
+ f"/admin/api/chat/sessions/{SESSION_ID}",
+ json={"expected_revision": 1, "title": "Renamed"},
+ )
+ prompt = client.put(
+ "/admin/api/chat/preferences/system-prompt",
+ json={"value": "custom"},
+ )
+ deleted = client.request(
+ "DELETE",
+ f"/admin/api/chat/sessions/{SESSION_ID}",
+ json={"expected_revision": 2},
+ )
+
+ assert created.status_code == 201
+ assert renamed.json()["title"] == "Renamed"
+ assert prompt.json()["system_prompt"] == "custom"
+ assert deleted.json() == {"deleted": True}
+ assert chat.deleted is True
+
+
+def test_chat_stream_serializes_events_and_closes_operation():
+ chat = StubChat()
+ response = _client(chat).post(
+ f"/admin/api/chat/sessions/{SESSION_ID}/send",
+ json={
+ "expected_revision": 1,
+ "operation_id": OPERATION_ID,
+ "text": "hello",
+ },
+ )
+
+ assert response.status_code == 200
+ assert "event: turn.completed" in response.text
+ assert "id: 1" in response.text
+ assert chat.last_stream is not None and chat.last_stream.closed is True
+
+
+async def test_chat_stream_closes_when_cancelled_before_body_iteration():
+ stream = StubStream()
+ response = _stream_response(stream)
+ response_started = asyncio.Event()
+
+ async def receive() -> Message:
+ await asyncio.Event().wait()
+ raise AssertionError("unreachable")
+
+ async def send(message: Message) -> None:
+ assert message["type"] == "http.response.start"
+ response_started.set()
+ await asyncio.Event().wait()
+
+ scope = cast(
+ Scope,
+ {
+ "type": "http",
+ "asgi": {"version": "3.0", "spec_version": "2.4"},
+ "http_version": "1.1",
+ "method": "POST",
+ "scheme": "http",
+ "path": f"/admin/api/chat/sessions/{SESSION_ID}/send",
+ "raw_path": b"/admin/api/chat/sessions/send",
+ "query_string": b"",
+ "headers": [],
+ "client": ("127.0.0.1", 50000),
+ "server": ("127.0.0.1", 8000),
+ },
+ )
+ response_task = asyncio.create_task(response(scope, receive, send))
+ await asyncio.wait_for(response_started.wait(), timeout=1)
+ response_task.cancel()
+
+ with pytest.raises(asyncio.CancelledError):
+ await response_task
+ assert stream.closed is True
+
+
+def test_chat_routes_apply_loopback_and_origin_protection():
+ chat = StubChat()
+ remote = TestClient(
+ create_test_app(chat=chat),
+ client=("203.0.113.5", 50000),
+ )
+ local = _client(chat)
+
+ assert remote.get("/admin/api/chat/bootstrap").status_code == 403
+ assert (
+ local.get(
+ "/admin/api/chat/bootstrap",
+ headers={"Origin": "https://example.com"},
+ ).status_code
+ == 403
+ )
+ assert (
+ local.get(
+ "/admin/api/chat/bootstrap",
+ headers={"Host": "attacker.example:8000"},
+ ).status_code
+ == 403
+ )
+
+
+ "origin",
+ (
+ "http://127.0.0.1:not-a-port",
+ "https://[::1",
+ ),
+)
+def test_chat_routes_reject_malformed_local_origins(origin: str):
+ response = _client(StubChat()).get(
+ "/admin/api/chat/bootstrap",
+ headers={"Origin": origin},
+ )
+
+ assert response.status_code == 403
+ assert response.json() == {"detail": "Admin UI is local-only"}
+
+
+ "origin",
+ (
+ "http://127.0.0.1:8000",
+ "https://localhost",
+ "http://[::1]:8000",
+ ),
+)
+def test_chat_routes_accept_valid_local_origins(origin: str):
+ response = _client(StubChat()).get(
+ "/admin/api/chat/bootstrap",
+ headers={"Origin": origin},
+ )
+
+ assert response.status_code == 200
+
+
+def test_chat_without_composed_service_isolated_as_503():
+ response = _client().get("/admin/api/chat/bootstrap")
+
+ assert response.status_code == 503
+ assert response.json()["code"] == "ChatUnavailableError"
+
+
+def test_invalid_session_cursor_is_rejected():
+ client = _client(StubChat())
+ malformed = client.get("/admin/api/chat/sessions", params={"cursor": "not-valid"})
+ non_uuid = base64.urlsafe_b64encode(b"1:not-a-session").decode().rstrip("=")
+ invalid_id = client.get("/admin/api/chat/sessions", params={"cursor": non_uuid})
+
+ assert malformed.status_code == 400
+ assert malformed.json()["code"] == "ChatValidationError"
+ assert invalid_id.status_code == 400
+ assert invalid_id.json()["code"] == "ChatValidationError"
diff --git a/tests/api/test_request_lifetime.py b/tests/api/test_request_lifetime.py
index 8074ee88..339be379 100644
--- a/tests/api/test_request_lifetime.py
+++ b/tests/api/test_request_lifetime.py
@@ -60,6 +60,7 @@ async def _unused_send(_message: Message) -> None:
[
_http_scope("/health"),
_http_scope("/v1/messages", method="OPTIONS"),
+ _http_scope("/admin/api/chat/sessions/session/stop"),
cast(Scope, {"type": "lifespan", "asgi": {"version": "3.0"}}),
],
)
@@ -92,7 +93,14 @@ async def test_non_inference_scopes_delegate_with_original_callables(
@pytest.mark.asyncio
[email protected]("path", ["/v1/messages", "/v1/responses"])
+ "path",
+ [
+ "/v1/messages",
+ "/v1/responses",
+ "/admin/api/chat/sessions/session/send",
+ ],
+)
async def test_request_body_frames_are_relayed_once_in_order(path: str) -> None:
frames: asyncio.Queue[Message] = asyncio.Queue()
receiver_closed = asyncio.Event()
@@ -445,6 +453,7 @@ class _Lease:
def __init__(self, settings: Settings, provider: ProviderPort) -> None:
self.settings = settings
+ self.model_infos: tuple[ProviderModelInfo, ...] = ()
self._provider = provider
self.release_calls = 0
@@ -464,7 +473,10 @@ class _Requests:
def __init__(self, lease: _Lease) -> None:
self._lease = lease
- async def acquire(self) -> RequestRuntimeLease:
+ async def acquire(
+ self, *, include_model_infos: bool = False
+ ) -> RequestRuntimeLease:
+ assert include_model_infos is False
return self._lease
def current_settings(self) -> Settings:
diff --git a/tests/application/test_chat_context.py b/tests/application/test_chat_context.py
new file mode 100644
index 00000000..74d2c082
--- /dev/null
+++ b/tests/application/test_chat_context.py
@@ -0,0 +1,295 @@
+from free_claude_code.application.chat import (
+ ChatCompaction,
+ ChatGeneration,
+ ChatReasoning,
+ ChatSegment,
+ ChatSession,
+ ChatTranscript,
+ ChatTurn,
+ ChatValidationError,
+ GenerationStatus,
+ SegmentKind,
+)
+from free_claude_code.application.chat.context import ChatContextBuilder
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.application.ports import RequestRuntimeLease
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic import ContentBlockText, ContentBlockThinking
+from free_claude_code.core.model_capabilities import ModelInputModality
+from free_claude_code.core.reasoning import ReasoningControl, ReasoningEffort
+
+
+class FakeRuntime:
+ def __init__(
+ self,
+ *,
+ configured: ProviderModelInfo,
+ discovered: tuple[ProviderModelInfo, ...] = (),
+ ) -> None:
+ self.settings = Settings().model_copy(
+ update={
+ "model": "groq/model",
+ "model_fallbacks": None,
+ }
+ )
+ self.configured = configured
+ self.discovered = discovered
+
+ async def acquire(
+ self, *, include_model_infos: bool = False
+ ) -> RequestRuntimeLease:
+ del include_model_infos
+ raise AssertionError("Context construction must not acquire a runtime lease")
+
+ def current_settings(self) -> Settings:
+ return self.settings
+
+ def cached_model_info(
+ self, provider_id: str, model_id: str
+ ) -> ProviderModelInfo | None:
+ if provider_id == "groq" and model_id == "model":
+ return self.configured
+ return None
+
+ def cached_prefixed_model_infos(self) -> tuple[ProviderModelInfo, ...]:
+ return self.discovered
+
+
+def _transcript(
+ *,
+ reasoning: ChatReasoning = ChatReasoning.HIGH,
+ compaction: ChatCompaction | None = None,
+) -> ChatTranscript:
+ session = ChatSession(
+ id="session",
+ title="Chat",
+ model="groq/model",
+ reasoning=reasoning,
+ revision=1,
+ created_at=1,
+ updated_at=1,
+ )
+ generation = ChatGeneration(
+ id="generation",
+ status=GenerationStatus.COMPLETED,
+ requested_model=session.model,
+ actual_model=session.model,
+ reasoning=reasoning,
+ effective_output_limit=4096,
+ stop_reason="end_turn",
+ error_code=None,
+ error_message=None,
+ started_at=1,
+ finished_at=2,
+ segments=(
+ ChatSegment(0, SegmentKind.THINKING, "private-looking but exposed"),
+ ChatSegment(1, SegmentKind.TEXT, "answer"),
+ ),
+ )
+ return ChatTranscript(
+ session=session,
+ turns=(
+ ChatTurn(
+ id="turn",
+ session_id=session.id,
+ operation_id="operation",
+ sequence=1,
+ user_text="question",
+ created_at=1,
+ generation=generation,
+ ),
+ ),
+ compaction=compaction,
+ )
+
+
+def test_models_merge_configured_and_discovered_capabilities():
+ runtime = FakeRuntime(
+ configured=ProviderModelInfo(
+ "model",
+ supports_thinking=True,
+ input_modalities=frozenset(
+ {ModelInputModality.TEXT, ModelInputModality.IMAGE}
+ ),
+ context_window_tokens=100_000,
+ max_output_tokens=20_000,
+ ),
+ discovered=(
+ ProviderModelInfo(
+ "groq/discovered",
+ supports_thinking=False,
+ context_window_tokens=32_000,
+ ),
+ ),
+ )
+
+ options = ChatContextBuilder(runtime).models()
+
+ assert [option.model_ref for option in options] == [
+ "groq/discovered",
+ "groq/model",
+ ]
+ assert options[1].input_modalities == frozenset(
+ {ModelInputModality.TEXT, ModelInputModality.IMAGE}
+ )
+
+
+def test_explicit_model_metadata_snapshot_does_not_follow_live_cache():
+ runtime = FakeRuntime(
+ configured=ProviderModelInfo(
+ "model",
+ context_window_tokens=100_000,
+ max_output_tokens=20_000,
+ )
+ )
+ builder = ChatContextBuilder(
+ runtime,
+ model_infos=(
+ ProviderModelInfo(
+ "groq/model",
+ context_window_tokens=32_000,
+ max_output_tokens=4_096,
+ ),
+ ),
+ )
+
+ prepared = builder.prepare(
+ _transcript(reasoning=ChatReasoning.OFF),
+ system_prompt="",
+ draft="hello",
+ )
+
+ assert prepared.model.context_window_tokens == 32_000
+ assert prepared.routed.request.max_tokens == 4_096
+
+
+def test_prepare_builds_ordered_messages_and_authoritative_reasoning():
+ runtime = FakeRuntime(
+ configured=ProviderModelInfo(
+ "model",
+ supports_thinking=True,
+ context_window_tokens=100_000,
+ max_output_tokens=20_000,
+ )
+ )
+ prepared = ChatContextBuilder(runtime).prepare(
+ _transcript(),
+ system_prompt="custom",
+ draft="follow up",
+ )
+
+ request = prepared.routed.request
+ assert request.system == "custom"
+ assert [message.role for message in request.messages] == [
+ "user",
+ "assistant",
+ "user",
+ ]
+ assistant = request.messages[1].content
+ assert isinstance(assistant, list)
+ assert isinstance(assistant[0], ContentBlockThinking)
+ assert isinstance(assistant[1], ContentBlockText)
+ assert prepared.routed.reasoning.control is ReasoningControl.ON
+ assert prepared.routed.reasoning.effort is ReasoningEffort.HIGH
+ assert request.max_tokens == 18_432
+
+
+def test_known_unsupported_reasoning_is_rejected_but_unknown_is_allowed():
+ unsupported = ChatContextBuilder(
+ FakeRuntime(configured=ProviderModelInfo("model", supports_thinking=False))
+ )
+ try:
+ unsupported.prepare(_transcript(), system_prompt="")
+ except ChatValidationError as exc:
+ assert "Thinking" in str(exc) or "thinking" in str(exc)
+ else:
+ raise AssertionError("Known unsupported reasoning was accepted")
+
+ unknown = ChatContextBuilder(
+ FakeRuntime(configured=ProviderModelInfo("model", supports_thinking=None))
+ )
+ assert unknown.prepare(
+ _transcript(), system_prompt=""
+ ).routed.reasoning.requests_reasoning
+
+
+def test_compaction_disables_reasoning_for_known_non_reasoning_model():
+ routed = ChatContextBuilder(
+ FakeRuntime(
+ configured=ProviderModelInfo(
+ "model",
+ supports_thinking=False,
+ max_output_tokens=20_000,
+ )
+ )
+ ).prepare_summary(
+ model_ref="groq/model",
+ source="Summarize this conversation.",
+ output_tokens=4_096,
+ )
+
+ assert routed.reasoning.control is ReasoningControl.OFF
+ assert routed.request.max_tokens == 4_096
+
+
+def test_unknown_context_disables_auto_compaction_without_inventing_a_limit():
+ builder = ChatContextBuilder(
+ FakeRuntime(configured=ProviderModelInfo("model", context_window_tokens=None))
+ )
+ estimate = builder.prepare(_transcript(), system_prompt="").estimate
+
+ assert estimate.context_window_tokens is None
+ assert estimate.usage_ratio is None
+ assert estimate.should_auto_compact is False
+
+
+def test_known_context_reserves_input_when_output_cap_is_unknown():
+ builder = ChatContextBuilder(
+ FakeRuntime(
+ configured=ProviderModelInfo(
+ "model",
+ context_window_tokens=16_384,
+ max_output_tokens=None,
+ )
+ )
+ )
+
+ prepared = builder.prepare(
+ _transcript(reasoning=ChatReasoning.OFF),
+ system_prompt="",
+ draft="hello",
+ )
+
+ assert prepared.routed.request.max_tokens == 15_360
+ assert prepared.estimate.usable_input_tokens == 1_024
+
+
+def test_existing_compaction_replaces_only_covered_context():
+ runtime = FakeRuntime(
+ configured=ProviderModelInfo("model", context_window_tokens=100_000)
+ )
+ transcript = _transcript(
+ reasoning=ChatReasoning.OFF,
+ compaction=ChatCompaction(
+ session_id="session",
+ covered_through_sequence=1,
+ summary="durable summary",
+ estimated_tokens=10,
+ requested_model="groq/model",
+ actual_model="groq/model",
+ updated_at=2,
+ ),
+ )
+ request = (
+ ChatContextBuilder(runtime)
+ .prepare(
+ transcript,
+ system_prompt="",
+ draft="new message",
+ )
+ .routed.request
+ )
+
+ assert len(request.messages) == 2
+ assert "durable summary" in str(request.messages[0].content)
+ assert request.messages[1].content == "new message"
diff --git a/tests/application/test_chat_service.py b/tests/application/test_chat_service.py
new file mode 100644
index 00000000..9cf19dc0
--- /dev/null
+++ b/tests/application/test_chat_service.py
@@ -0,0 +1,1525 @@
+import asyncio
+import sqlite3
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import pytest
+
+from free_claude_code.application.chat import (
+ ChatConflictError,
+ ChatNotFoundError,
+ ChatService,
+ ChatUnavailableError,
+ GenerationStatus,
+)
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.application.ports import ProviderPort, RequestRuntimeLease
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic import MessagesRequest
+from free_claude_code.core.anthropic.streaming import format_sse_event
+from free_claude_code.core.openai_responses import OpenAIResponsesRequest
+from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.runtime.chat_sqlite import SQLiteChatStore
+
+
+class FakeChatProvider:
+ def __init__(
+ self,
+ *,
+ block_after_delta: bool = False,
+ truncate_summary: bool = False,
+ ) -> None:
+ self.block_after_delta = block_after_delta
+ self.truncate_summary = truncate_summary
+ self.started = asyncio.Event()
+ self.closed = 0
+ self.requests: list[MessagesRequest] = []
+
+ def preflight_messages(
+ self,
+ request: MessagesRequest,
+ *,
+ reasoning: ReasoningPolicy,
+ ) -> None:
+ del reasoning
+ self.requests.append(request)
+
+ def preflight_responses(
+ self,
+ request: OpenAIResponsesRequest,
+ *,
+ reasoning: ReasoningPolicy,
+ ) -> None:
+ raise AssertionError((request, reasoning))
+
+ async def stream_messages(
+ self,
+ request: MessagesRequest,
+ *,
+ input_tokens: int,
+ request_id: str,
+ response_model: str,
+ reasoning: ReasoningPolicy,
+ ) -> AsyncIterator[str]:
+ del input_tokens, request_id, response_model, reasoning
+ text = "summary" if str(request.system).startswith("Summarize") else "answer"
+ frames = [
+ format_sse_event(
+ "message_start",
+ {"type": "message_start", "message": {"content": []}},
+ ),
+ format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "thinking", "thinking": ""},
+ },
+ ),
+ format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "thinking_delta", "thinking": "thought"},
+ },
+ ),
+ format_sse_event(
+ "content_block_stop", {"type": "content_block_stop", "index": 0}
+ ),
+ format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 1,
+ "content_block": {"type": "text", "text": ""},
+ },
+ ),
+ format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 1,
+ "delta": {"type": "text_delta", "text": text},
+ },
+ ),
+ ]
+ try:
+ wire = "".join(frames)
+ midpoint = len(wire) // 2
+ yield wire[:midpoint]
+ yield wire[midpoint:]
+ self.started.set()
+ if self.truncate_summary and text == "summary":
+ return
+ if self.block_after_delta:
+ await asyncio.Event().wait()
+ yield format_sse_event(
+ "content_block_stop", {"type": "content_block_stop", "index": 1}
+ )
+ yield format_sse_event(
+ "message_delta",
+ {"type": "message_delta", "delta": {"stop_reason": "end_turn"}},
+ )
+ yield format_sse_event("message_stop", {"type": "message_stop"})
+ finally:
+ self.closed += 1
+
+ async def stream_responses(
+ self,
+ request: OpenAIResponsesRequest,
+ *,
+ input_tokens: int,
+ request_id: str,
+ response_model: str,
+ reasoning: ReasoningPolicy,
+ ) -> AsyncIterator[str]:
+ raise AssertionError(
+ (request, input_tokens, request_id, response_model, reasoning)
+ )
+ yield ""
+
+
+class BackpressuredCompletionProvider(FakeChatProvider):
+ async def stream_messages(
+ self,
+ request: MessagesRequest,
+ *,
+ input_tokens: int,
+ request_id: str,
+ response_model: str,
+ reasoning: ReasoningPolicy,
+ ) -> AsyncIterator[str]:
+ del request, input_tokens, request_id, response_model, reasoning
+ yield format_sse_event(
+ "message_start",
+ {"type": "message_start", "message": {"content": []}},
+ )
+ yield format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "text", "text": ""},
+ },
+ )
+ for _ in range(125):
+ yield format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "text_delta", "text": "x"},
+ },
+ )
+ yield format_sse_event(
+ "content_block_stop", {"type": "content_block_stop", "index": 0}
+ )
+ yield format_sse_event(
+ "message_delta",
+ {"type": "message_delta", "delta": {"stop_reason": "end_turn"}},
+ )
+ yield format_sse_event("message_stop", {"type": "message_stop"})
+
+
+class FakeLease:
+ def __init__(
+ self,
+ settings: Settings,
+ provider: FakeChatProvider,
+ model_infos: tuple[ProviderModelInfo, ...],
+ ) -> None:
+ self._settings = settings
+ self._provider = provider
+ self.model_infos = model_infos
+ self.released = 0
+
+ @property
+ def generation_id(self) -> int:
+ return 1
+
+ @property
+ def settings(self) -> Settings:
+ return self._settings
+
+ def is_provider_cached(self, provider_id: str) -> bool:
+ return provider_id == "groq"
+
+ def resolve_provider(self, provider_id: str) -> ProviderPort:
+ assert provider_id == "groq"
+ return self._provider
+
+ async def release(self) -> None:
+ self.released += 1
+
+
+class FakeRuntime:
+ def __init__(
+ self,
+ provider: FakeChatProvider,
+ *,
+ context_window_tokens: int = 100_000,
+ ) -> None:
+ self.settings = Settings().model_copy(
+ update={
+ "model": "groq/model",
+ "model_fallbacks": None,
+ "provider_progress_timeout": 5.0,
+ }
+ )
+ self.provider = provider
+ self.context_window_tokens = context_window_tokens
+ self.leases: list[FakeLease] = []
+
+ async def acquire(
+ self, *, include_model_infos: bool = False
+ ) -> RequestRuntimeLease:
+ lease = FakeLease(
+ self.settings,
+ self.provider,
+ (
+ ProviderModelInfo(
+ "groq/model",
+ supports_thinking=True,
+ context_window_tokens=self.context_window_tokens,
+ max_output_tokens=20_000,
+ ),
+ )
+ if include_model_infos
+ else (),
+ )
+ self.leases.append(lease)
+ return lease
+
+ def current_settings(self) -> Settings:
+ return self.settings
+
+ def cached_model_info(
+ self, provider_id: str, model_id: str
+ ) -> ProviderModelInfo | None:
+ if (provider_id, model_id) == ("groq", "model"):
+ return ProviderModelInfo(
+ "model",
+ supports_thinking=True,
+ context_window_tokens=self.context_window_tokens,
+ max_output_tokens=20_000,
+ )
+ return None
+
+ def cached_prefixed_model_infos(self) -> tuple[ProviderModelInfo, ...]:
+ return ()
+
+
+async def _service(
+ tmp_path: Path, provider: FakeChatProvider
+) -> tuple[ChatService, FakeRuntime, SQLiteChatStore]:
+ runtime = FakeRuntime(provider)
+ store = SQLiteChatStore(tmp_path / "chat.db", tmp_path / "chat.lock")
+ service = ChatService(runtime, store)
+ await service.start()
+ return service, runtime, store
+
+
+async def _drain(stream) -> list[str]:
+ events = [event.event async for event in stream]
+ await stream.aclose()
+ return events
+
+
+async def test_send_streams_and_persists_interleaved_segments(tmp_path: Path):
+ provider = FakeChatProvider()
+ service, runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="b21677f0-aa9a-4acb-b197-64d3dbd56536",
+ text="hello",
+ )
+ events = await _drain(stream)
+
+ transcript = await store.get_transcript(session.id)
+ generation = transcript.turns[0].generation
+ assert events[-1] == "turn.completed"
+ assert [segment.text for segment in generation.segments] == [
+ "thought",
+ "answer",
+ ]
+ assert generation.actual_model == "groq/model"
+ assert runtime.leases[0].released == 1
+ assert provider.closed == 1
+ finally:
+ await service.close()
+
+
+async def test_completion_persistence_exhaustion_never_downgrades_to_failed(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ statuses: list[GenerationStatus] = []
+ original_finish_generation = store.finish_generation
+
+ async def unavailable_completion(*args, **kwargs):
+ status = kwargs["status"]
+ statuses.append(status)
+ if len(statuses) <= 2:
+ raise ChatUnavailableError("Chat storage is temporarily unavailable.")
+ return await original_finish_generation(*args, **kwargs)
+
+ monkeypatch.setattr(store, "finish_generation", unavailable_completion)
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="f69c7c4d-9a46-40f0-b6ad-7f288a2c2dd7",
+ text="finish successfully",
+ )
+
+ assert (await _drain(stream))[-1] == "turn.failed"
+ assert statuses == [GenerationStatus.COMPLETED, GenerationStatus.COMPLETED]
+ generation = (await store.get_transcript(session.id)).turns[0].generation
+ assert generation.status is GenerationStatus.RUNNING
+ assert service.availability() == (
+ False,
+ "Chat storage became unavailable. Restart FCC to repair Chat Sessions.",
+ )
+ finally:
+ await service.close()
+
+
+async def test_regeneration_retries_an_ambiguous_terminal_commit(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ initial = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="e8476211-c6a1-45c4-a463-b7d92bfcc7d8",
+ text="answer once",
+ )
+ assert (await _drain(initial))[-1] == "turn.completed"
+ before = await store.get_transcript(session.id)
+ original_id = before.turns[0].generation.id
+
+ attempts = 0
+ original_finish_regeneration = store.finish_regeneration
+
+ async def ambiguous_finish_regeneration(*args, **kwargs):
+ nonlocal attempts
+ attempts += 1
+ result = await original_finish_regeneration(*args, **kwargs)
+ if attempts == 1:
+ raise ChatUnavailableError("Chat commit result was unavailable.")
+ return result
+
+ monkeypatch.setattr(
+ store,
+ "finish_regeneration",
+ ambiguous_finish_regeneration,
+ )
+ replacement = await service.regenerate(
+ session.id,
+ expected_revision=before.session.revision,
+ operation_id="8a99c4a9-e4f5-4ebd-a8c9-982a9227a557",
+ )
+
+ assert (await _drain(replacement))[-1] == "turn.completed"
+ after = await store.get_transcript(session.id)
+ assert attempts == 2
+ assert after.turns[0].generation.id != original_id
+ assert after.turns[0].generation.status is GenerationStatus.COMPLETED
+ assert service.availability()[0] is True
+ finally:
+ await service.close()
+
+
+async def test_stopped_regeneration_retries_an_ambiguous_discard(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ initial = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="14e14878-842d-425a-952c-4e9f105760c0",
+ text="keep the original answer",
+ )
+ assert (await _drain(initial))[-1] == "turn.completed"
+ before = await store.get_transcript(session.id)
+ original_generation = before.turns[0].generation
+
+ discard_attempts = 0
+ segment_writes = 0
+ original_discard_generation = store.discard_generation
+ original_replace_segments = store.replace_generation_segments
+
+ async def ambiguous_discard(*args, **kwargs):
+ nonlocal discard_attempts
+ discard_attempts += 1
+ await original_discard_generation(*args, **kwargs)
+ if discard_attempts == 1:
+ raise ChatUnavailableError("Chat commit result was unavailable.")
+
+ async def observed_replace_segments(*args, **kwargs):
+ nonlocal segment_writes
+ segment_writes += 1
+ return await original_replace_segments(*args, **kwargs)
+
+ monkeypatch.setattr(store, "discard_generation", ambiguous_discard)
+ monkeypatch.setattr(
+ store, "replace_generation_segments", observed_replace_segments
+ )
+ provider.started.clear()
+ provider.block_after_delta = True
+ replacement = await service.regenerate(
+ session.id,
+ expected_revision=before.session.revision,
+ operation_id="19cbb991-38ff-4cd2-a20e-f94783f78003",
+ )
+ await asyncio.wait_for(provider.started.wait(), timeout=1)
+ writes_before_stop = segment_writes
+
+ assert await service.stop(
+ session.id,
+ operation_id="19cbb991-38ff-4cd2-a20e-f94783f78003",
+ )
+ assert (await _drain(replacement))[-1] == "turn.stopped"
+
+ after = await store.get_transcript(session.id)
+ assert discard_attempts == 2
+ assert segment_writes == writes_before_stop
+ assert after.turns[0].generation == original_generation
+ assert service.availability()[0] is True
+ finally:
+ await service.close()
+
+
+async def test_closing_initiating_stream_cancels_and_persists_partial_answer(
+ tmp_path: Path,
+):
+ provider = FakeChatProvider(block_after_delta=True)
+ service, runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="9781df8c-aa92-422e-97d9-e9ea7f542b89",
+ text="hello",
+ )
+ collector = asyncio.create_task(_drain(stream))
+ await asyncio.wait_for(provider.started.wait(), timeout=1)
+ await stream.aclose()
+ events = await asyncio.wait_for(collector, timeout=1)
+
+ generation = (await store.get_transcript(session.id)).turns[0].generation
+ assert events[-1] == "turn.stopped"
+ assert generation.status is GenerationStatus.STOPPED
+ assert generation.segments[-1].text == "answer"
+ assert runtime.leases[0].released == 1
+ assert provider.closed == 1
+ finally:
+ await service.close()
+
+
+async def test_stop_retries_transient_terminal_persistence_failure(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider(block_after_delta=True)
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ operation_id = "3a1c071f-f558-4be3-a072-f9af230352ec"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="survive one storage failure",
+ )
+ await asyncio.wait_for(provider.started.wait(), timeout=1)
+
+ attempts = 0
+ original_finish_generation = store.finish_generation
+
+ async def flaky_finish_generation(*args, **kwargs):
+ nonlocal attempts
+ attempts += 1
+ if attempts == 1:
+ raise ChatUnavailableError("Chat storage is temporarily unavailable.")
+ return await original_finish_generation(*args, **kwargs)
+
+ monkeypatch.setattr(store, "finish_generation", flaky_finish_generation)
+
+ assert await service.stop(session.id, operation_id=operation_id) is True
+ assert (await _drain(stream))[-1] == "turn.stopped"
+
+ transcript = await store.get_transcript(session.id)
+ assert attempts == 2
+ assert transcript.turns[-1].generation.status is GenerationStatus.STOPPED
+ assert (await service.get_detail(session.id)).active_operation is False
+
+ provider.block_after_delta = False
+ replacement = await service.send(
+ session.id,
+ expected_revision=transcript.session.revision,
+ operation_id="f5190fdb-ce16-402d-a5a2-1633ba0cae55",
+ text="keep going",
+ )
+ assert (await _drain(replacement))[-1] == "turn.completed"
+ finally:
+ await service.close()
+
+
+async def test_stop_retries_transient_terminal_segment_flush(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider(block_after_delta=True)
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ operation_id = "242841f6-d826-48b5-9ed7-bf073b17840e"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="preserve the final partial segment",
+ )
+ await asyncio.wait_for(provider.started.wait(), timeout=1)
+
+ attempts = 0
+ original_replace_segments = store.replace_generation_segments
+
+ async def flaky_replace_segments(*args, **kwargs):
+ nonlocal attempts
+ attempts += 1
+ if attempts == 1:
+ raise ChatUnavailableError("Chat storage is temporarily unavailable.")
+ return await original_replace_segments(*args, **kwargs)
+
+ monkeypatch.setattr(
+ store, "replace_generation_segments", flaky_replace_segments
+ )
+
+ assert await service.stop(session.id, operation_id=operation_id) is True
+ assert (await _drain(stream))[-1] == "turn.stopped"
+
+ generation = (await store.get_transcript(session.id)).turns[-1].generation
+ assert attempts == 2
+ assert generation.status is GenerationStatus.STOPPED
+ assert generation.segments[-1].text == "answer"
+ finally:
+ await service.close()
+
+
+async def test_terminal_persistence_failure_disables_chat_instead_of_lying(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider(block_after_delta=True)
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ operation_id = "f744570e-0ec6-4f70-b74d-19de6bc60547"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="surface a persistent storage failure",
+ )
+ await asyncio.wait_for(provider.started.wait(), timeout=1)
+
+ attempts = 0
+
+ async def unavailable_finish_generation(*args, **kwargs):
+ nonlocal attempts
+ attempts += 1
+ raise ChatUnavailableError("Chat storage is unavailable.")
+
+ monkeypatch.setattr(
+ store,
+ "finish_generation",
+ unavailable_finish_generation,
+ )
+
+ assert await service.stop(session.id, operation_id=operation_id) is True
+ assert (await _drain(stream))[-1] == "turn.failed"
+ assert attempts == 2
+
+ available, message = service.availability()
+ assert available is False
+ assert message == (
+ "Chat storage became unavailable. Restart FCC to repair Chat Sessions."
+ )
+ with pytest.raises(ChatUnavailableError, match="Restart FCC"):
+ await service.get_detail(session.id)
+
+ generation = (await store.get_transcript(session.id)).turns[-1].generation
+ assert generation.status is GenerationStatus.RUNNING
+ finally:
+ await service.close()
+
+
+async def test_immediate_stop_before_operation_task_starts_releases_owner(
+ tmp_path: Path,
+):
+ provider = FakeChatProvider()
+ service, _runtime, _store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ operation_id = "2029b65e-f4d9-4b80-8c6a-563a32fb8b8f"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="stop before start",
+ )
+
+ assert await service.stop(session.id, operation_id=operation_id) is True
+ assert await _drain(stream) == []
+
+ replacement = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="4b50506e-92bf-46ba-aa35-333dc0946e14",
+ text="still usable",
+ )
+ assert (await _drain(replacement))[-1] == "turn.completed"
+ finally:
+ await service.close()
+
+
+async def test_ambiguous_generation_start_adopts_the_committed_owner(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ original_begin_send = store.begin_send
+
+ async def ambiguous_begin_send(*args, **kwargs):
+ await original_begin_send(*args, **kwargs)
+ raise ChatUnavailableError("Chat commit result was unavailable.")
+
+ monkeypatch.setattr(store, "begin_send", ambiguous_begin_send)
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="cc47acc3-d7c2-46d0-a1b6-fe2acda191e4",
+ text="recover the committed start",
+ )
+
+ assert (await _drain(stream))[-1] == "turn.completed"
+ generation = (await store.get_transcript(session.id)).turns[0].generation
+ assert generation.status is GenerationStatus.COMPLETED
+ assert (
+ await service.stop(
+ session.id,
+ operation_id="cc47acc3-d7c2-46d0-a1b6-fe2acda191e4",
+ )
+ is False
+ )
+ assert service.availability()[0] is True
+ finally:
+ await service.close()
+
+
+async def test_disconnect_cannot_interrupt_failure_terminalization(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ release_flush = asyncio.Event()
+ try:
+
+ async def failing_stream(*args, **kwargs):
+ del args, kwargs
+ yield "".join(
+ (
+ format_sse_event(
+ "message_start",
+ {"type": "message_start", "message": {"content": []}},
+ ),
+ format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "text", "text": ""},
+ },
+ ),
+ format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "text_delta", "text": "partial"},
+ },
+ ),
+ format_sse_event(
+ "error",
+ {
+ "type": "error",
+ "error": {"message": "provider failed"},
+ },
+ ),
+ )
+ )
+
+ monkeypatch.setattr(provider, "stream_messages", failing_stream)
+ entered_flush = asyncio.Event()
+ original_replace_segments = store.replace_generation_segments
+
+ async def blocked_replace_segments(generation_id, segments):
+ entered_flush.set()
+ await release_flush.wait()
+ await original_replace_segments(generation_id, segments)
+
+ monkeypatch.setattr(
+ store,
+ "replace_generation_segments",
+ blocked_replace_segments,
+ )
+ session = await service.create_session()
+ operation_id = "63523531-024d-47f2-a0ce-ff7104d4e3af"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="fail before disconnect",
+ )
+ await asyncio.wait_for(entered_flush.wait(), timeout=1)
+
+ close_task = asyncio.create_task(stream.aclose())
+ await asyncio.sleep(0.05)
+ assert not close_task.done()
+ release_flush.set()
+ await asyncio.wait_for(close_task, timeout=1)
+
+ assert (await _drain(stream))[-1] == "turn.failed"
+ generation = (await store.get_transcript(session.id)).turns[0].generation
+ assert generation.status is GenerationStatus.FAILED
+ assert await service.stop(session.id, operation_id=operation_id) is False
+ assert service.availability()[0] is True
+ finally:
+ release_flush.set()
+ await service.close()
+
+
+async def test_second_operation_on_same_session_is_rejected(tmp_path: Path):
+ provider = FakeChatProvider(block_after_delta=True)
+ service, _runtime, _store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ first = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="3e363fbc-25ee-414e-a954-02d11990497f",
+ text="first",
+ )
+ await asyncio.wait_for(provider.started.wait(), timeout=1)
+ running = await service.get_session(session.id)
+ with pytest.raises(ChatConflictError, match="active operation"):
+ await service.send(
+ session.id,
+ expected_revision=running.revision,
+ operation_id="223ad9ac-e830-42ec-b73d-b1cbd81511c4",
+ text="second",
+ )
+ await first.aclose()
+ finally:
+ await service.close()
+
+
+async def test_delete_validates_stale_revision_before_cancelling_active_send(
+ tmp_path: Path,
+):
+ provider = FakeChatProvider(block_after_delta=True)
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ operation_id = "3b4390e2-bbd0-499a-94c5-d7813b1d5f75"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="keep running",
+ )
+ await asyncio.wait_for(provider.started.wait(), timeout=1)
+ assert (await service.get_session(session.id)).revision > session.revision
+
+ with pytest.raises(ChatConflictError, match="another tab"):
+ await service.delete_session(
+ session.id,
+ expected_revision=session.revision,
+ )
+
+ assert await service.stop(session.id, operation_id=operation_id) is True
+ generation = (await store.get_transcript(session.id)).turns[0].generation
+ assert generation.status is GenerationStatus.STOPPED
+ await stream.aclose()
+ finally:
+ await service.close()
+
+
+async def test_delete_active_send_finishes_generation_before_removing_session(
+ tmp_path: Path,
+):
+ provider = FakeChatProvider(block_after_delta=True)
+ service, _runtime, _store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="0162e7e5-aabd-4ffb-ae50-ed864825ec71",
+ text="delete me",
+ )
+ await asyncio.wait_for(provider.started.wait(), timeout=1)
+ running = await service.get_session(session.id)
+
+ await service.delete_session(session.id, expected_revision=running.revision)
+
+ with pytest.raises(ChatNotFoundError):
+ await service.get_session(session.id)
+ await stream.aclose()
+ finally:
+ await service.close()
+
+
+async def test_cancellation_waits_for_generation_start_commit_before_cleanup(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider(block_after_delta=True)
+ service, _runtime, store = await _service(tmp_path, provider)
+ blocker: sqlite3.Connection | None = None
+ try:
+ session = await service.create_session()
+ initial_stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="7f4c7a3f-c06e-42c3-9887-f748dc5aa518",
+ text="partial answer",
+ )
+ await asyncio.wait_for(provider.started.wait(), timeout=5)
+ assert await service.stop(
+ session.id,
+ operation_id="7f4c7a3f-c06e-42c3-9887-f748dc5aa518",
+ )
+ await initial_stream.aclose()
+
+ entered = asyncio.Event()
+ original_begin_retry = store.begin_retry
+
+ async def observed_begin_retry(*args, **kwargs):
+ entered.set()
+ return await original_begin_retry(*args, **kwargs)
+
+ monkeypatch.setattr(store, "begin_retry", observed_begin_retry)
+ blocker = sqlite3.connect(tmp_path / "chat.db", isolation_level=None)
+ blocker.execute("PRAGMA journal_mode = WAL")
+ blocker.execute("BEGIN IMMEDIATE")
+
+ current = await service.get_session(session.id)
+ retry_stream = await service.retry(
+ session.id,
+ expected_revision=current.revision,
+ operation_id="38dcb3e5-04b7-4ecf-bc8b-7c72550839b0",
+ )
+ await asyncio.wait_for(entered.wait(), timeout=1)
+ await asyncio.sleep(0.05)
+
+ close_task = asyncio.create_task(retry_stream.aclose())
+ await asyncio.sleep(0.05)
+ waited_for_commit = not close_task.done()
+ blocker.commit()
+ blocker.close()
+ blocker = None
+ await asyncio.wait_for(close_task, timeout=1)
+
+ generation = (await store.get_transcript(session.id)).turns[-1].generation
+ assert waited_for_commit
+ assert generation.status is GenerationStatus.STOPPED
+ finally:
+ if blocker is not None:
+ blocker.rollback()
+ blocker.close()
+ await service.close()
+
+
+async def test_repeated_cancellation_waits_for_terminal_cleanup(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider(block_after_delta=True)
+ service, _runtime, store = await _service(tmp_path, provider)
+ blocker: sqlite3.Connection | None = None
+ try:
+ session = await service.create_session()
+ operation_id = "f02c0da7-1ec9-4433-bef3-dc760753e451"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="preserve partial output",
+ )
+ await asyncio.wait_for(provider.started.wait(), timeout=1)
+
+ entered_cleanup = asyncio.Event()
+ original_replace_segments = store.replace_generation_segments
+
+ async def observed_replace_segments(generation_id, segments):
+ entered_cleanup.set()
+ await original_replace_segments(generation_id, segments)
+
+ monkeypatch.setattr(
+ store,
+ "replace_generation_segments",
+ observed_replace_segments,
+ )
+ blocker = sqlite3.connect(tmp_path / "chat.db", isolation_level=None)
+ blocker.execute("PRAGMA journal_mode = WAL")
+ blocker.execute("BEGIN IMMEDIATE")
+
+ close_task = asyncio.create_task(stream.aclose())
+ await asyncio.wait_for(entered_cleanup.wait(), timeout=1)
+ stop_task = asyncio.create_task(
+ service.stop(session.id, operation_id=operation_id)
+ )
+ await asyncio.sleep(0.05)
+
+ assert not close_task.done()
+ assert not stop_task.done()
+ blocker.commit()
+ blocker.close()
+ blocker = None
+ await asyncio.wait_for(close_task, timeout=1)
+ assert await asyncio.wait_for(stop_task, timeout=1) is True
+
+ generation = (await store.get_transcript(session.id)).turns[0].generation
+ assert generation.status is GenerationStatus.STOPPED
+ assert await service.stop(session.id, operation_id=operation_id) is False
+ finally:
+ if blocker is not None:
+ blocker.rollback()
+ blocker.close()
+ await service.close()
+
+
+async def test_stop_at_generation_commit_preserves_completed_result(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ entered_commit = asyncio.Event()
+ release_commit = asyncio.Event()
+ original_finish_generation = store.finish_generation
+
+ async def observed_finish_generation(*args, **kwargs):
+ entered_commit.set()
+ await release_commit.wait()
+ return await original_finish_generation(*args, **kwargs)
+
+ monkeypatch.setattr(store, "finish_generation", observed_finish_generation)
+ session = await service.create_session()
+ operation_id = "03ba5dce-bd47-452c-a878-229d4df65944"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="finish this answer",
+ )
+ await asyncio.wait_for(entered_commit.wait(), timeout=1)
+
+ stop_task = asyncio.create_task(
+ service.stop(session.id, operation_id=operation_id)
+ )
+ await asyncio.sleep(0.05)
+ assert not stop_task.done()
+ release_commit.set()
+
+ assert await asyncio.wait_for(stop_task, timeout=1) is True
+ events = await _drain(stream)
+ generation = (await store.get_transcript(session.id)).turns[0].generation
+ assert events[-1] == "turn.completed"
+ assert generation.status is GenerationStatus.COMPLETED
+ finally:
+ await service.close()
+
+
+async def test_detail_snapshot_keeps_operation_owner_visible_through_completion(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ release_commit = asyncio.Event()
+ release_snapshot = asyncio.Event()
+ try:
+ entered_commit = asyncio.Event()
+ committed = asyncio.Event()
+ original_finish_generation = store.finish_generation
+
+ async def observed_finish_generation(*args, **kwargs):
+ entered_commit.set()
+ await release_commit.wait()
+ result = await original_finish_generation(*args, **kwargs)
+ committed.set()
+ return result
+
+ monkeypatch.setattr(store, "finish_generation", observed_finish_generation)
+ session = await service.create_session()
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="9e34cdcb-3d56-44f2-8921-a5d43cb0ed20",
+ text="complete while detail loads",
+ )
+ await asyncio.wait_for(entered_commit.wait(), timeout=1)
+
+ entered_snapshot = asyncio.Event()
+ original_get_transcript = store.get_transcript
+
+ async def observed_get_transcript(session_id: str):
+ entered_snapshot.set()
+ await release_snapshot.wait()
+ return await original_get_transcript(session_id)
+
+ monkeypatch.setattr(store, "get_transcript", observed_get_transcript)
+ detail_task = asyncio.create_task(service.get_detail(session.id))
+ await asyncio.wait_for(entered_snapshot.wait(), timeout=1)
+
+ release_commit.set()
+ await asyncio.wait_for(committed.wait(), timeout=1)
+ release_snapshot.set()
+ detail = await asyncio.wait_for(detail_task, timeout=1)
+ await _drain(stream)
+
+ assert detail.active_operation is True
+ assert detail.session.revision > session.revision
+ finally:
+ release_commit.set()
+ release_snapshot.set()
+ await service.close()
+
+
+async def test_cancellation_while_release_waits_cannot_strand_operation_owner(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ release_commit = asyncio.Event()
+ release_snapshot = asyncio.Event()
+ try:
+ entered_commit = asyncio.Event()
+ original_finish_generation = store.finish_generation
+
+ async def observed_finish_generation(*args, **kwargs):
+ entered_commit.set()
+ await release_commit.wait()
+ return await original_finish_generation(*args, **kwargs)
+
+ monkeypatch.setattr(store, "finish_generation", observed_finish_generation)
+ session = await service.create_session()
+ operation_id = "7f4dcfd1-bc69-4df1-9737-f434d357133a"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="finish while detail owns the lifecycle lock",
+ )
+ await asyncio.wait_for(entered_commit.wait(), timeout=1)
+
+ entered_snapshot = asyncio.Event()
+ original_get_transcript = store.get_transcript
+
+ async def observed_get_transcript(session_id: str):
+ entered_snapshot.set()
+ await release_snapshot.wait()
+ return await original_get_transcript(session_id)
+
+ monkeypatch.setattr(store, "get_transcript", observed_get_transcript)
+ detail_task = asyncio.create_task(service.get_detail(session.id))
+ await asyncio.wait_for(entered_snapshot.wait(), timeout=1)
+
+ release_commit.set()
+ events = stream.__aiter__()
+ while (
+ await asyncio.wait_for(anext(events), timeout=1)
+ ).event != "turn.completed":
+ pass
+
+ close_task = asyncio.create_task(stream.aclose())
+ await asyncio.sleep(0)
+ release_snapshot.set()
+ await asyncio.wait_for(detail_task, timeout=1)
+ await asyncio.wait_for(close_task, timeout=1)
+
+ current = await service.get_session(session.id)
+ next_stream = await service.send(
+ session.id,
+ expected_revision=current.revision,
+ operation_id="87f5dd83-ee78-48d8-82f5-b65cd91034fc",
+ text="the next operation can start",
+ )
+ await _drain(next_stream)
+ finally:
+ release_commit.set()
+ release_snapshot.set()
+ await service.close()
+
+
+async def test_disconnect_after_durable_completion_cannot_downgrade_status(
+ tmp_path: Path,
+):
+ provider = BackpressuredCompletionProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="80354cee-d3b1-4760-963f-9cc7a1558ffc",
+ text="fill the event queue",
+ )
+
+ async def wait_for_completion() -> None:
+ while True:
+ transcript = await store.get_transcript(session.id)
+ if (
+ transcript.turns
+ and transcript.turns[0].generation.status
+ is GenerationStatus.COMPLETED
+ ):
+ return
+ await asyncio.sleep(0)
+
+ await asyncio.wait_for(wait_for_completion(), timeout=1)
+ await stream.aclose()
+
+ generation = (await store.get_transcript(session.id)).turns[0].generation
+ assert generation.status is GenerationStatus.COMPLETED
+ assert generation.stop_reason == "end_turn"
+ finally:
+ await service.close()
+
+
+async def test_stop_during_compaction_commit_waits_and_reports_completion(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ blocker: sqlite3.Connection | None = None
+ try:
+ session = await service.create_session()
+ for index, operation_id in enumerate(
+ (
+ "08ea4712-3732-4626-9590-ac78cd273982",
+ "35d15a22-88e4-476f-aec2-9c0cdfb5cb87",
+ )
+ ):
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text=f"turn {index}",
+ )
+ await _drain(stream)
+ session = await service.get_session(session.id)
+
+ entered_commit = asyncio.Event()
+ original_upsert_compaction = store.upsert_compaction
+
+ async def observed_upsert_compaction(*args, **kwargs):
+ entered_commit.set()
+ return await original_upsert_compaction(*args, **kwargs)
+
+ monkeypatch.setattr(store, "upsert_compaction", observed_upsert_compaction)
+ blocker = sqlite3.connect(tmp_path / "chat.db", isolation_level=None)
+ blocker.execute("PRAGMA journal_mode = WAL")
+ blocker.execute("BEGIN IMMEDIATE")
+
+ operation_id = "b15f0721-acd3-482f-812d-28d2d3cc568b"
+ compact = await service.compact(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ )
+ await asyncio.wait_for(entered_commit.wait(), timeout=1)
+ stop_task = asyncio.create_task(
+ service.stop(session.id, operation_id=operation_id)
+ )
+ await asyncio.sleep(0.05)
+ assert not stop_task.done()
+
+ blocker.commit()
+ blocker.close()
+ blocker = None
+ assert await asyncio.wait_for(stop_task, timeout=1) is True
+ events = await _drain(compact)
+
+ transcript = await store.get_transcript(session.id)
+ assert events[-1] == "compaction.completed"
+ assert transcript.compaction is not None
+ assert transcript.compaction.covered_through_sequence == 1
+ finally:
+ if blocker is not None:
+ blocker.rollback()
+ blocker.close()
+ await service.close()
+
+
+async def test_compaction_retries_an_ambiguous_commit_once(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ for operation_id, text in (
+ ("110ce497-5d5f-4659-b2c7-7ae4bf362900", "first"),
+ ("64de0c33-c956-4ac2-b172-9f9fc5caf13b", "second"),
+ ):
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text=text,
+ )
+ assert (await _drain(stream))[-1] == "turn.completed"
+ session = await service.get_session(session.id)
+
+ revision_before_compaction = session.revision
+ attempts = 0
+ original_upsert_compaction = store.upsert_compaction
+
+ async def ambiguous_upsert_compaction(*args, **kwargs):
+ nonlocal attempts
+ attempts += 1
+ result = await original_upsert_compaction(*args, **kwargs)
+ if attempts == 1:
+ raise ChatUnavailableError("Chat commit result was unavailable.")
+ return result
+
+ monkeypatch.setattr(store, "upsert_compaction", ambiguous_upsert_compaction)
+ compact = await service.compact(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="861cba8a-fca4-47eb-84cb-de1a7059714c",
+ )
+
+ assert (await _drain(compact))[-1] == "compaction.completed"
+ transcript = await store.get_transcript(session.id)
+ assert attempts == 2
+ assert transcript.compaction is not None
+ assert transcript.session.revision == revision_before_compaction + 1
+ assert service.availability()[0] is True
+ finally:
+ await service.close()
+
+
+async def test_manual_compaction_keeps_full_transcript_and_adds_checkpoint(
+ tmp_path: Path,
+):
+ provider = FakeChatProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ first = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="e90f819b-a835-4c1f-80d7-6e7c17c429a7",
+ text="first",
+ )
+ await _drain(first)
+ session = await service.get_session(session.id)
+ second = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="8de64c2a-34c8-4b30-a880-37d3678c62de",
+ text="second",
+ )
+ await _drain(second)
+ session = await service.get_session(session.id)
+ compact = await service.compact(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="b5c9bc6f-3b74-4218-bac5-17b6813f443a",
+ )
+ events = await _drain(compact)
+
+ transcript = await store.get_transcript(session.id)
+ assert events[-1] == "compaction.completed"
+ assert len(transcript.turns) == 2
+ assert transcript.compaction is not None
+ assert transcript.compaction.covered_through_sequence == 1
+ assert transcript.compaction.summary == "summary"
+ finally:
+ await service.close()
+
+
+async def test_manual_compaction_rejects_incomplete_summary_stream(tmp_path: Path):
+ provider = FakeChatProvider(truncate_summary=True)
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ for operation_id, text in (
+ ("560c7a0f-c074-489b-8b90-e7e031577716", "first"),
+ ("d77427c1-8417-4ab5-a380-94860c778db8", "second"),
+ ):
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text=text,
+ )
+ await _drain(stream)
+ session = await service.get_session(session.id)
+
+ compact = await service.compact(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="8895d9ae-c896-4af2-be44-d6328e1da736",
+ )
+ events = await _drain(compact)
+
+ transcript = await store.get_transcript(session.id)
+ assert events[-1] == "compaction.failed"
+ assert transcript.compaction is None
+ finally:
+ await service.close()
+
+
+async def test_send_auto_compacts_without_removing_original_turns(tmp_path: Path):
+ provider = FakeChatProvider()
+ runtime = FakeRuntime(provider, context_window_tokens=40_000)
+ store = SQLiteChatStore(tmp_path / "chat.db", tmp_path / "chat.lock")
+ service = ChatService(runtime, store)
+ await service.start()
+ try:
+ session = await service.create_session()
+ operation_ids = (
+ "4e542b5b-8386-46d2-8643-67a523c216f0",
+ "86293f1e-2899-47b9-8590-27450fc00989",
+ "dd945983-b49c-4749-83b3-3051d3998bc2",
+ )
+ for operation_id in operation_ids:
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="token " * 5_000,
+ )
+ await _drain(stream)
+ session = await service.get_session(session.id)
+
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id="195faf19-ea0a-4633-ad81-a09734f5e17c",
+ text="token " * 5_000,
+ )
+ events = await _drain(stream)
+
+ transcript = await store.get_transcript(session.id)
+ assert "compaction.started" in events
+ assert "compaction.completed" in events
+ assert len(transcript.turns) == 4
+ assert transcript.compaction is not None
+ assert transcript.compaction.covered_through_sequence >= 1
+ finally:
+ await service.close()
+
+
+async def test_stop_during_auto_compaction_commit_keeps_checkpoint_without_new_turn(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ provider = FakeChatProvider()
+ runtime = FakeRuntime(provider, context_window_tokens=40_000)
+ store = SQLiteChatStore(tmp_path / "chat.db", tmp_path / "chat.lock")
+ service = ChatService(runtime, store)
+ await service.start()
+ blocker: sqlite3.Connection | None = None
+ try:
+ session = await service.create_session()
+ for operation_id in (
+ "d3bb405e-245f-4dbf-bbdd-b72508926367",
+ "d4fec5fe-a75a-4752-8c33-f51fd105774f",
+ "79cd9bd9-df33-4ed4-8a5c-5e34770a30f7",
+ ):
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="token " * 5_000,
+ )
+ await _drain(stream)
+ session = await service.get_session(session.id)
+
+ entered_commit = asyncio.Event()
+ original_upsert_compaction = store.upsert_compaction
+
+ async def observed_upsert_compaction(*args, **kwargs):
+ entered_commit.set()
+ return await original_upsert_compaction(*args, **kwargs)
+
+ monkeypatch.setattr(store, "upsert_compaction", observed_upsert_compaction)
+ blocker = sqlite3.connect(tmp_path / "chat.db", isolation_level=None)
+ blocker.execute("PRAGMA journal_mode = WAL")
+ blocker.execute("BEGIN IMMEDIATE")
+
+ operation_id = "443b12d9-8989-4bb5-a609-c9c2c0e2ecf5"
+ stream = await service.send(
+ session.id,
+ expected_revision=session.revision,
+ operation_id=operation_id,
+ text="token " * 5_000,
+ )
+ await asyncio.wait_for(entered_commit.wait(), timeout=1)
+ stop_task = asyncio.create_task(
+ service.stop(session.id, operation_id=operation_id)
+ )
+ await asyncio.sleep(0.05)
+ assert not stop_task.done()
+
+ blocker.commit()
+ blocker.close()
+ blocker = None
+ assert await asyncio.wait_for(stop_task, timeout=1) is True
+ events = await _drain(stream)
+
+ transcript = await store.get_transcript(session.id)
+ assert events[-2:] == ["compaction.completed", "turn.stopped"]
+ assert transcript.compaction is not None
+ assert len(transcript.turns) == 3
+ finally:
+ if blocker is not None:
+ blocker.rollback()
+ blocker.close()
+ await service.close()
+
+
+async def test_storage_start_failure_disables_only_chat(tmp_path: Path):
+ database_path = tmp_path / "chat.db"
+ database_path.mkdir()
+ store = SQLiteChatStore(database_path, tmp_path / "chat.lock")
+ service = ChatService(FakeRuntime(FakeChatProvider()), store)
+
+ await service.start()
+ try:
+ available, message = service.availability()
+ assert available is False
+ assert message == "Chat storage is unavailable."
+ with pytest.raises(ChatUnavailableError, match="storage is unavailable"):
+ await service.create_session()
+ finally:
+ await service.close()
diff --git a/tests/application/test_execution.py b/tests/application/test_execution.py
index 88c5aa90..e0288a13 100644
--- a/tests/application/test_execution.py
+++ b/tests/application/test_execution.py
@@ -384,6 +384,69 @@ def _executor_stream(
)
+async def test_candidate_observer_runs_once_before_committed_output() -> None:
+ provider = FakeProvider()
+ selected: list[str] = []
+ executor = ProviderExecutor(
+ lambda _provider_id: provider,
+ progress_timeout_seconds=1.0,
+ )
+
+ async def observe(target: ProviderModelTarget) -> None:
+ selected.append(target.provider_model_ref)
+
+ stream = executor.stream_messages(
+ _routed_request(),
+ raw_log_payload={},
+ request_id="req_candidate_observer",
+ candidate_selected=observe,
+ )
+
+ assert [chunk async for chunk in stream]
+ assert selected == ["provider/provider-model"]
+
+
+async def test_candidate_observer_records_only_successful_fallback() -> None:
+ primary = ControlledProvider([_execution_failure("overloaded")])
+ fallback = FakeProvider()
+ providers = {"provider": primary, "fallback": fallback}
+ selected: list[str] = []
+ executor = ProviderExecutor(
+ providers.__getitem__,
+ progress_timeout_seconds=1.0,
+ )
+ stream = executor.stream_messages(
+ _routed_request(_target("fallback", "model")),
+ raw_log_payload={},
+ request_id="req_candidate_fallback_observer",
+ candidate_selected=lambda target: selected.append(target.provider_model_ref),
+ )
+
+ assert [chunk async for chunk in stream]
+ assert selected == ["fallback/model"]
+
+
+async def test_candidate_observer_records_normal_empty_completion() -> None:
+ provider = ControlledProvider([])
+ selected: list[str] = []
+ executor = ProviderExecutor(
+ lambda _provider_id: provider,
+ progress_timeout_seconds=1.0,
+ )
+ stream = executor.stream_messages(
+ _routed_request(),
+ raw_log_payload={},
+ request_id="req_empty_candidate_observer",
+ candidate_selected=lambda target: selected.append(target.provider_model_ref),
+ )
+
+ assert [chunk async for chunk in stream] == []
+ assert selected == ["provider/provider-model"]
+
+
@pytest.mark.asyncio
async def test_executor_routes_native_responses_without_messages_conversion() -> None:
provider = ResponsesFakeProvider()
diff --git a/tests/core/anthropic/test_sse_decoder.py b/tests/core/anthropic/test_sse_decoder.py
new file mode 100644
index 00000000..2d9821ab
--- /dev/null
+++ b/tests/core/anthropic/test_sse_decoder.py
@@ -0,0 +1,38 @@
+from free_claude_code.core.anthropic.streaming import AnthropicSSEDecoder
+
+
+def test_decoder_handles_every_split_and_crlf_boundaries():
+ wire = (
+ 'event: first\r\ndata: {"type":"first"}\r\n\r\n'
+ 'event: second\ndata: {"type":"second"}\n\n'
+ )
+
+ for split in range(len(wire) + 1):
+ decoder = AnthropicSSEDecoder()
+ events = (*decoder.feed(wire[:split]), *decoder.feed(wire[split:]))
+ assert [event.event for event in events] == ["first", "second"]
+ assert decoder.finish() == ()
+
+
+def test_decoder_returns_one_unterminated_final_event():
+ decoder = AnthropicSSEDecoder()
+
+ assert decoder.feed('event: final\ndata: {"value": 1}') == ()
+ events = decoder.finish()
+
+ assert len(events) == 1
+ assert events[0].event == "final"
+ assert events[0].data == {"value": 1}
+ assert decoder.finish() == ()
+
+
+def test_decoder_handles_many_tiny_fragments_without_losing_frames():
+ wire = "".join(
+ f'event: delta\ndata: {{"index":{index}}}\n\n' for index in range(250)
+ )
+ decoder = AnthropicSSEDecoder()
+
+ events = tuple(event for character in wire for event in decoder.feed(character))
+
+ assert [event.data["index"] for event in events] == list(range(250))
+ assert decoder.finish() == ()
diff --git a/tests/providers/test_openai_chat_usage.py b/tests/providers/test_openai_chat_usage.py
index 71bed953..ee64986c 100644
--- a/tests/providers/test_openai_chat_usage.py
+++ b/tests/providers/test_openai_chat_usage.py
@@ -427,7 +427,7 @@ async def test_openai_chat_nonstream_message_uses_final_cache_partition():
)
with patch.object(provider._client.chat.completions, "create", create):
- message, error = await aggregate_anthropic_sse_to_message(
+ message, error, _complete = await aggregate_anthropic_sse_to_message(
provider.stream_messages(request, input_tokens=7)
)
diff --git a/tests/runtime/test_chat_sqlite.py b/tests/runtime/test_chat_sqlite.py
new file mode 100644
index 00000000..56345fae
--- /dev/null
+++ b/tests/runtime/test_chat_sqlite.py
@@ -0,0 +1,555 @@
+import asyncio
+import sqlite3
+import threading
+import uuid
+from contextlib import closing
+from pathlib import Path
+
+import pytest
+
+from free_claude_code.application.chat import (
+ DEFAULT_CHAT_SYSTEM_PROMPT,
+ ChatConflictError,
+ ChatReasoning,
+ ChatSegment,
+ ChatUnavailableError,
+ GenerationStatus,
+ SegmentKind,
+)
+from free_claude_code.runtime.chat_sqlite import SQLiteChatStore
+
+
+def _id() -> str:
+ return str(uuid.uuid4())
+
+
+def _store(tmp_path: Path) -> SQLiteChatStore:
+ return SQLiteChatStore(tmp_path / "chat.db", tmp_path / "chat.lock")
+
+
+async def test_store_creates_schema_preferences_and_searchable_sessions(tmp_path: Path):
+ store = _store(tmp_path)
+ await store.start()
+ try:
+ preferences = await store.load_preferences()
+ assert preferences.system_prompt == DEFAULT_CHAT_SYSTEM_PROMPT
+ assert preferences.last_reasoning is ChatReasoning.MEDIUM
+
+ first = await store.create_session(
+ session_id=_id(), model="groq/first", reasoning=ChatReasoning.MEDIUM
+ )
+ second = await store.create_session(
+ session_id=_id(), model="open_router/second", reasoning=ChatReasoning.OFF
+ )
+ renamed = await store.update_session(
+ first.id,
+ expected_revision=first.revision,
+ title="Café launch",
+ model=None,
+ reasoning=None,
+ )
+
+ page = await store.list_sessions(query="CAFÉ", cursor=None, limit=25)
+ assert [session.id for session in page.sessions] == [renamed.id]
+ assert (await store.load_preferences()).last_model == second.model
+ finally:
+ await store.close()
+
+
+async def test_store_rejects_stale_session_revision_atomically(tmp_path: Path):
+ store = _store(tmp_path)
+ await store.start()
+ try:
+ session = await store.create_session(
+ session_id=_id(), model="groq/model", reasoning=ChatReasoning.OFF
+ )
+ updated = await store.update_session(
+ session.id,
+ expected_revision=session.revision,
+ title="Current",
+ model=None,
+ reasoning=None,
+ )
+ with pytest.raises(ChatConflictError, match="another tab"):
+ await store.update_session(
+ session.id,
+ expected_revision=session.revision,
+ title="Stale",
+ model=None,
+ reasoning=None,
+ )
+ with pytest.raises(ChatConflictError, match="another tab"):
+ await store.delete_session(
+ session.id,
+ expected_revision=session.revision,
+ )
+ assert (await store.get_session(session.id)).title == updated.title
+ finally:
+ await store.close()
+
+
+async def test_user_title_new_chat_is_not_replaced_on_first_turn(tmp_path: Path):
+ store = _store(tmp_path)
+ await store.start()
+ try:
+ session = await store.create_session(
+ session_id=_id(), model="groq/model", reasoning=ChatReasoning.OFF
+ )
+ renamed = await store.update_session(
+ session.id,
+ expected_revision=session.revision,
+ title="New chat",
+ model=None,
+ reasoning=None,
+ )
+
+ await store.begin_send(
+ session.id,
+ expected_revision=renamed.revision,
+ turn_id=_id(),
+ generation_id=_id(),
+ operation_id=_id(),
+ user_text="First question",
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=1024,
+ )
+
+ assert (await store.get_session(session.id)).title == "New chat"
+ finally:
+ await store.close()
+
+
+async def test_store_persists_generation_segments_and_actual_fallback(tmp_path: Path):
+ store = _store(tmp_path)
+ await store.start()
+ try:
+ session = await store.create_session(
+ session_id=_id(), model="groq/requested", reasoning=ChatReasoning.HIGH
+ )
+ generation_id = _id()
+ operation_id = _id()
+ turn = await store.begin_send(
+ session.id,
+ expected_revision=session.revision,
+ turn_id=_id(),
+ generation_id=generation_id,
+ operation_id=operation_id,
+ user_text="Explain this",
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=4096,
+ )
+ assert turn.operation_id == operation_id
+ assert await store.generation_start_committed(
+ session.id,
+ generation_id=generation_id,
+ staged=False,
+ )
+ assert not await store.generation_start_committed(
+ session.id,
+ generation_id=generation_id,
+ staged=True,
+ )
+ await store.set_generation_actual_model(generation_id, "open_router/fallback")
+ await store.replace_generation_segments(
+ generation_id,
+ (
+ ChatSegment(0, SegmentKind.THINKING, "considering"),
+ ChatSegment(1, SegmentKind.TEXT, "answer"),
+ ),
+ )
+ completed = await store.finish_generation(
+ generation_id,
+ status=GenerationStatus.COMPLETED,
+ stop_reason="end_turn",
+ error_code=None,
+ error_message=None,
+ )
+ repeated = await store.finish_generation(
+ generation_id,
+ status=GenerationStatus.STOPPED,
+ stop_reason="stopped",
+ error_code=None,
+ error_message=None,
+ )
+
+ stored = (await store.get_transcript(session.id)).turns[0]
+ assert repeated.revision == completed.revision
+ assert stored.generation.status is GenerationStatus.COMPLETED
+ assert stored.generation.stop_reason == "end_turn"
+ assert stored.id == turn.id
+ assert stored.generation.actual_model == "open_router/fallback"
+ assert [segment.text for segment in stored.generation.segments] == [
+ "considering",
+ "answer",
+ ]
+ finally:
+ await store.close()
+
+
+async def test_transcript_reads_one_revision_snapshot(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ store = _store(tmp_path)
+ await store.start()
+ release_read = threading.Event()
+ session_read = threading.Event()
+ try:
+ session = await store.create_session(
+ session_id=_id(), model="groq/model", reasoning=ChatReasoning.OFF
+ )
+ generation_id = _id()
+ await store.begin_send(
+ session.id,
+ expected_revision=session.revision,
+ turn_id=_id(),
+ generation_id=generation_id,
+ operation_id=_id(),
+ user_text="Keep one coherent snapshot",
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=4_096,
+ )
+ original_get_session = store._get_session
+ gate_next_read = True
+
+ def gated_get_session(
+ connection: sqlite3.Connection,
+ session_id: str,
+ ):
+ nonlocal gate_next_read
+ current = original_get_session(connection, session_id)
+ if gate_next_read:
+ gate_next_read = False
+ session_read.set()
+ if not release_read.wait(timeout=5):
+ raise AssertionError(
+ "Timed out waiting to finish the transcript read."
+ )
+ return current
+
+ monkeypatch.setattr(store, "_get_session", gated_get_session)
+ transcript_task = asyncio.create_task(store.get_transcript(session.id))
+ assert await asyncio.to_thread(session_read.wait, 1)
+
+ completed = await store.finish_generation(
+ generation_id,
+ status=GenerationStatus.COMPLETED,
+ stop_reason="end_turn",
+ error_code=None,
+ error_message=None,
+ )
+ release_read.set()
+ transcript = await asyncio.wait_for(transcript_task, timeout=1)
+
+ assert completed.revision == transcript.session.revision + 1
+ assert transcript.turns[0].generation.status is GenerationStatus.RUNNING
+ finally:
+ release_read.set()
+ await store.close()
+
+
+async def test_retry_reuses_generation_and_replaces_partial_output(tmp_path: Path):
+ store = _store(tmp_path)
+ await store.start()
+ try:
+ session = await store.create_session(
+ session_id=_id(), model="groq/model", reasoning=ChatReasoning.OFF
+ )
+ generation_id = _id()
+ await store.begin_send(
+ session.id,
+ expected_revision=session.revision,
+ turn_id=_id(),
+ generation_id=generation_id,
+ operation_id=_id(),
+ user_text="hello",
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=1024,
+ )
+ await store.replace_generation_segments(
+ generation_id, (ChatSegment(0, SegmentKind.TEXT, "partial"),)
+ )
+ session = await store.finish_generation(
+ generation_id,
+ status=GenerationStatus.STOPPED,
+ stop_reason="stopped",
+ error_code=None,
+ error_message=None,
+ )
+ retried = await store.begin_retry(
+ session.id,
+ expected_revision=session.revision,
+ requested_model="open_router/new",
+ reasoning=ChatReasoning.LOW,
+ effective_output_limit=2048,
+ )
+
+ assert retried.id == generation_id
+ assert retried.status is GenerationStatus.RUNNING
+ assert retried.segments == ()
+ assert retried.requested_model == "open_router/new"
+ finally:
+ await store.close()
+
+
+async def test_regeneration_keeps_visible_answer_until_atomic_swap(tmp_path: Path):
+ store = _store(tmp_path)
+ await store.start()
+ try:
+ session = await store.create_session(
+ session_id=_id(), model="groq/model", reasoning=ChatReasoning.OFF
+ )
+ original_id = _id()
+ await store.begin_send(
+ session.id,
+ expected_revision=session.revision,
+ turn_id=_id(),
+ generation_id=original_id,
+ operation_id=_id(),
+ user_text="hello",
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=1024,
+ )
+ await store.replace_generation_segments(
+ original_id, (ChatSegment(0, SegmentKind.TEXT, "original"),)
+ )
+ session = await store.finish_generation(
+ original_id,
+ status=GenerationStatus.COMPLETED,
+ stop_reason="end_turn",
+ error_code=None,
+ error_message=None,
+ )
+ replacement_id = _id()
+ _turn, replacement = await store.begin_regenerate(
+ session.id,
+ expected_revision=session.revision,
+ generation_id=replacement_id,
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=1024,
+ )
+ assert replacement.id == replacement_id
+ assert await store.generation_start_committed(
+ session.id,
+ generation_id=replacement_id,
+ staged=True,
+ )
+ assert not await store.generation_start_committed(
+ session.id,
+ generation_id=replacement_id,
+ staged=False,
+ )
+ assert (await store.get_transcript(session.id)).turns[
+ 0
+ ].generation.id == original_id
+
+ await store.replace_generation_segments(
+ replacement_id, (ChatSegment(0, SegmentKind.TEXT, "replacement"),)
+ )
+ with pytest.raises(ChatConflictError, match="Staged"):
+ await store.finish_generation(
+ replacement_id,
+ status=GenerationStatus.COMPLETED,
+ stop_reason="end_turn",
+ error_code=None,
+ error_message=None,
+ )
+ await store.finish_regeneration(replacement_id, stop_reason="end_turn")
+ visible = (await store.get_transcript(session.id)).turns[0].generation
+ assert visible.id == replacement_id
+ assert visible.status is GenerationStatus.COMPLETED
+ assert visible.stop_reason == "end_turn"
+ assert visible.segments[0].text == "replacement"
+ finally:
+ await store.close()
+
+
+async def test_startup_recovers_visible_and_discards_staged_running_generations(
+ tmp_path: Path,
+):
+ store = _store(tmp_path)
+ await store.start()
+ session = await store.create_session(
+ session_id=_id(), model="groq/model", reasoning=ChatReasoning.OFF
+ )
+ original_id = _id()
+ await store.begin_send(
+ session.id,
+ expected_revision=session.revision,
+ turn_id=_id(),
+ generation_id=original_id,
+ operation_id=_id(),
+ user_text="hello",
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=1024,
+ )
+ await store.close()
+
+ reopened = _store(tmp_path)
+ await reopened.start()
+ try:
+ generation = (await reopened.get_transcript(session.id)).turns[0].generation
+ assert generation.status is GenerationStatus.INTERRUPTED
+ assert generation.stop_reason == "server_restart"
+ finally:
+ await reopened.close()
+
+
+async def test_startup_discards_uncommitted_regeneration_and_keeps_visible_answer(
+ tmp_path: Path,
+):
+ store = _store(tmp_path)
+ await store.start()
+ session = await store.create_session(
+ session_id=_id(), model="groq/model", reasoning=ChatReasoning.OFF
+ )
+ original_id = _id()
+ await store.begin_send(
+ session.id,
+ expected_revision=session.revision,
+ turn_id=_id(),
+ generation_id=original_id,
+ operation_id=_id(),
+ user_text="hello",
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=1024,
+ )
+ await store.replace_generation_segments(
+ original_id, (ChatSegment(0, SegmentKind.TEXT, "original"),)
+ )
+ session = await store.finish_generation(
+ original_id,
+ status=GenerationStatus.COMPLETED,
+ stop_reason="end_turn",
+ error_code=None,
+ error_message=None,
+ )
+ staged_id = _id()
+ await store.begin_regenerate(
+ session.id,
+ expected_revision=session.revision,
+ generation_id=staged_id,
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=1024,
+ )
+ await store.close()
+
+ reopened = _store(tmp_path)
+ await reopened.start()
+ try:
+ visible = (await reopened.get_transcript(session.id)).turns[0].generation
+ assert visible.id == original_id
+ with closing(sqlite3.connect(tmp_path / "chat.db")) as connection:
+ assert connection.execute(
+ "SELECT COUNT(*) FROM chat_generations WHERE id = ?", (staged_id,)
+ ).fetchone() == (0,)
+ finally:
+ await reopened.close()
+
+
+async def test_startup_discards_terminal_staged_regeneration(tmp_path: Path):
+ store = _store(tmp_path)
+ await store.start()
+ session = await store.create_session(
+ session_id=_id(), model="groq/model", reasoning=ChatReasoning.OFF
+ )
+ original_id = _id()
+ await store.begin_send(
+ session.id,
+ expected_revision=session.revision,
+ turn_id=_id(),
+ generation_id=original_id,
+ operation_id=_id(),
+ user_text="hello",
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=1024,
+ )
+ session = await store.finish_generation(
+ original_id,
+ status=GenerationStatus.COMPLETED,
+ stop_reason="end_turn",
+ error_code=None,
+ error_message=None,
+ )
+ staged_id = _id()
+ await store.begin_regenerate(
+ session.id,
+ expected_revision=session.revision,
+ generation_id=staged_id,
+ requested_model=session.model,
+ reasoning=session.reasoning,
+ effective_output_limit=1024,
+ )
+ await store.close()
+
+ with closing(sqlite3.connect(tmp_path / "chat.db")) as connection:
+ connection.execute(
+ "UPDATE chat_generations SET status = 'completed' WHERE id = ?",
+ (staged_id,),
+ )
+ connection.commit()
+
+ reopened = _store(tmp_path)
+ await reopened.start()
+ try:
+ with closing(sqlite3.connect(tmp_path / "chat.db")) as connection:
+ assert connection.execute(
+ "SELECT COUNT(*) FROM chat_generations WHERE id = ?", (staged_id,)
+ ).fetchone() == (0,)
+ finally:
+ await reopened.close()
+
+
+async def test_failed_initial_schema_creation_does_not_claim_schema_version(
+ tmp_path: Path,
+):
+ database = tmp_path / "chat.db"
+ with closing(sqlite3.connect(database)) as connection:
+ connection.execute("CREATE TABLE chat_settings (id INTEGER PRIMARY KEY)")
+
+ store = _store(tmp_path)
+ with pytest.raises(ChatUnavailableError, match="storage is unavailable"):
+ await store.start()
+
+ with closing(sqlite3.connect(database)) as connection:
+ assert connection.execute("PRAGMA user_version").fetchone() == (0,)
+
+
+async def test_newer_schema_and_lock_contention_disable_only_chat(tmp_path: Path):
+ database = tmp_path / "newer.db"
+ with closing(sqlite3.connect(database)) as connection:
+ connection.execute("PRAGMA user_version = 99")
+ newer = SQLiteChatStore(database, tmp_path / "newer.lock")
+ with pytest.raises(ChatUnavailableError, match="newer FCC version"):
+ await newer.start()
+
+ first = _store(tmp_path / "locked")
+ second = _store(tmp_path / "locked")
+ await first.start()
+ try:
+ with pytest.raises(ChatUnavailableError, match="another FCC server"):
+ await second.start()
+ finally:
+ await first.close()
diff --git a/tests/runtime/test_codex_catalog.py b/tests/runtime/test_codex_catalog.py
index 81cc68c1..9ddd3f34 100644
--- a/tests/runtime/test_codex_catalog.py
+++ b/tests/runtime/test_codex_catalog.py
@@ -23,7 +23,10 @@ class FakeRequestRuntime(RequestRuntimePort):
self._settings = settings
self._cached_infos = cached_infos
- async def acquire(self) -> RequestRuntimeLease:
+ async def acquire(
+ self, *, include_model_infos: bool = False
+ ) -> RequestRuntimeLease:
+ del include_model_infos
raise AssertionError("Catalog publication must not acquire a provider lease.")
def current_settings(self) -> Settings:
diff --git a/tests/runtime/test_provider_manager.py b/tests/runtime/test_provider_manager.py
index 21331474..5a67f88c 100644
--- a/tests/runtime/test_provider_manager.py
+++ b/tests/runtime/test_provider_manager.py
@@ -90,6 +90,7 @@ async def test_startup_generation_lease_and_shutdown_close_exactly_once() -> Non
assert lease.generation_id == 1
assert lease.settings is settings
+ assert lease.model_infos == ()
assert lease.is_provider_cached("cached") is True
assert lease.resolve_provider("nvidia_nim") is factory.runtimes[0].provider
await lease.release()
@@ -797,6 +798,41 @@ async def test_application_catalog_survives_generation_replacement() -> None:
await manager.close()
+async def test_generation_lease_keeps_its_model_metadata_after_replacement() -> None:
+ factory = RuntimeFactory()
+ first_settings = _settings("open_router/one").model_copy(
+ update={"open_router_api_key": "open-router-key"}
+ )
+ manager = ProviderRuntimeManager(first_settings, runtime_factory=factory)
+ manager.cache_model_infos(
+ "open_router",
+ {
+ ProviderModelInfo(
+ "old-model",
+ context_window_tokens=32_000,
+ max_output_tokens=4_096,
+ )
+ },
+ )
+ lease = await manager.acquire(include_model_infos=True)
+
+ await manager.replace(
+ _settings("nvidia_nim/two"),
+ commit=lambda: None,
+ )
+
+ assert lease.model_infos == (
+ ProviderModelInfo(
+ "open_router/old-model",
+ context_window_tokens=32_000,
+ max_output_tokens=4_096,
+ ),
+ )
+ await lease.release()
+ await manager.close()
+
+
@pytest.mark.asyncio
async def test_replacement_prunes_and_rejects_removed_remote_provider_cache() -> None:
factory = RuntimeFactory()
diff --git a/uv.lock b/uv.lock
index 8f1aa777..ebc7e99c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,10 +598,11 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.17.5"
+version = "5.18.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },
+ { name = "anyio" },
{ name = "discord-py" },
{ name = "fastapi", extra = ["standard"] },
{ name = "google-auth", extra = ["requests"] },
@@ -649,6 +650,7 @@ dev = [
requires-dist = [
{ name = "accelerate", marker = "extra == 'voice-local'", specifier = ">=1.14.0" },
{ name = "aiohttp", specifier = ">=3.14.3" },
+ { name = "anyio", specifier = ">=4.12.1" },
{ name = "discord-py", specifier = ">=2.7.1" },
{ name = "fastapi", extras = ["standard"], specifier = ">=0.141.1" },
{ name = "google-auth", extras = ["requests"], specifier = ">=2.56.3" },