Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(chat): headless chat sessions on one transport-neutral engine (#3746)
Raghav Chamadiya876eb77593de
diff --git a/docs/architecture/chat.md b/docs/architecture/chat.mdindex c1919c37e..08c2c7578 100644--- a/docs/architecture/chat.md+++ b/docs/architecture/chat.md@@ -53,7 +53,7 @@ POST /api/repos/{repo_id}/chat/messages+---------------------------------------+```-The agentic loop is in the chat router for most providers (OpenAI, Anthropic,+The agentic loop is in the chat session engine (`chat_session.py`) for most providers (OpenAI, Anthropic,Ollama, LiteLLM). For Gemini, the loop runs inside `stream_chat()` using nativeContent objects to preserve thought signatures. The router passes a`tool_executor` callback that Gemini calls internally.@@ -174,7 +174,7 @@ TOOL_REGISTRY: dict[str, ToolDef] # name -> ToolDef(name, description, paramete|----------|---------|| `get_tool_schemas_for_llm()` | Returns OpenAI-format tool definitions for the LLM || `execute_tool(name, args)` | Runs a tool and ensures JSON-serializable output |-| `get_artifact_type(name)` | Maps tool name to frontend artifact type |+| `ToolBackend.catalog_for(...)` | Tool contracts, each carrying its frontend artifact type || `init_tool_state(...)` | Bridges FastAPI app state to MCP module globals |**Tool to artifact type mapping (7 tools):**diff --git a/packages/core/alembic/versions/0110_chat_sessions.py b/packages/core/alembic/versions/0110_chat_sessions.pynew file mode 100644index 000000000..c24d40c9e--- /dev/null+++ b/packages/core/alembic/versions/0110_chat_sessions.py@@ -0,0 +1,71 @@+"""Headless chat sessions on ``conversations`` and send keys on ``chat_messages``.++``conversations`` gains the caller's opaque thread key (``namespace`` plus+``external_ref``, unique together so a thread resumes its conversation), the+session scope, the principal that opened it, the policy frozen at open, and+running token and turn counts. ``chat_messages.idempotency_key`` is unique per+conversation, so a retried send returns the stored reply.++Local SQLite stores never run Alembic; ``init_db`` adds the columns and indexes+there from the model.++Revision ID: 0110+Revises: 0109+Create Date: 2026-10-14+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++# revision identifiers+revision: str = "0110"+down_revision: str | None = "0109"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.add_column("conversations", sa.Column("namespace", sa.String(128), nullable=True))+ op.add_column("conversations", sa.Column("external_ref", sa.String(512), nullable=True))+ op.add_column("conversations", sa.Column("scope_json", sa.Text, nullable=True))+ op.add_column("conversations", sa.Column("principal_id", sa.String(256), nullable=True))+ op.add_column("conversations", sa.Column("policy_json", sa.Text, nullable=True))+ for column in ("input_tokens", "output_tokens", "turns"):+ op.add_column(+ "conversations",+ sa.Column(column, sa.Integer, nullable=False, server_default="0"),+ )+ op.create_index(+ "uq_conversations_external_ref",+ "conversations",+ ["namespace", "external_ref"],+ unique=True,+ )+ op.add_column("chat_messages", sa.Column("idempotency_key", sa.String(128), nullable=True))+ op.create_index(+ "uq_chat_messages_idempotency_key",+ "chat_messages",+ ["conversation_id", "idempotency_key"],+ unique=True,+ )+++def downgrade() -> None:+ op.drop_index("uq_chat_messages_idempotency_key", table_name="chat_messages")+ op.drop_column("chat_messages", "idempotency_key")+ op.drop_index("uq_conversations_external_ref", table_name="conversations")+ for column in (+ "turns",+ "output_tokens",+ "input_tokens",+ "policy_json",+ "principal_id",+ "scope_json",+ "external_ref",+ "namespace",+ ):+ op.drop_column("conversations", column)diff --git a/packages/core/src/repowise/core/persistence/crud/chat.py b/packages/core/src/repowise/core/persistence/crud/chat.pyindex e8f878cef..698540613 100644--- a/packages/core/src/repowise/core/persistence/crud/chat.py+++ b/packages/core/src/repowise/core/persistence/crud/chat.py@@ -27,8 +27,21 @@ async def create_conversation(*,repository_id: str,title: str = "New conversation",+ namespace: str | None = None,+ external_ref: str | None = None,+ scope_json: str | None = None,+ principal_id: str | None = None,+ policy_json: str | None = None,) -> Conversation:- conv = Conversation(repository_id=repository_id, title=title)+ conv = Conversation(+ repository_id=repository_id,+ title=title,+ namespace=namespace,+ external_ref=external_ref,+ scope_json=scope_json,+ principal_id=principal_id,+ policy_json=policy_json,+ )session.add(conv)await session.flush()return conv@@ -38,6 +51,31 @@ async def get_conversation(session: AsyncSession, conversation_id: str) -> Convereturn await session.get(Conversation, conversation_id)+async def get_conversation_by_external_ref(+ session: AsyncSession, namespace: str, external_ref: str+) -> Conversation | None:+ """The conversation a caller's thread key names, deleted or not."""+ result = await session.execute(+ select(Conversation).where(+ Conversation.namespace == namespace, Conversation.external_ref == external_ref+ )+ )+ return result.scalars().first()+++async def record_conversation_turn(+ session: AsyncSession, conversation_id: str, *, input_tokens: int, output_tokens: int+) -> None:+ """Count one finished turn and the tokens it used."""+ conv = await session.get(Conversation, conversation_id)+ if conv:+ conv.turns = (conv.turns or 0) + 1+ conv.input_tokens = (conv.input_tokens or 0) + input_tokens+ conv.output_tokens = (conv.output_tokens or 0) + output_tokens+ conv.updated_at = _now_utc()+ await session.flush()++async def list_conversations(session: AsyncSession, repository_id: str, *, limit: int = 50) -> list[Conversation]:@@ -140,11 +178,13 @@ async def create_chat_message(conversation_id: str,role: str,content: dict,+ idempotency_key: str | None = None,) -> ChatMessage:msg = ChatMessage(conversation_id=conversation_id,role=role,content_json=json.dumps(content),+ idempotency_key=idempotency_key,)session.add(msg)await session.flush()@@ -160,6 +200,29 @@ async def list_chat_messages(session: AsyncSession, conversation_id: str) -> lisreturn list(result.scalars().all())+async def find_idempotent_turn(+ session: AsyncSession, conversation_id: str, idempotency_key: str+) -> tuple[ChatMessage, ChatMessage | None] | None:+ """The user message sent under *idempotency_key* and the reply after it.++ The reply is None when that send never finished (it failed or was+ cancelled before anything was saved).+ """+ result = await session.execute(+ select(ChatMessage).where(+ ChatMessage.conversation_id == conversation_id,+ ChatMessage.idempotency_key == idempotency_key,+ )+ )+ sent = result.scalars().first()+ if sent is None:+ return None+ messages = await list_chat_messages(session, conversation_id)+ after = messages[[m.id for m in messages].index(sent.id) + 1 :]+ reply = next((m for m in after[:1] if m.role == "assistant"), None)+ return sent, reply++async def update_chat_message_content(session: AsyncSession,message_id: str,diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex f75fc52a1..c1f0d9750 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -1564,9 +1564,18 @@ class DecisionAlias(Base):class Conversation(Base):- """A chat conversation for a repository."""+ """A chat conversation for a repository.++ A headless session also carries the caller's opaque thread key+ (``namespace`` plus ``external_ref``, unique together), its scope, the+ principal that opened it, the policy frozen at open, and running token+ and turn counts. Conversations started from the web leave them empty.+ """__tablename__ = "conversations"+ __table_args__ = (+ Index("uq_conversations_external_ref", "namespace", "external_ref", unique=True),+ )id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_new_uuid)repository_id: Mapped[str] = mapped_column(@@ -1575,6 +1584,19 @@ class Conversation(Base):title: Mapped[str] = mapped_column(Text, nullable=False, default="New conversation")pinned: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)deleted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)+ namespace: Mapped[str | None] = mapped_column(String(128), nullable=True)+ external_ref: Mapped[str | None] = mapped_column(String(512), nullable=True)+ # {"kind": "repo" | "workspace", "alias": str | None}; NULL reads as repo.+ scope_json: Mapped[str | None] = mapped_column(Text, nullable=True)+ principal_id: Mapped[str | None] = mapped_column(String(256), nullable=True)+ policy_json: Mapped[str | None] = mapped_column(Text, nullable=True)+ input_tokens: Mapped[int] = mapped_column(+ Integer, nullable=False, default=0, server_default="0"+ )+ output_tokens: Mapped[int] = mapped_column(+ Integer, nullable=False, default=0, server_default="0"+ )+ turns: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default="0")created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=_now_utc)@@ -1587,6 +1609,11 @@ class ChatMessage(Base):"""A single message in a chat conversation."""__tablename__ = "chat_messages"+ __table_args__ = (+ Index(+ "uq_chat_messages_idempotency_key", "conversation_id", "idempotency_key", unique=True+ ),+ )id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_new_uuid)conversation_id: Mapped[str] = mapped_column(@@ -1594,6 +1621,9 @@ class ChatMessage(Base):)role: Mapped[str] = mapped_column(String(32), nullable=False) # user | assistantcontent_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")+ #: On a user message: the caller's key for this send, so a retry returns+ #: the stored reply instead of running the turn again.+ idempotency_key: Mapped[str | None] = mapped_column(String(128), nullable=True)created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=_now_utc)diff --git a/packages/core/src/repowise/core/providers/llm/anthropic.py b/packages/core/src/repowise/core/providers/llm/anthropic.pyindex 4ccf10928..7d7a987d6 100644--- a/packages/core/src/repowise/core/providers/llm/anthropic.py+++ b/packages/core/src/repowise/core/providers/llm/anthropic.py@@ -286,9 +286,13 @@ class AnthropicProvider(SdkClientOwner, BaseProvider):async with self._client.messages.stream(**kwargs) as stream:async for event in _iter_anthropic_stream_events(stream):yield event- blocks = _thinking_turn_blocks(await stream.get_final_message())+ final = await stream.get_final_message()+ blocks = _thinking_turn_blocks(final)if blocks:yield ChatStreamEvent(type="assistant_content", content_blocks=blocks)+ usage = _final_usage(final)+ if usage is not None:+ yield usagedef _translate_anthropic_errors() -> AbstractContextManager[None]:@@ -361,21 +365,30 @@ async def _iter_anthropic_stream_events(stream: Any) -> AsyncIterator[ChatStreamdef _message_delta_events(event: Any) -> list[ChatStreamEvent]:- """Usage and stop events carried by a ``message_delta``, in that order."""- events: list[ChatStreamEvent] = []- usage = getattr(event, "usage", None)- if usage:- events.append(- ChatStreamEvent(- type="usage",- input_tokens=getattr(usage, "input_tokens", 0) or 0,- output_tokens=getattr(usage, "output_tokens", 0) or 0,- )- )+ """The stop event carried by a ``message_delta``; usage is read once, at the end."""stop = getattr(event.delta, "stop_reason", None)- if stop:- events.append(ChatStreamEvent(type="stop", stop_reason=stop))- return events+ return [ChatStreamEvent(type="stop", stop_reason=stop)] if stop else []+++def _final_usage(message: Any) -> ChatStreamEvent | None:+ """The call's ``usage`` event from the final message, cache reads and writes+ counted as input as ``generate`` does; None when the SDK reported none."""+ usage = getattr(message, "usage", None)+ counts = [+ getattr(usage, key, None)+ for key in (+ "input_tokens",+ "output_tokens",+ "cache_read_input_tokens",+ "cache_creation_input_tokens",+ )+ ]+ if not isinstance(counts[0], int) or not isinstance(counts[1], int):+ return None+ cached = sum(c for c in counts[2:] if isinstance(c, int))+ return ChatStreamEvent(+ type="usage", input_tokens=counts[0] + cached, output_tokens=counts[1]+ )def _build_cached_payload(diff --git a/packages/core/src/repowise/core/providers/llm/base.py b/packages/core/src/repowise/core/providers/llm/base.pyindex 2bb141455..18893405f 100644--- a/packages/core/src/repowise/core/providers/llm/base.py+++ b/packages/core/src/repowise/core/providers/llm/base.py@@ -638,7 +638,9 @@ class ChatStreamEvent:- ``text_delta``: incremental text token(s) in ``text``- ``tool_start``: a completed tool call block in ``tool_call``- ``tool_result``: tool execution result (from internal loops) in ``tool_call`` + ``tool_result_data``- - ``usage``: token counts in ``input_tokens`` / ``output_tokens``+ - ``usage``: the call's token counts in ``input_tokens`` / ``output_tokens``.+ At most one per ``stream_chat`` call, after ``stop``, and only when the+ SDK reported usage; no ``usage`` event means the counts are unknown.- ``stop``: end of generation (may follow tool_start if stop_reason is tool_use)- ``assistant_content``: the turn's provider-native blocks in ``content_blocks``,after ``stop``. The caller stores them on the assistant message asdiff --git a/packages/core/src/repowise/core/providers/llm/gemini.py b/packages/core/src/repowise/core/providers/llm/gemini.pyindex 867d5a78b..e60aabd4c 100644--- a/packages/core/src/repowise/core/providers/llm/gemini.py+++ b/packages/core/src/repowise/core/providers/llm/gemini.py@@ -504,6 +504,7 @@ class GeminiProvider(BaseProvider):contents = _to_gemini_contents(messages)max_loops = 10+ usage = _UsageTotal()for _ in range(max_loops):# Call Geminitry:@@ -512,10 +513,11 @@ class GeminiProvider(BaseProvider):raiseexcept Exception as exc:raise ProviderError("gemini", f"{type(exc).__name__}: {exc}") from exc+ usage.add(getattr(response, "usage_metadata", None))if not response.candidates:yield ChatStreamEvent(type="stop", stop_reason="end_turn")- return+ break# The model's response content — preserved as-is for the next turnmodel_content = response.candidates[0].content@@ -526,14 +528,14 @@ class GeminiProvider(BaseProvider):if not function_calls_found:yield ChatStreamEvent(type="stop", stop_reason="end_turn")- return+ break# If no tool_executor, yield stop and let the caller handle# (will break on next round-trip due to thought_signature, but# this is a fallback)if tool_executor is None:yield ChatStreamEvent(type="stop", stop_reason="tool_use")- return+ break# Execute tools and build function_response parts# Append the model's response (with thought signatures) to contents@@ -557,9 +559,30 @@ class GeminiProvider(BaseProvider):# Append tool results as a user turncontents.append(genai_types.Content(role="user", parts=response_parts))# Loop back to get the model's text response+ else:+ # Max loops reached+ yield ChatStreamEvent(type="stop", stop_reason="end_turn")+ if usage.reported:+ yield ChatStreamEvent(+ type="usage", input_tokens=usage.input_tokens, output_tokens=usage.output_tokens+ )+++class _UsageTotal:+ """Token counts summed over the internal tool loop's calls."""++ def __init__(self) -> None:+ self.input_tokens = 0+ self.output_tokens = 0+ self.reported = False- # Max loops reached- yield ChatStreamEvent(type="stop", stop_reason="end_turn")+ def add(self, metadata: Any) -> None:+ prompt = getattr(metadata, "prompt_token_count", None)+ output = getattr(metadata, "candidates_token_count", None)+ if isinstance(prompt, int):+ self.input_tokens += prompt+ self.output_tokens += output if isinstance(output, int) else 0+ self.reported = Truedef _strip_unsupported_schema_keys(schema: Any) -> Any:diff --git a/packages/core/src/repowise/core/providers/llm/openai.py b/packages/core/src/repowise/core/providers/llm/openai.pyindex c3285d463..b7b035fda 100644--- a/packages/core/src/repowise/core/providers/llm/openai.py+++ b/packages/core/src/repowise/core/providers/llm/openai.py@@ -164,6 +164,9 @@ def _openai_temperature(model: str, requested: float) -> float:return requested+_OPENAI_API_URL = "https://api.openai.com/v1"++def _openai_chat_tool_kwargs(model: str, *, has_tools: bool) -> dict[str, Any]:"""Return Chat Completions overrides required by tool-enabled models.@@ -306,7 +309,7 @@ class OpenAIProvider(SdkClientOwner, BaseProvider):)resolved_base_url = base_url or os.environ.get("OPENAI_BASE_URL")self._api_key = resolved_key- self._base_url = resolved_base_url or "https://api.openai.com/v1"+ self._base_url = resolved_base_url or _OPENAI_API_URLloopback = bool(resolved_base_url and _is_loopback_url(resolved_base_url))def _new_client() -> AsyncOpenAI:@@ -441,6 +444,10 @@ class OpenAIProvider(SdkClientOwner, BaseProvider):"messages": full_messages,"stream": True,}+ if self._base_url == _OPENAI_API_URL:+ # Without it the stream carries no usage chunk. Only the hosted API+ # is asked: an OpenAI-compatible server may reject the field.+ kwargs["stream_options"] = {"include_usage": True}if tools:kwargs["tools"] = toolskwargs.update(_openai_chat_tool_kwargs(self._model, has_tools=bool(tools)))diff --git a/packages/server/src/repowise/server/chat_context.py b/packages/server/src/repowise/server/chat_context.pynew file mode 100644index 000000000..cfd0a3020--- /dev/null+++ b/packages/server/src/repowise/server/chat_context.py@@ -0,0 +1,165 @@+"""Keep the model-facing chat request inside the model's context window.++Stored and streamed artifacts stay whole so a client can render them; only the+copy sent to the provider is bounded. History is cut to a newest suffix of+whole turns, an oversized tool result becomes a marked excerpt, and a request+still over the ceiling sheds its oldest complete tool rounds (an assistant tool+call and its results move together, or the provider rejects the transcript).++The ceilings sit above what the MCP tools already return (their own response+budget is about 32k characters), so an ordinary turn reaches the model exactly+as before; they only bite on long conversations and runaway loops. Characters,+not tokens: no tokenizer is shipped, and dense JSON costs roughly 2.5 to 4+characters a token. When a provider still reports an overflow the engine retries+once with :func:`compose_request` in emergency mode.+"""++from __future__ import annotations++import json+from collections.abc import Sequence+from typing import Any++#: One tool result as the model sees it.+RESULT_CHAR_BUDGET = 48_000+#: Earlier turns replayed into a new turn, tool results included.+HISTORY_CHAR_BUDGET = 240_000+#: The whole message list of one provider call (system prompt and schemas excluded).+REQUEST_CHAR_BUDGET = 400_000++OVERFLOW_MESSAGE = (+ "This conversation is too large for the model to process. "+ "Ask a narrower question or start a new chat."+)++_MARKER = "\n\n[content omitted to fit the model context]\n\n"+_OVERFLOW_MARKERS = (+ "context_length_exceeded",+ "context length",+ "context window",+ "input tokens exceed",+ "maximum context length",+ "prompt is too long",+ "request too large",+ "too many tokens",+)+++def message_chars(value: Any) -> int:+ """Compact JSON size, the unit every budget here is counted in."""+ return len(json.dumps(value, ensure_ascii=True, separators=(",", ":"), default=str))+++def _middle_truncate(text: str, limit: int) -> str:+ if len(text) <= limit:+ return text+ available = max(0, limit - len(_MARKER))+ head = available // 2+ return f"{text[:head]}{_MARKER}{text[len(text) - (available - head):]}"+++def _bounded_tool_message(message: dict[str, Any], limit: int) -> dict[str, Any]:+ content = message.get("content")+ if message.get("role") != "tool" or not isinstance(content, str) or len(content) <= limit:+ return message+ excerpt = {+ "truncated": True,+ "original_chars": len(content),+ "note": "Result too large for the chat context; ask for a narrower target.",+ "excerpt": _middle_truncate(content, max(1_000, limit - 400)),+ }+ return {**message, "content": json.dumps(excerpt)}+++def bound_tool_messages(+ messages: Sequence[dict[str, Any]], limit: int = RESULT_CHAR_BUDGET+) -> list[dict[str, Any]]:+ """The messages with every oversized tool result replaced by an excerpt.++ Parallel results of one round share the budget, so a round of five large+ reads costs about what one does.+ """+ results = sum(1 for m in messages if m.get("role") == "tool")+ share = max(4_000, limit // max(1, results))+ return [_bounded_tool_message(m, share) for m in messages]+++def _turn_groups(messages: Sequence[dict[str, Any]]) -> list[list[dict[str, Any]]]:+ """Split a transcript into turns, each starting at a user message."""+ groups: list[list[dict[str, Any]]] = []+ for message in messages:+ if message.get("role") == "user" or not groups:+ groups.append([])+ groups[-1].append(message)+ return groups+++def bound_history(+ messages: Sequence[dict[str, Any]], budget: int = HISTORY_CHAR_BUDGET+) -> list[dict[str, Any]]:+ """The newest whole turns that fit *budget*, oldest first.++ The last turn (the question being asked) is always kept; a huge question+ is middle-truncated rather than dropped. A suffix never starts with an+ orphaned assistant or tool message.+ """+ groups = _turn_groups(messages)+ kept: list[list[dict[str, Any]]] = []+ remaining = budget+ for index, group in enumerate(reversed(groups)):+ group = bound_tool_messages(group)+ size = message_chars(group)+ if index == 0:+ if size > remaining:+ group = [_bounded_user_message(m, remaining) for m in group]+ kept.append(group)+ remaining -= min(remaining, size)+ continue+ if size > remaining:+ break+ kept.append(group)+ remaining -= size+ selected = [message for group in reversed(kept) for message in group]+ while selected and selected[0].get("role") != "user":+ selected.pop(0)+ return selected+++def _bounded_user_message(message: dict[str, Any], limit: int) -> dict[str, Any]:+ content = message.get("content")+ if message.get("role") != "user" or not isinstance(content, str):+ return message+ return {**message, "content": _middle_truncate(content, max(1_000, limit))}+++def _flatten(base: Sequence[dict[str, Any]], rounds: Sequence[Sequence[dict[str, Any]]]):+ return [*base, *(message for round_messages in rounds for message in round_messages)]+++def compose_request(+ base: Sequence[dict[str, Any]],+ rounds: Sequence[Sequence[dict[str, Any]]],+ *,+ emergency: bool = False,+) -> list[dict[str, Any]]:+ """One provider call's messages: history plus this turn's tool rounds.++ Sheds the oldest complete rounds while the request is over budget. In+ emergency mode (after the provider reported an overflow) only the newest+ question and the newest round are sent.+ """+ rounds = [bound_tool_messages(r) for r in rounds]+ if emergency:+ newest_user = next((m for m in reversed(base) if m.get("role") == "user"), None)+ return _flatten([newest_user] if newest_user else [], rounds[-1:])+ messages = _flatten(base, rounds)+ while len(rounds) > 1 and message_chars(messages) > REQUEST_CHAR_BUDGET:+ rounds.pop(0)+ messages = _flatten(base, rounds)+ return messages+++def is_context_overflow(exc: BaseException) -> bool:+ """True when a provider error says the request exceeded the context window."""+ text = str(exc).lower()+ return any(marker in text for marker in _OVERFLOW_MARKERS)diff --git a/packages/server/src/repowise/server/chat_prompt.py b/packages/server/src/repowise/server/chat_prompt.pyindex dc01d7186..ea2ef073b 100644--- a/packages/server/src/repowise/server/chat_prompt.py+++ b/packages/server/src/repowise/server/chat_prompt.py@@ -185,16 +185,13 @@ def _assistant_history(content: dict[str, Any]) -> list[dict[str, Any]]:return messages-def _db_messages_to_llm_format(db_messages: list) -> list[dict[str, Any]]:- """Convert DB chat messages to OpenAI-format message list."""+def stored_messages_to_llm_format(messages: list) -> list[dict[str, Any]]:+ """Convert stored chat messages (``id``, ``role``, ``content`` dict) to+ an OpenAI-format message list."""llm_messages: list[dict[str, Any]] = []- for msg in db_messages:- content = (- json.loads(msg.content_json) if isinstance(msg.content_json, str) else msg.content_json- )- if isinstance(content, dict):- content = normalize_message_artifacts(content, message_id=str(msg.id))+ for msg in messages:+ content = normalize_message_artifacts(msg.content, message_id=str(msg.id))if msg.role == "user":llm_messages.append({"role": "user", "content": content.get("text", "")})diff --git a/packages/server/src/repowise/server/chat_seams.py b/packages/server/src/repowise/server/chat_seams.pynew file mode 100644index 000000000..46d609ed5--- /dev/null+++ b/packages/server/src/repowise/server/chat_seams.py@@ -0,0 +1,252 @@+"""The seams a chat session runs on, and the values that cross them.++:mod:`repowise.server.chat_session` owns the loop; everything it reads or+writes outside itself goes through one of three seams, each a named+``SeamRegistry`` with ``local`` registered by the session module:++* ``chat-tools`` (:class:`ToolBackend`): the tools a session may call. Local is+ this server's configured MCP surface.+* ``chat-store`` (:class:`ConversationStore`): where conversations live. Local+ is the SQLAlchemy ``conversations`` table of the repository's index.+* ``chat-hooks`` (:class:`TurnHooks`): admission, usage and event callbacks+ around each turn. Local does nothing.++The tool and store seams hold factories, called once per session with its+:class:`SessionScope` (and principal, for tools), so an implementation can bind+to the session's repository. A plugin registers its own from the+``repowise.plugins`` entry point and selects it with ``default=True`` or+``REPOWISE_SEAM_CHAT_TOOLS`` / ``_CHAT_STORE`` / ``_CHAT_HOOKS``.+"""++from __future__ import annotations++import json+from collections.abc import Callable+from dataclasses import asdict, dataclass, field, fields+from typing import Any, Literal, Protocol, runtime_checkable++from repowise.core.registry.plugins import SeamRegistry+from repowise.server.auth import Principal+from repowise.server.chat_tools import ChatToolContract++#: Tool safety kinds in widening order; a policy admits its ceiling and below.+SAFETY_ORDER: tuple[str, ...] = ("read_only", "generative", "mutating")++Audience = Literal["engineer", "business"]+SafetyCeiling = Literal["read_only", "generative", "mutating"]+++@dataclass(frozen=True)+class SessionScope:+ """What a session is about.++ ``repo`` sessions pin tool calls to ``repo_alias`` inside a workspace;+ ``workspace`` sessions leave the repo argument to the model, so ``"all"``+ and any alias are reachable. ``repo_id`` is the repository the+ conversation is stored with (a workspace's primary for workspace scope).+ ``storage`` is the handle the local store writes through (a session+ factory); other stores may ignore it.+ """++ kind: Literal["repo", "workspace"]+ repo_id: str+ repo_name: str+ repo_path: str+ repo_alias: str | None = None+ storage: Any = field(default=None, compare=False, repr=False)++ def stored(self) -> dict[str, Any]:+ return {"kind": self.kind, "alias": self.repo_alias}+++@dataclass(frozen=True)+class SessionPolicy:+ """Limits one session runs under, frozen when the session is opened.++ The defaults suit a headless caller: read-only tools, 20 model calls a+ turn. ``audience`` is stored and passed along; nothing reads it yet.+ """++ tool_allowlist: frozenset[str] | None = None+ safety_ceiling: SafetyCeiling = "read_only"+ max_tool_loops: int = 20+ max_turns: int | None = None+ max_output_tokens: int = 8192+ max_turn_tokens: int | None = None+ max_session_tokens: int | None = None+ temperature: float = 0.7+ audience: Audience = "engineer"++ def admits(self, tool: ChatToolContract) -> bool:+ return self.admits_name(tool.entry.name, tool.entry.safety)++ def admits_name(self, name: str, safety: str) -> bool:+ if self.tool_allowlist is not None and name not in self.tool_allowlist:+ return False+ safety = safety if safety in SAFETY_ORDER else "mutating"+ return SAFETY_ORDER.index(safety) <= SAFETY_ORDER.index(self.safety_ceiling)++ def to_json(self) -> str:+ data = asdict(self)+ if self.tool_allowlist is not None:+ data["tool_allowlist"] = sorted(self.tool_allowlist)+ return json.dumps(data, sort_keys=True)++ @classmethod+ def from_json(cls, raw: str | None, default: SessionPolicy) -> SessionPolicy:+ """The stored policy, or *default* for a conversation that has none.+ Unknown keys (from a newer server) are ignored."""+ if not raw:+ return default+ data = json.loads(raw)+ known = {f.name for f in fields(cls)}+ values = {k: v for k, v in data.items() if k in known}+ if values.get("tool_allowlist") is not None:+ values["tool_allowlist"] = frozenset(values["tool_allowlist"])+ return cls(**values)+++@dataclass(frozen=True)+class TurnUsage:+ """Tokens one turn used. ``None`` means the provider reported nothing."""++ input_tokens: int | None = None+ output_tokens: int | None = None+ model_calls: int = 0++ @property+ def total(self) -> int:+ return (self.input_tokens or 0) + (self.output_tokens or 0)+++@dataclass(frozen=True)+class StoredConversation:+ id: str+ repository_id: str+ title: str+ scope: dict[str, Any]+ namespace: str | None+ external_ref: str | None+ principal_id: str | None+ policy_json: str | None+ input_tokens: int+ output_tokens: int+ turns: int+ deleted: bool++ @property+ def tokens_used(self) -> int:+ return self.input_tokens + self.output_tokens+++@dataclass(frozen=True)+class StoredMessage:+ id: str+ role: str+ content: dict[str, Any]+++@runtime_checkable+class ToolBackend(Protocol):+ """The tools one session may see and call."""++ def catalog_for(+ self, policy: SessionPolicy, principal: Principal | None+ ) -> list[ChatToolContract]:+ """Tools available to *principal*. The session intersects this with+ *policy* itself and refuses any other name at execution."""+ ...++ async def execute(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:+ """Run one tool. Failures come back as ``{"error": ..., "error_code": ...}``."""+ ...+++@runtime_checkable+class ConversationStore(Protocol):+ """Where a session's conversation and messages live."""++ async def get_or_create(+ self,+ *,+ repository_id: str,+ title: str,+ scope: dict[str, Any],+ namespace: str | None,+ external_ref: str | None,+ principal_id: str | None,+ policy_json: str | None,+ ) -> tuple[StoredConversation, bool]:+ """The conversation keyed by ``(namespace, external_ref)``, created+ when absent (always created without a key); the flag says which."""+ ...++ async def get(self, conversation_id: str) -> StoredConversation | None: ...++ async def find(self, namespace: str, external_ref: str) -> StoredConversation | None: ...++ async def messages(self, conversation_id: str) -> list[StoredMessage]:+ """Every message, oldest first."""+ ...++ async def find_sent(+ self, conversation_id: str, idempotency_key: str+ ) -> tuple[StoredMessage, StoredMessage | None] | None:+ """``(user message, reply or None)`` for a key already sent, else None."""+ ...++ async def add_user_message(+ self, conversation_id: str, content: dict[str, Any], *, idempotency_key: str | None+ ) -> str: ...++ async def add_reply(+ self,+ conversation_id: str,+ content: dict[str, Any],+ *,+ title: str | None,+ usage: TurnUsage,+ ) -> str:+ """Store the assistant message, count the turn and its tokens, and+ retitle the conversation when *title* is given."""+ ...+++@runtime_checkable+class TurnHooks(Protocol):+ """Callbacks around each turn, for admission control and metering."""++ async def preflight(+ self, principal: Principal | None, policy: SessionPolicy, conversation: StoredConversation+ ) -> str | None:+ """None to run the turn, or the reason it is refused."""+ ...++ async def on_usage(+ self, principal: Principal | None, conversation: StoredConversation, usage: TurnUsage+ ) -> None: ...++ async def on_event(self, event: dict[str, Any]) -> list[dict[str, Any]]:+ """Called with every event the turn emits; returns extra events to emit after it."""+ ...+++class NoTurnHooks:+ """The local default: admit every turn, record nothing, add nothing."""++ async def preflight(self, principal, policy, conversation) -> str | None:+ return None++ async def on_usage(self, principal, conversation, usage) -> None:+ return None++ async def on_event(self, event: dict[str, Any]) -> list[dict[str, Any]]:+ return []+++ToolBackendFactory = Callable[[SessionScope, Principal | None], ToolBackend]+ConversationStoreFactory = Callable[[SessionScope], ConversationStore]++tool_backends: SeamRegistry[ToolBackendFactory] = SeamRegistry("chat-tools")+conversation_stores: SeamRegistry[ConversationStoreFactory] = SeamRegistry("chat-store")+turn_hooks: SeamRegistry[TurnHooks] = SeamRegistry("chat-hooks")diff --git a/packages/server/src/repowise/server/chat_session.py b/packages/server/src/repowise/server/chat_session.pynew file mode 100644index 000000000..a9ffc786d--- /dev/null+++ b/packages/server/src/repowise/server/chat_session.py@@ -0,0 +1,855 @@+"""Transport-neutral chat sessions: the one agentic loop every surface drives.++A :class:`ChatSession` is one conversation opened under a :class:`SessionScope`,+a :class:`SessionPolicy` and an optional principal. ``stream`` yields the turn+as event dicts (the names the web chat reads: ``grounding``, ``text_delta``,+``tool_start``, ``tool_result``, ``view``, ``truncated``, ``suggestions``,+``done``, ``error``); ``send`` runs the same turn and returns a+:class:`ChatTurnResult`. Nothing here imports FastAPI: the HTTP routes format+events as SSE, and an in-process caller uses the class directly.++The tools a model is shown, and the only ones it can run, are the backend's+catalog for the principal narrowed by the policy's allowlist and safety+ceiling, plus the chat-only ``show_view`` tool, which builds tables and+charts from this turn's results (:mod:`repowise.server.chat_views`).+Everything outside the loop goes through the seams in+:mod:`repowise.server.chat_seams`.+"""++from __future__ import annotations++import asyncio+import logging+import weakref+from collections.abc import AsyncIterator, Awaitable, Callable+from dataclasses import asdict, dataclass, field+from typing import Any, Literal++from repowise.core.providers.llm.base import ChatProvider, ProviderError+from repowise.server.auth import Principal+from repowise.server.chat_artifacts import create_artifact_envelope+from repowise.server.chat_context import (+ OVERFLOW_MESSAGE,+ bound_history,+ compose_request,+ is_context_overflow,+)+from repowise.server.chat_grounding import plan_grounding, run_grounding+from repowise.server.chat_prompt import (+ _build_system_prompt,+ _history_has_call,+ _with_navigation_context,+ assistant_tool_call_message,+ stored_messages_to_llm_format,+ tool_result_message,+)+from repowise.server.chat_seams import (+ ConversationStore,+ NoTurnHooks,+ SessionPolicy,+ SessionScope,+ StoredConversation,+ StoredMessage,+ ToolBackend,+ TurnHooks,+ TurnUsage,+ conversation_stores,+ tool_backends,+ turn_hooks,+)+from repowise.server.chat_store import SqlConversationStore+from repowise.server.chat_suggestions import conversation_title, follow_up_suggestions, tool_names+from repowise.server.chat_summaries import _build_tool_summary+from repowise.server.chat_tools import ChatToolContract, LocalToolBackend, tool_schemas+from repowise.server.chat_views import SHOW_VIEW_TOOL, TurnViews, show_view_schema++logger = logging.getLogger(__name__)++#: A headless session: read-only tools, 20 model calls a turn.+DEFAULT_POLICY = SessionPolicy()+#: The web chat keeps the surface it always had: every configured tool, a+#: mutating one still refused at execution without a confirmation grant.+WEB_POLICY = SessionPolicy(safety_ceiling="mutating")++StopReason = Literal[+ "answered", "loop_cap", "token_budget", "turn_budget", "refused", "cancelled", "error"+]+IsCancelled = Callable[[], Awaitable[bool]]++conversation_stores.register("local", lambda scope: SqlConversationStore(scope.storage))+tool_backends.register(+ "local",+ lambda scope, principal: LocalToolBackend(+ scope.repo_path,+ repo_alias=scope.repo_alias if scope.kind == "repo" else None,+ repo_id=scope.repo_id,+ principal=principal,+ ),+)+turn_hooks.register("local", NoTurnHooks())+++class SessionNotFoundError(LookupError):+ """The conversation does not exist, was deleted, or belongs to another repository."""+++class IdempotencyConflictError(ValueError):+ """An idempotency key already sent with a different message."""+++@dataclass(frozen=True)+class ToolTraceEntry:+ """What one tool call did, without its payload."""++ name: str+ summary: str+ ok: bool+ basis: str+ origin: str | None = None+++@dataclass(frozen=True)+class ChatTurnResult:+ conversation_id: str+ #: None when nothing was stored (refused, cancelled, failed).+ message_id: str | None+ user_message_id: str | None+ answer: str+ stop_reason: StopReason+ provider: str+ model: str+ citations: list[dict[str, Any]] = field(default_factory=list)+ cards: list[dict[str, Any]] = field(default_factory=list)+ views: list[dict[str, Any]] = field(default_factory=list)+ tool_trace: list[ToolTraceEntry] = field(default_factory=list)+ follow_ups: list[dict[str, Any]] = field(default_factory=list)+ usage: TurnUsage = field(default_factory=TurnUsage)+ error: str | None = None+ #: True when an idempotency key matched and the stored reply was returned.+ replayed: bool = False+++# ---------------------------------------------------------------------------+# Per-conversation turn lock+# ---------------------------------------------------------------------------++# In-process only: two server processes on one database can still interleave+# turns of one conversation. A multi-process deployment needs a database lock+# (an advisory lock or SELECT ... FOR UPDATE) behind the store.+_turn_locks: weakref.WeakValueDictionary[str, asyncio.Lock] = weakref.WeakValueDictionary()+++def _turn_lock(conversation_id: str) -> asyncio.Lock:+ lock = _turn_locks.get(conversation_id)+ if lock is None:+ lock = asyncio.Lock()+ _turn_locks[conversation_id] = lock+ return lock+++async def _never_cancelled() -> bool:+ return False+++# ---------------------------------------------------------------------------+# Stored content <-> results+# ---------------------------------------------------------------------------+++def _citations(tool_calls: list[dict[str, Any]]) -> list[dict[str, Any]]:+ """Files the turn's tool results cite, first mention first."""+ seen: set[tuple[Any, ...]] = set()+ out: list[dict[str, Any]] = []+ for call in tool_calls:+ data = (call.get("artifact") or {}).get("data") or {}+ raw = data.get("citations") if isinstance(data, dict) else None+ for item in raw if isinstance(raw, list) else []:+ if isinstance(item, str):+ citation = {"file_path": item}+ elif isinstance(item, dict) and isinstance(item.get("file_path"), str):+ citation = {+ key: item[key]+ for key in ("file_path", "symbol_name", "start_line", "end_line")+ if item.get(key) is not None+ }+ else:+ continue+ key = tuple(sorted(citation.items()))+ if key not in seen:+ seen.add(key)+ out.append(citation)+ return out+++def _tool_trace(tool_calls: list[dict[str, Any]]) -> list[ToolTraceEntry]:+ trace = []+ for call in tool_calls:+ artifact = call.get("artifact") or {}+ data = artifact.get("data")+ trace.append(+ ToolTraceEntry(+ name=str(call.get("name", "")),+ summary=str(call.get("summary", "")),+ ok=not (isinstance(data, dict) and "error" in data),+ basis=str((artifact.get("evidence") or {}).get("basis", "unknown")),+ origin=call.get("origin"),+ )+ )+ return trace+++def _result_from_content(+ content: dict[str, Any],+ *,+ conversation_id: str,+ message_id: str | None,+ user_message_id: str | None,+ stop_reason: StopReason,+ replayed: bool = False,+) -> ChatTurnResult:+ tool_calls = [c for c in content.get("tool_calls") or [] if isinstance(c, dict)]+ usage = content.get("usage")+ return ChatTurnResult(+ conversation_id=conversation_id,+ message_id=message_id,+ user_message_id=user_message_id,+ answer=str(content.get("text", "")),+ stop_reason=stop_reason,+ provider=str(content.get("provider", "")),+ model=str(content.get("model", "")),+ citations=_citations(tool_calls),+ cards=list(content.get("cards") or []),+ views=list(content.get("views") or []),+ tool_trace=_tool_trace(tool_calls),+ follow_ups=list(content.get("follow_ups") or []),+ usage=TurnUsage(**usage) if isinstance(usage, dict) else TurnUsage(),+ replayed=replayed,+ )+++def _closing_events(result: ChatTurnResult) -> list[dict[str, Any]]:+ events: list[dict[str, Any]] = []+ if result.follow_ups:+ events.append({"type": "suggestions", "suggestions": result.follow_ups})+ done: dict[str, Any] = {+ "type": "done",+ "conversation_id": result.conversation_id,+ "message_id": result.message_id,+ "user_message_id": result.user_message_id,+ "provider": result.provider,+ "model": result.model,+ }+ if result.replayed:+ done["replayed"] = True+ events.append(done)+ return events+++# ---------------------------------------------------------------------------+# One turn+# ---------------------------------------------------------------------------+++class _Turn:+ """The model and tool loop of one turn, and what it records.++ ``base`` is the bounded history ending with the question; each tool round+ (an assistant tool call and its results) is kept whole in ``rounds`` so+ the request can shed old rounds without breaking the transcript.+ """++ def __init__(+ self,+ *,+ provider: ChatProvider,+ tools: ToolBackend,+ catalog: list[ChatToolContract],+ policy: SessionPolicy,+ base: list[dict[str, Any]],+ tokens_before: int,+ is_cancelled: IsCancelled,+ shows_views: bool = False,+ ) -> None:+ self.provider = provider+ self.tools = tools+ self.catalog = {tool.entry.name: tool for tool in catalog}+ self.shows_views = shows_views+ self.views = TurnViews()+ self.policy = policy+ self.base = base+ self.rounds: list[list[dict[str, Any]]] = []+ self.tokens_before = tokens_before+ self.is_cancelled = is_cancelled+ self.text_parts: list[str] = []+ self.provider_content: list[dict[str, Any]] | None = None+ self.tool_calls: list[dict[str, Any]] = []+ self.stop_reason: StopReason = "answered"+ self.error: str | None = None+ self.model_calls = 0+ self.input_tokens: int | None = None+ self.output_tokens: int | None = None++ @property+ def usage(self) -> TurnUsage:+ return TurnUsage(self.input_tokens, self.output_tokens, self.model_calls)++ @property+ def stopped(self) -> bool:+ return self.stop_reason in ("cancelled", "error")++ async def execute(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:+ """Run one tool the session admits; also handed to providers that loop internally.++ Each result is stamped with the artifact id ``show_view`` takes.+ """+ if name == SHOW_VIEW_TOOL and self.shows_views:+ return self.views.show(arguments)+ tool = self.catalog.get(name)+ if tool is None:+ return {+ "error": f"Tool is not available in this session: {name}",+ "error_code": "tool_not_enabled",+ }+ return self.views.record(+ name,+ arguments,+ await self.tools.execute(name, arguments),+ artifact_type=tool.entry.artifact_type,+ evidence_basis=tool.entry.evidence_basis,+ )++ async def ground(self, page_context: Any) -> dict[str, Any] | None:+ """Make the one read the page already justifies, before the first model call.++ A repeat of a call the history already holds is skipped.+ """+ plan = plan_grounding(page_context, (tool.entry for tool in self.catalog.values()))+ if plan is not None and _history_has_call(self.base, plan.tool_name, plan.arguments):+ plan = None+ grounding = await run_grounding(plan, self.execute, unstamp=self.views.unstamp)+ if grounding is None:+ return None+ self.rounds.append(grounding.llm_messages())+ self.tool_calls.append(+ _stored_tool_call(+ grounding.tool_id,+ grounding.tool_name,+ grounding.arguments,+ grounding.summary,+ grounding.artifact,+ origin="grounding",+ )+ )+ return grounding.sse_payload()++ def _over_budget(self) -> bool:+ used = self.usage.total+ policy = self.policy+ if policy.max_turn_tokens is not None and used >= policy.max_turn_tokens:+ return True+ return (+ policy.max_session_tokens is not None+ and self.tokens_before + used >= policy.max_session_tokens+ )++ async def run(self, system_prompt: str, schemas: list[dict[str, Any]]) -> AsyncIterator[dict]:+ """Alternate model calls and tool runs until the model answers or a limit stops it."""+ for _ in range(self.policy.max_tool_loops):+ if self._over_budget():+ self.stop_reason = "token_budget"+ break+ pending: list[dict[str, Any]] = []+ async for event in self._model_call(system_prompt, schemas, pending):+ yield event+ if self.stopped or not pending:+ return+ async for event in self._run_pending(pending):+ yield event+ if self.stopped:+ return+ else:+ # Every call ended in a tool call, so no final answer exists.+ self.stop_reason = "loop_cap"+ yield {+ "type": "truncated",+ "loops": self.policy.max_tool_loops+ if self.stop_reason == "loop_cap"+ else self.model_calls,+ "reason": self.stop_reason,+ }++ async def _model_call(+ self, system_prompt: str, schemas: list[dict[str, Any]], pending: list[dict[str, Any]]+ ) -> AsyncIterator[dict]:+ """Stream one provider call, collecting the tool calls left to us in *pending*.++ A provider that reports a context overflow before anything streamed is+ asked once more with only the question and the newest tool round.+ """+ self.model_calls += 1+ for attempt in range(2):+ emitted = False+ try:+ async for event in self.provider.stream_chat(+ messages=compose_request(self.base, self.rounds, emergency=attempt > 0),+ tools=schemas,+ system_prompt=system_prompt,+ max_tokens=self.policy.max_output_tokens,+ temperature=self.policy.temperature,+ tool_executor=self.execute,+ ):+ if await self.is_cancelled():+ self.stop_reason = "cancelled"+ return+ for out in self._on_provider_event(event, pending):+ emitted = True+ yield out+ return+ except ProviderError as exc:+ overflow = is_context_overflow(exc)+ if overflow and attempt == 0 and not emitted:+ logger.warning("chat_context_overflow_retry")+ pending.clear()+ continue+ self.stop_reason = "error"+ self.error = OVERFLOW_MESSAGE if overflow else str(exc)+ yield {"type": "error", "message": self.error}+ return++ def _on_provider_event(self, event: Any, pending: list[dict[str, Any]]) -> list[dict]:+ if event.type == "text_delta" and event.text:+ self.text_parts.append(event.text)+ return [{"type": "text_delta", "text": event.text}]+ if event.type == "usage":+ self.input_tokens = (self.input_tokens or 0) + event.input_tokens+ self.output_tokens = (self.output_tokens or 0) + event.output_tokens+ return []+ if event.type == "assistant_content":+ self.provider_content = event.content_blocks+ return []+ tc = event.tool_call+ if not tc:+ return []+ if event.type == "tool_start":+ pending.append({"id": tc.id, "name": tc.name, "arguments": tc.arguments})+ return [+ {+ "type": "tool_start",+ "tool_id": tc.id,+ "tool_name": tc.name,+ "input": tc.arguments,+ }+ ]+ if event.type == "tool_result":+ # The provider already ran this tool (e.g. Gemini), so it leaves the pending list.+ pending[:] = [p for p in pending if p["id"] != tc.id]+ return self._tool_result(tc.id, tc.name, tc.arguments, event.tool_result_data or {})+ return []++ async def _run_pending(self, pending: list[dict[str, Any]]) -> AsyncIterator[dict]:+ """Run the tool calls the provider left to us and feed the results back."""+ round_messages = [+ assistant_tool_call_message(+ "".join(self.text_parts), pending, provider_content=self.provider_content+ )+ ]+ self.rounds.append(round_messages)+ self.text_parts.clear()+ self.provider_content = None+ for tc in pending:+ if await self.is_cancelled():+ self.stop_reason = "cancelled"+ return+ result = await self.execute(tc["name"], tc["arguments"])+ for event in self._tool_result(tc["id"], tc["name"], tc["arguments"], result):+ yield event+ round_messages.append(tool_result_message(tc["id"], tc["name"], result))++ def _tool_result(+ self, tool_id: str, name: str, arguments: dict[str, Any], result: dict[str, Any]+ ) -> list[dict[str, Any]]:+ """Record one tool result as a stored call and return its events: the+ result, then the view a successful ``show_view`` built."""+ tool = self.catalog.get(name)+ # The stored artifact keeps the tool's own data; only the model's copy is stamped.+ artifact_id, data = self.views.unstamp(result)+ summary = _build_tool_summary(name, data)+ artifact = create_artifact_envelope(+ tool_name=name,+ artifact_type=tool.entry.artifact_type if tool else "generic",+ presentation=tool.entry.presentation if tool else "generic",+ data=data,+ title=summary,+ artifact_id=artifact_id,+ evidence_basis=tool.entry.evidence_basis if tool else "unknown",+ )+ self.tool_calls.append(_stored_tool_call(tool_id, name, arguments, summary, artifact))+ event = {+ "type": "tool_result",+ "tool_id": tool_id,+ "tool_name": name,+ "summary": summary,+ "artifact": artifact,+ }+ view = self.views.event(tool_id, result) if name == SHOW_VIEW_TOOL else None+ return [event] if view is None else [event, view]++ def reply_content(self) -> dict[str, Any]:+ content: dict[str, Any] = {+ "text": "".join(self.text_parts),+ "tool_calls": self.tool_calls,+ "provider": self.provider.provider_name,+ "model": self.provider.model_name,+ "usage": asdict(self.usage),+ }+ if self.stop_reason in ("loop_cap", "token_budget"):+ content["truncated"] = True+ content["stop_reason"] = self.stop_reason+ # A turn that read nothing, or read only failures, has no next step to propose.+ follow_ups = follow_up_suggestions(self.tool_calls)+ if follow_ups:+ content["follow_ups"] = follow_ups+ if self.views.parts:+ content["views"] = self.views.parts+ return content+++def _stored_tool_call(+ tool_id: str,+ name: str,+ arguments: dict[str, Any],+ summary: str,+ artifact: dict[str, Any],+ origin: str | None = None,+) -> dict[str, Any]:+ """Persist one durable artifact payload with the assistant message.++ ``origin`` marks a call the server made for the page rather than the+ model; absent for model-made calls so stored rows keep their shape.+ """+ stored = {+ "id": tool_id,+ "name": name,+ "arguments": arguments,+ "summary": summary,+ "artifact": artifact,+ }+ if origin:+ stored["origin"] = origin+ return stored+++# ---------------------------------------------------------------------------+# The session+# ---------------------------------------------------------------------------+++@dataclass+class _Outcome:+ result: ChatTurnResult | None = None+++class ChatSession:+ """One conversation and the limits it runs under. Open with :meth:`open`."""++ def __init__(+ self,+ *,+ conversation: StoredConversation,+ created: bool,+ scope: SessionScope,+ policy: SessionPolicy,+ provider: ChatProvider | None,+ principal: Principal | None,+ store: ConversationStore,+ tools: ToolBackend,+ hooks: TurnHooks,+ ) -> None:+ self.conversation = conversation+ self.created = created+ self.scope = scope+ self.policy = policy+ self.provider = provider+ self.principal = principal+ self.store = store+ self.tools = tools+ self.hooks = hooks++ @property+ def id(self) -> str:+ return self.conversation.id++ @classmethod+ async def open(+ cls,+ *,+ scope: SessionScope,+ provider: ChatProvider | None = None,+ principal: Principal | None = None,+ policy: SessionPolicy | None = None,+ fallback_policy: SessionPolicy = DEFAULT_POLICY,+ conversation_id: str | None = None,+ namespace: str | None = None,+ external_ref: str | None = None,+ title: str = "New conversation",+ store: ConversationStore | None = None,+ tools: ToolBackend | None = None,+ hooks: TurnHooks | None = None,+ ) -> ChatSession:+ """Resume *conversation_id*, get or create the one ``(namespace,+ external_ref)`` names, or start a new one. A session opened without a+ *provider* can be inspected but not sent to.++ *policy* is frozen on a conversation this call creates; a resumed one+ keeps the policy it was opened with, or *fallback_policy* if it has+ none. Raises :class:`SessionNotFoundError` for a missing or deleted+ conversation, or one stored with another repository.+ """+ store = store if store is not None else conversation_stores.get()(scope)+ if conversation_id is not None:+ conversation = await store.get(conversation_id)+ created = False+ else:+ conversation, created = await store.get_or_create(+ repository_id=scope.repo_id,+ title=title,+ scope=scope.stored(),+ namespace=namespace,+ external_ref=external_ref,+ principal_id=principal.id if principal is not None else None,+ policy_json=policy.to_json() if policy is not None else None,+ )+ if (+ conversation is None+ or conversation.deleted+ or conversation.repository_id != scope.repo_id+ ):+ raise SessionNotFoundError("Conversation not found")+ return cls(+ conversation=conversation,+ created=created,+ scope=scope,+ policy=SessionPolicy.from_json(+ conversation.policy_json, default=policy or fallback_policy+ ),+ provider=provider,+ principal=principal,+ store=store,+ tools=tools if tools is not None else tool_backends.get()(scope, principal),+ hooks=hooks if hooks is not None else turn_hooks.get(),+ )++ def catalog(self) -> list[ChatToolContract]:+ """The tools this session may show and run: backend ∩ principal ∩ policy."""+ return [+ tool+ for tool in self.tools.catalog_for(self.policy, self.principal)+ if self.policy.admits(tool)+ ]++ def stream(+ self,+ message: str,+ *,+ context: Any = None,+ idempotency_key: str | None = None,+ is_cancelled: IsCancelled | None = None,+ ) -> AsyncIterator[dict[str, Any]]:+ """Run one turn, yielding its events."""+ return self._events(message, context, idempotency_key, is_cancelled, _Outcome())++ async def send(+ self,+ message: str,+ *,+ context: Any = None,+ idempotency_key: str | None = None,+ is_cancelled: IsCancelled | None = None,+ ) -> ChatTurnResult:+ """Run one turn and return its result."""+ outcome = _Outcome()+ async for _ in self._events(message, context, idempotency_key, is_cancelled, outcome):+ pass+ assert outcome.result is not None+ return outcome.result++ async def _events(+ self,+ message: str,+ context: Any,+ idempotency_key: str | None,+ is_cancelled: IsCancelled | None,+ outcome: _Outcome,+ ) -> AsyncIterator[dict[str, Any]]:+ if self.provider is None:+ raise ValueError("this session was opened without a provider")+ async with _turn_lock(self.id):+ try:+ async for event in self._turn(+ message, context, idempotency_key, is_cancelled or _never_cancelled, outcome+ ):+ yield event+ for extra in await self.hooks.on_event(event):+ yield extra+ except IdempotencyConflictError:+ raise+ except Exception as exc:+ logger.exception("Chat turn error")+ text = f"Internal error: {type(exc).__name__}: {exc}"+ outcome.result = self._unstored("error", error=text)+ yield {"type": "error", "message": text}++ async def check_send(self, message: str, idempotency_key: str | None) -> None:+ """Raise :class:`IdempotencyConflictError` when *idempotency_key* was+ already sent with another message. ``send`` and ``stream`` check too;+ this lets a transport refuse before it starts a response."""+ if idempotency_key is None:+ return+ sent = await self.store.find_sent(self.id, idempotency_key)+ if sent is not None:+ _check_same_message(sent[0], message, idempotency_key)++ def _unstored(+ self, stop_reason: StopReason, *, error: str | None = None, **values: Any+ ) -> ChatTurnResult:+ return ChatTurnResult(+ conversation_id=self.id,+ message_id=None,+ user_message_id=values.pop("user_message_id", None),+ answer=values.pop("answer", ""),+ stop_reason=stop_reason,+ provider=self.provider.provider_name,+ model=self.provider.model_name,+ error=error,+ **values,+ )++ async def _refusal(self, conversation: StoredConversation) -> tuple[StopReason, str] | None:+ policy = self.policy+ if policy.max_turns is not None and conversation.turns >= policy.max_turns:+ return "turn_budget", "This conversation has used its turn budget."+ if (+ policy.max_session_tokens is not None+ and conversation.tokens_used >= policy.max_session_tokens+ ):+ return "token_budget", "This conversation has used its token budget."+ reason = await self.hooks.preflight(self.principal, policy, conversation)+ return ("refused", reason) if reason else None++ async def _turn(+ self,+ message: str,+ context: Any,+ idempotency_key: str | None,+ is_cancelled: IsCancelled,+ outcome: _Outcome,+ ) -> AsyncIterator[dict[str, Any]]:+ conversation = await self.store.get(self.id)+ if conversation is None or conversation.deleted:+ outcome.result = self._unstored("error", error="Conversation not found")+ yield {"type": "error", "message": "Conversation not found"}+ return+ self.conversation = conversation++ user_message_id: str | None = None+ if idempotency_key is not None:+ sent = await self.store.find_sent(self.id, idempotency_key)+ if sent is not None:+ user_message, reply = sent+ _check_same_message(user_message, message, idempotency_key)+ user_message_id = user_message.id+ if reply is not None:+ outcome.result = _replayed(reply, self.id, user_message_id)+ if outcome.result.answer:+ yield {"type": "text_delta", "text": outcome.result.answer}+ for event in _closing_events(outcome.result):+ yield event+ return+ # That send stored its question and then failed; run it again on it.++ refusal = await self._refusal(conversation)+ if refusal is not None:+ stop_reason, reason = refusal+ outcome.result = self._unstored(stop_reason, error=reason)+ yield {"type": "error", "message": reason}+ return++ if user_message_id is None:+ user_message_id = await self.store.add_user_message(+ self.id, {"text": message}, idempotency_key=idempotency_key+ )+ history = await self.store.messages(self.id)+ opening = all(m.id == user_message_id for m in history)++ catalog = self.catalog()+ # show_view is chat-only and read-only: never an MCP tool, offered+ # whenever there is a tool whose result it could be built from.+ shows_views = bool(catalog) and self.policy.admits_name(SHOW_VIEW_TOOL, "read_only")+ schemas = tool_schemas(catalog)+ if shows_views:+ schemas.append(show_view_schema([tool.entry.artifact_type for tool in catalog]))+ turn = _Turn(+ provider=self.provider,+ tools=self.tools,+ catalog=catalog,+ policy=self.policy,+ base=bound_history(+ _with_navigation_context(stored_messages_to_llm_format(history), context)+ ),+ tokens_before=conversation.tokens_used,+ is_cancelled=is_cancelled,+ shows_views=shows_views,+ )+ grounded = await turn.ground(context)+ if grounded is not None:+ yield grounded+ system_prompt = _build_system_prompt(+ self.scope.repo_name, self.scope.repo_path, catalog, context+ )+ async for event in turn.run(system_prompt, schemas):+ yield event+ if turn.stopped:+ # Nothing is stored for a cancelled or failed turn; the question stays.+ outcome.result = self._unstored(+ turn.stop_reason,+ error=turn.error,+ user_message_id=user_message_id,+ answer="".join(turn.text_parts),+ usage=turn.usage,+ )+ return++ content = turn.reply_content()+ title = conversation_title(message, tool_names(turn.tool_calls)) if opening else None+ message_id = await self.store.add_reply(+ self.id, content, title=title, usage=turn.usage+ )+ await self.hooks.on_usage(self.principal, conversation, turn.usage)+ outcome.result = _result_from_content(+ content,+ conversation_id=self.id,+ message_id=message_id,+ user_message_id=user_message_id,+ stop_reason=turn.stop_reason,+ )+ for event in _closing_events(outcome.result):+ yield event+++def _check_same_message(sent: StoredMessage, message: str, idempotency_key: str) -> None:+ if sent.content.get("text") != message:+ raise IdempotencyConflictError(+ f"idempotency key {idempotency_key!r} was already sent with a different message"+ )+++def _replayed(reply: StoredMessage, conversation_id: str, user_message_id: str) -> ChatTurnResult:+ content = reply.content+ return _result_from_content(+ content,+ conversation_id=conversation_id,+ message_id=reply.id,+ user_message_id=user_message_id,+ stop_reason=content.get("stop_reason", "answered"),+ replayed=True,+ )diff --git a/packages/server/src/repowise/server/chat_store.py b/packages/server/src/repowise/server/chat_store.pynew file mode 100644index 000000000..ddcfe9ea9--- /dev/null+++ b/packages/server/src/repowise/server/chat_store.py@@ -0,0 +1,148 @@+"""The local ``ConversationStore``: the ``conversations`` table of an index."""++from __future__ import annotations++import json+from typing import Any++from sqlalchemy.exc import IntegrityError++from repowise.core.persistence import crud+from repowise.core.persistence.database import get_session+from repowise.server.chat_seams import StoredConversation, StoredMessage, TurnUsage+++def _conversation(row: Any) -> StoredConversation:+ try:+ scope = json.loads(row.scope_json) if row.scope_json else {}+ except json.JSONDecodeError:+ scope = {}+ return StoredConversation(+ id=row.id,+ repository_id=row.repository_id,+ title=row.title,+ scope=scope if isinstance(scope, dict) else {},+ namespace=row.namespace,+ external_ref=row.external_ref,+ principal_id=row.principal_id,+ policy_json=row.policy_json,+ input_tokens=row.input_tokens or 0,+ output_tokens=row.output_tokens or 0,+ turns=row.turns or 0,+ deleted=row.deleted_at is not None,+ )+++def _message(row: Any) -> StoredMessage:+ raw = row.content_json+ try:+ content = json.loads(raw) if isinstance(raw, str) else raw+ except json.JSONDecodeError:+ content = {"text": raw}+ return StoredMessage(+ id=row.id, role=row.role, content=content if isinstance(content, dict) else {}+ )+++class SqlConversationStore:+ """Conversations in one index database, through its session factory."""++ def __init__(self, session_factory: Any) -> None:+ self._factory = session_factory++ async def get_or_create(+ self,+ *,+ repository_id: str,+ title: str,+ scope: dict[str, Any],+ namespace: str | None,+ external_ref: str | None,+ principal_id: str | None,+ policy_json: str | None,+ ) -> tuple[StoredConversation, bool]:+ if namespace is not None and external_ref is not None:+ found = await self.find(namespace, external_ref)+ if found is not None:+ return found, False+ try:+ async with get_session(self._factory) as session:+ row = await crud.create_conversation(+ session,+ repository_id=repository_id,+ title=title,+ namespace=namespace,+ external_ref=external_ref,+ scope_json=json.dumps(scope),+ principal_id=principal_id,+ policy_json=policy_json,+ )+ created = _conversation(row)+ except IntegrityError:+ # A concurrent open of the same thread won the unique key.+ if namespace is None or external_ref is None:+ raise+ found = await self.find(namespace, external_ref)+ if found is None:+ raise+ return found, False+ return created, True++ async def get(self, conversation_id: str) -> StoredConversation | None:+ async with get_session(self._factory) as session:+ row = await crud.get_conversation(session, conversation_id)+ return _conversation(row) if row is not None else None++ async def find(self, namespace: str, external_ref: str) -> StoredConversation | None:+ async with get_session(self._factory) as session:+ row = await crud.get_conversation_by_external_ref(session, namespace, external_ref)+ return _conversation(row) if row is not None else None++ async def messages(self, conversation_id: str) -> list[StoredMessage]:+ async with get_session(self._factory) as session:+ return [_message(m) for m in await crud.list_chat_messages(session, conversation_id)]++ async def find_sent(+ self, conversation_id: str, idempotency_key: str+ ) -> tuple[StoredMessage, StoredMessage | None] | None:+ async with get_session(self._factory) as session:+ found = await crud.find_idempotent_turn(session, conversation_id, idempotency_key)+ if found is None:+ return None+ sent, reply = found+ return _message(sent), (_message(reply) if reply is not None else None)++ async def add_user_message(+ self, conversation_id: str, content: dict[str, Any], *, idempotency_key: str | None+ ) -> str:+ async with get_session(self._factory) as session:+ message = await crud.create_chat_message(+ session,+ conversation_id=conversation_id,+ role="user",+ content=content,+ idempotency_key=idempotency_key,+ )+ return message.id++ async def add_reply(+ self,+ conversation_id: str,+ content: dict[str, Any],+ *,+ title: str | None,+ usage: TurnUsage,+ ) -> str:+ async with get_session(self._factory) as session:+ message = await crud.create_chat_message(+ session, conversation_id=conversation_id, role="assistant", content=content+ )+ await crud.record_conversation_turn(+ session,+ conversation_id,+ input_tokens=usage.input_tokens or 0,+ output_tokens=usage.output_tokens or 0,+ )+ if title is not None:+ await crud.update_conversation_title(session, conversation_id, title)+ return message.iddiff --git a/packages/server/src/repowise/server/chat_tools.py b/packages/server/src/repowise/server/chat_tools.pyindex 678b20bc2..9f6058979 100644--- a/packages/server/src/repowise/server/chat_tools.py+++ b/packages/server/src/repowise/server/chat_tools.py@@ -50,10 +50,8 @@ def get_tool_catalog(return catalog-def get_tool_schemas_for_llm(- repo_path: str | None, principal: Principal | None = None-) -> list[dict[str, Any]]:- """Return OpenAI-format definitions from FastMCP's canonical schemas."""+def tool_schemas(catalog: list[ChatToolContract]) -> list[dict[str, Any]]:+ """OpenAI-format definitions for *catalog*, the only tools a model is shown."""return [{"type": "function",@@ -63,10 +61,17 @@ def get_tool_schemas_for_llm("parameters": tool.parameters,},}- for tool in get_tool_catalog(repo_path, principal)+ for tool in catalog]+def get_tool_schemas_for_llm(+ repo_path: str | None, principal: Principal | None = None+) -> list[dict[str, Any]]:+ """Return OpenAI-format definitions from FastMCP's canonical schemas."""+ return tool_schemas(get_tool_catalog(repo_path, principal))++def _make_json_serializable(obj: Any) -> Any:if obj is None or isinstance(obj, (bool, int, float, str)):return obj@@ -182,19 +187,43 @@ def _catalog_entry(tool_name: str, repo_path: str | None) -> ToolEntry | None:)-def get_artifact_type(tool_name: str, repo_path: str | None) -> str:- entry = _catalog_entry(tool_name, repo_path)- return entry.artifact_type if entry is not None else "generic"---def get_artifact_presentation(tool_name: str, repo_path: str | None) -> str:- entry = _catalog_entry(tool_name, repo_path)- return entry.presentation if entry is not None else "generic"+class LocalToolBackend:+ """The default chat ``ToolBackend``: this server's configured MCP surface.+ One instance is bound to one session's repository and principal, which is+ the per-session part of tool state. The tools' data handles (database,+ search, workspace registry) stay process-wide in ``mcp_server``, published+ by :func:`init_tool_state` and :func:`set_tool_workspace`, so one process+ serves one index or workspace; repo scoping keeps sessions apart within it.+ """-def get_artifact_evidence_basis(tool_name: str, repo_path: str | None) -> str:- entry = _catalog_entry(tool_name, repo_path)- return entry.evidence_basis if entry is not None else "unknown"+ def __init__(+ self,+ repo_path: str | None,+ *,+ repo_alias: str | None = None,+ repo_id: str | None = None,+ principal: Principal | None = None,+ ) -> None:+ self.repo_path = repo_path+ self.repo_alias = repo_alias+ self.repo_id = repo_id+ self.principal = principal++ def catalog_for(self, policy: Any, principal: Principal | None) -> list[ChatToolContract]:+ """The repository's surface within *principal*'s tool scope. The session+ narrows it further by *policy*, for every backend alike."""+ return get_tool_catalog(self.repo_path, principal)++ async def execute(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:+ return await execute_tool(+ name,+ arguments,+ repo_path=self.repo_path,+ repo=self.repo_alias,+ principal=self.principal,+ repo_id=self.repo_id,+ )def init_tool_state(diff --git a/packages/server/src/repowise/server/deps.py b/packages/server/src/repowise/server/deps.pyindex 5800d4d90..96ea189ec 100644--- a/packages/server/src/repowise/server/deps.py+++ b/packages/server/src/repowise/server/deps.py@@ -133,9 +133,17 @@ def auth_is_open(request: Request) -> bool:return not get_authenticator().configured() and client_is_local(request)-#: Routes a repo-scoped principal may call without naming a repo, because the-#: handler filters its output to the principal's scope.-_SCOPE_FILTERED_ROUTES = frozenset({("GET", "/api/repos"), ("GET", "/api/repos/summary")})+#: Routes a repo-scoped principal may call without naming a repo in the path,+#: because the handler filters its output to, or checks, the principal's scope.+_SCOPE_FILTERED_ROUTES = frozenset(+ {+ ("GET", "/api/repos"),+ ("GET", "/api/repos/summary"),+ ("POST", "/api/chat/sessions"),+ ("GET", "/api/chat/sessions"),+ ("POST", "/api/chat/sessions/{session_id}/messages"),+ }+)async def _repo_identifiers(request: Request, repo_id: str) -> tuple[str, ...]:diff --git a/packages/server/src/repowise/server/routers/chat.py b/packages/server/src/repowise/server/routers/chat.pyindex bfa9e65b2..be0450517 100644--- a/packages/server/src/repowise/server/routers/chat.py+++ b/packages/server/src/repowise/server/routers/chat.py@@ -1,10 +1,16 @@-"""Chat router: the SSE agentic loop and conversation management."""+"""Chat router: SSE and JSON transports over chat sessions, and conversation management.++The turn itself runs in :mod:`repowise.server.chat_session`; these routes+resolve the repository, principal and provider, then stream its events as SSE+or return its result as JSON.+"""from __future__ import annotationsimport jsonimport loggingfrom collections.abc import AsyncIterator, Iterator+from dataclasses import asdictfrom pathlib import Pathfrom typing import Any@@ -14,42 +20,30 @@ from starlette.responses import StreamingResponsefrom repowise.core.persistence import crudfrom repowise.core.persistence.database import get_session-from repowise.core.providers.llm.base import ChatProvider, ProviderError-from repowise.server.auth import PER_CALL_TOOL_SCOPE-from repowise.server.chat_artifacts import (- create_artifact_envelope,- find_artifact,- set_artifact_pinned,-)+from repowise.core.providers.llm.base import ChatProvider+from repowise.server.auth import PER_CALL_TOOL_SCOPE, Principal, get_authorizer+from repowise.server.chat_artifacts import find_artifact, set_artifact_pinnedfrom repowise.server.chat_grounding import plan_grounding, run_grounding-from repowise.server.chat_prompt import (- _build_system_prompt,- _db_messages_to_llm_format,- _history_has_call,- _with_navigation_context,- assistant_tool_call_message,- tool_result_message,-)-from repowise.server.chat_suggestions import (- conversation_title,- follow_up_suggestions,- page_suggestions,- tool_names,+from repowise.server.chat_seams import (+ SessionPolicy,+ SessionScope,+ StoredConversation,+ conversation_stores,+ tool_backends,)-from repowise.server.chat_summaries import _build_tool_summary-from repowise.server.chat_tools import (- execute_tool,- get_artifact_evidence_basis,- get_artifact_presentation,- get_artifact_type,- get_tool_catalog,- get_tool_schemas_for_llm,+from repowise.server.chat_session import (+ DEFAULT_POLICY,+ WEB_POLICY,+ ChatSession,+ IdempotencyConflictError,+ SessionNotFoundError,)-from repowise.server.chat_views import SHOW_VIEW_TOOL, TurnViews, show_view_schema+from repowise.server.chat_suggestions import page_suggestionsfrom repowise.server.deps import (get_db_session,request_principal,resolve_request_session_factory,+ resolve_session_factory,verify_api_key,)from repowise.server.provider_config import get_chat_provider_instance@@ -65,7 +59,14 @@ from repowise.server.schemas import (ConversationUpdateRequest,OkResponse,)-from repowise.server.schemas.chat import ChatPageContext+from repowise.server.schemas.chat import (+ ChatPageContext,+ ChatSessionMessageRequest,+ ChatSessionOpenRequest,+ ChatSessionPolicyRequest,+ ChatSessionResponse,+ ChatTurnResultResponse,+)logger = logging.getLogger(__name__)@@ -75,8 +76,6 @@ router = APIRouter(dependencies=[Security(verify_api_key, scopes=[PER_CALL_TOOL_SCOPE])],)-_MAX_AGENTIC_LOOPS = 10-async def _get_repo_info(factory: Any, repo_id: str) -> tuple[str, str]:"""Get repo name and path from DB."""@@ -87,11 +86,6 @@ async def _get_repo_info(factory: Any, repo_id: str) -> tuple[str, str]:return repo.name, repo.local_path-# ----------------------------------------------------------------------------# SSE Chat Endpoint-# -----------------------------------------------------------------------------def _workspace_alias(request: Request, repo_path: str, repo_name: str) -> str | None:"""Return the workspace alias owning *repo_path*, or None outside a workspace.@@ -124,369 +118,35 @@ def _is_live(conv: Any, repo_id: str) -> bool:return bool(conv) and conv.repository_id == repo_id and conv.deleted_at is None-async def _open_conversation(- factory: Any, repo_id: str, body: ChatRequest-) -> tuple[str, str, bool] | None:- """Load or create the turn's conversation and save the user message.-- Returns ``(conversation_id, user_message_id, created)``, or None when the- requested conversation is not a live one of this repo.- """- async with get_session(factory) as session:- created = not body.conversation_id- if created:- # Placeholder; refined once the turn's tools are known.- conv = await crud.create_conversation(- session,- repository_id=repo_id,- title=" ".join(body.message.split()[:6]),- )- else:- conv = await crud.get_conversation(session, body.conversation_id)- if not _is_live(conv, repo_id):- return None- user_msg = await crud.create_chat_message(- session,- conversation_id=conv.id,- role="user",- content={"text": body.message},- )- return conv.id, user_msg.id, created---async def _llm_history(factory: Any, conv_id: str, page_context: Any) -> list[dict[str, Any]]:- async with get_session(factory) as session:- db_messages = await crud.list_chat_messages(session, conv_id)- llm_messages = _db_messages_to_llm_format(db_messages)- return _with_navigation_context(llm_messages, page_context)---async def _save_reply(- factory: Any, conv_id: str, content: dict[str, Any], opening_message: str | None-) -> str:- """Store the assistant message; *opening_message* titles a new conversation."""- async with get_session(factory) as session:- msg = await crud.create_chat_message(- session,- conversation_id=conv_id,- role="assistant",- content=content,- )- await crud.touch_conversation(session, conv_id)- # Opening turn only, so a later rename is never overwritten.- if opening_message is not None:- await crud.update_conversation_title(- session,- conv_id,- conversation_title(opening_message, tool_names(content["tool_calls"])),- )- return msg.id---class _AgentTurn:- """One assistant turn: the model and tool loop, and what it records.-- ``aborted`` is set when the client disconnects or the provider fails, in- which case nothing is saved; ``truncated`` when the loop cap is reached.- """-- def __init__(- self,- repo_path: str,- repo_alias: str | None,- provider: ChatProvider,- llm_messages: list[dict[str, Any]],- principal: Any = None,- repo_id: str | None = None,- ) -> None:- self.repo_path = repo_path- self.repo_alias = repo_alias- self.principal = principal- self.repo_id = repo_id- self.provider = provider- self.llm_messages = llm_messages- self.text_parts: list[str] = []- self.provider_content: list[dict[str, Any]] | None = None- self.tool_calls: list[dict[str, Any]] = []- self.aborted = False- self.truncated = False- self.views = TurnViews()-- async def execute(self, name: str, args: dict) -> dict:- """Run one tool scoped to this repo; also handed to providers that loop internally."""- if name == SHOW_VIEW_TOOL:- return self.views.show(args)- result = await execute_tool(- name,- args,- repo_path=self.repo_path,- repo=self.repo_alias,- principal=self.principal,- repo_id=self.repo_id,- )- return self.views.record(- name,- args,- result,- artifact_type=get_artifact_type(name, self.repo_path),- evidence_basis=get_artifact_evidence_basis(name, self.repo_path),- )-- async def ground(self, page_context: Any, tool_catalog: list) -> str | None:- """Make the one read the page already justifies, before the first model turn.-- A repeat of a call the history already holds is skipped.- """- plan = plan_grounding(page_context, (tool.entry for tool in tool_catalog))- if plan is not None and _history_has_call(self.llm_messages, plan.tool_name, plan.arguments):- plan = None- grounding = await run_grounding(plan, self.execute, unstamp=self.views.unstamp)- if grounding is None:- return None- self.llm_messages.extend(grounding.llm_messages())- self.tool_calls.append(- _stored_tool_call(- grounding.tool_id,- grounding.tool_name,- grounding.arguments,- grounding.summary,- grounding.artifact,- origin="grounding",- )- )- return _sse_event("data", grounding.sse_payload())-- async def run(- self, request: Request, system_prompt: str, tool_schemas: list- ) -> AsyncIterator[str]:- """Alternate model turns and tool runs until the model answers."""- for _ in range(_MAX_AGENTIC_LOOPS):- pending: list[dict[str, Any]] = []- async for sse in self._model_turn(request, system_prompt, tool_schemas, pending):- yield sse- if self.aborted or not pending:- return- async for sse in self._run_pending(pending):- yield sse- # Every turn ended in a tool call, so no final answer exists.- self.truncated = True- yield _sse_event("data", {"type": "truncated", "loops": _MAX_AGENTIC_LOOPS})-- def reply_content(self) -> dict[str, Any]:- content: dict[str, Any] = {- "text": "".join(self.text_parts),- "tool_calls": self.tool_calls,- "provider": self.provider.provider_name,- "model": self.provider.model_name,- }- if self.truncated:- content["truncated"] = True- if self.views.parts:- content["views"] = self.views.parts- # A turn that read nothing, or read only failures, has no next- # step to propose.- follow_ups = follow_up_suggestions(self.tool_calls)- if follow_ups:- content["follow_ups"] = follow_ups- return content-- async def _model_turn(- self,- request: Request,- system_prompt: str,- tool_schemas: list,- pending: list[dict[str, Any]],- ) -> AsyncIterator[str]:- """Stream one provider call, collecting the tool calls left to us in *pending*."""- try:- async for event in self.provider.stream_chat(- messages=self.llm_messages,- tools=tool_schemas,- system_prompt=system_prompt,- max_tokens=8192,- temperature=0.7,- tool_executor=self.execute,- ):- if await request.is_disconnected():- self.aborted = True- return- sse = self._on_provider_event(event, pending)- if sse is not None:- yield sse- except ProviderError as exc:- self.aborted = True- yield _sse_event("data", {"type": "error", "message": str(exc)})-- def _on_provider_event(self, event: Any, pending: list[dict[str, Any]]) -> str | None:- if event.type == "text_delta" and event.text:- self.text_parts.append(event.text)- return _sse_event("data", {"type": "text_delta", "text": event.text})- if event.type == "assistant_content":- self.provider_content = event.content_blocks- return None- tc = event.tool_call- if not tc:- return None- if event.type == "tool_start":- pending.append({"id": tc.id, "name": tc.name, "arguments": tc.arguments})- return _sse_event(- "data",- {- "type": "tool_start",- "tool_id": tc.id,- "tool_name": tc.name,- "input": tc.arguments,- },- )- if event.type == "tool_result":- # The provider already ran this tool (e.g. Gemini), so it leaves the pending list.- pending[:] = [p for p in pending if p["id"] != tc.id]- return self._tool_result(tc.id, tc.name, tc.arguments, event.tool_result_data or {})- return None-- async def _run_pending(self, pending: list[dict[str, Any]]) -> AsyncIterator[str]:- """Run the tool calls the provider left to us and feed the results back."""- self.llm_messages.append(- assistant_tool_call_message(- "".join(self.text_parts), pending, provider_content=self.provider_content- )- )- self.text_parts.clear()- self.provider_content = None- for tc in pending:- result = await self.execute(tc["name"], tc["arguments"])- yield self._tool_result(tc["id"], tc["name"], tc["arguments"], result)- self.llm_messages.append(tool_result_message(tc["id"], tc["name"], result))-- def _tool_result(- self, tool_id: str, name: str, arguments: dict[str, Any], result: dict[str, Any]- ) -> str:- """Record one tool result as a stored call and return its SSE event."""- artifact_type = get_artifact_type(name, self.repo_path)- artifact_id, data = self.views.unstamp(result)- summary = _build_tool_summary(name, data)- artifact = create_artifact_envelope(- tool_name=name,- artifact_type=artifact_type,- presentation=get_artifact_presentation(name, self.repo_path),- data=data,- title=summary,- artifact_id=artifact_id,- evidence_basis=get_artifact_evidence_basis(name, self.repo_path),- )- self.tool_calls.append(_stored_tool_call(tool_id, name, arguments, summary, artifact))- sse = _sse_event(- "data",- {- "type": "tool_result",- "tool_id": tool_id,- "tool_name": name,- "summary": summary,- "artifact": artifact,- },- )- view = self.views.event(tool_id, result) if name == SHOW_VIEW_TOOL else None- return sse if view is None else sse + _sse_event("data", view)--[email protected]("/api/repos/{repo_id}/chat/messages")-async def chat_messages(repo_id: str, body: ChatRequest, request: Request):- """Stream an agentic chat response via SSE."""- # In workspace mode each repo has its own ``wiki.db``, so every session- # this request opens must come from the factory resolved by ``repo_id``.- factory = resolve_request_session_factory(request)-- repo_name, repo_path = await _get_repo_info(factory, repo_id)- # In workspace mode the MCP tools address repos by alias, not by the id- # in this URL, so resolve it once and scope every tool call to it.- repo_alias = _workspace_alias(request, repo_path, repo_name)- principal = request_principal(request)-- # An override (the UI model picker) applies to this request only; without- # one the repo's own config and ``.env`` pick the provider, as for update.+def _chat_provider(+ repo_path: str, repo_id: str, provider: str | None, model: str | None+) -> ChatProvider:+ """The provider for one request. An override (the UI model picker) applies to+ this request only; without one the repo's config and ``.env`` pick it."""try:- provider = get_chat_provider_instance(+ instance = get_chat_provider_instance(repo_path=repo_path,repo_id=repo_id,- provider_override=body.provider,- model_override=body.model,+ provider_override=provider,+ model_override=model,)except ValueError as exc:# Unknown provider override, or no provider resolvable at all.raise HTTPException(400, str(exc)) from excexcept Exception as exc:raise HTTPException(422, f"No chat provider available: {exc}") from exc-- if not isinstance(provider, ChatProvider):+ if not isinstance(instance, ChatProvider):raise HTTPException(422,- f"Provider '{provider.provider_name}' does not support streaming chat. "+ f"Provider '{instance.provider_name}' does not support streaming chat. ""Configure a provider that supports tool use (Anthropic, OpenAI, Gemini).",)+ return instance- async def event_stream():- try:- yield "retry: 3000\n\n"-- opened = await _open_conversation(factory, repo_id, body)- if opened is None:- yield _sse_event("data", {"type": "error", "message": "Conversation not found"})- return- conv_id, user_msg_id, created = opened-- llm_messages = await _llm_history(factory, conv_id, body.context)- tool_catalog = get_tool_catalog(repo_path, principal)- system_prompt = _build_system_prompt(repo_name, repo_path, tool_catalog, body.context)- tool_schemas = get_tool_schemas_for_llm(repo_path, principal)- if tool_catalog:- tool_schemas.append(- show_view_schema([tool.entry.artifact_type for tool in tool_catalog])- )-- turn = _AgentTurn(- repo_path, repo_alias, provider, llm_messages, principal=principal, repo_id=repo_id- )- grounded = await turn.ground(body.context, tool_catalog)- if grounded is not None:- yield grounded- async for sse in turn.run(request, system_prompt, tool_schemas):- yield sse- if turn.aborted:- return-- content = turn.reply_content()- msg_id = await _save_reply(- factory, conv_id, content, body.message if created else None- )- if "follow_ups" in content:- yield _sse_event(- "data", {"type": "suggestions", "suggestions": content["follow_ups"]}- )-- yield _sse_event(- "data",- {- "type": "done",- "conversation_id": conv_id,- "message_id": msg_id,- "user_message_id": user_msg_id,- "provider": provider.provider_name,- "model": provider.model_name,- },- )-- except Exception as exc:- logger.exception("Chat stream error")- yield _sse_event(- "data",- {- "type": "error",- "message": f"Internal error: {type(exc).__name__}: {exc}",- },- )+def _sse_response(events: AsyncIterator[str]) -> StreamingResponse:return StreamingResponse(- event_stream(),+ events,media_type="text/event-stream",headers={# no-transform keeps the Next.js rewrite proxy's compression@@ -498,6 +158,72 @@ async def chat_messages(repo_id: str, body: ChatRequest, request: Request):)+async def _session_sse(open_session: Any, run: Any) -> AsyncIterator[str]:+ """Open the session inside the stream, so a missing conversation or a+ failure to open still ends the stream with a typed ``error`` event."""+ yield "retry: 3000\n\n"+ try:+ session = await open_session()+ except SessionNotFoundError as exc:+ yield _sse_event("data", {"type": "error", "message": str(exc)})+ return+ except Exception as exc:+ logger.exception("Chat session open error")+ yield _sse_event(+ "data", {"type": "error", "message": f"Internal error: {type(exc).__name__}: {exc}"}+ )+ return+ try:+ async for event in run(session):+ yield _sse_event("data", event)+ except IdempotencyConflictError as exc:+ # Checked before the response; only a concurrent send reaches this.+ yield _sse_event("data", {"type": "error", "message": str(exc)})+++# ---------------------------------------------------------------------------+# SSE chat for the web client+# ---------------------------------------------------------------------------++[email protected]("/api/repos/{repo_id}/chat/messages")+async def chat_messages(repo_id: str, body: ChatRequest, request: Request):+ """Stream an agentic chat response via SSE."""+ # In workspace mode each repo has its own ``wiki.db``, so every session+ # this request opens must come from the factory resolved by ``repo_id``.+ factory = resolve_request_session_factory(request)+ repo_name, repo_path = await _get_repo_info(factory, repo_id)+ provider = _chat_provider(repo_path, repo_id, body.provider, body.model)+ scope = SessionScope(+ kind="repo",+ repo_id=repo_id,+ repo_name=repo_name,+ repo_path=repo_path,+ # In workspace mode the MCP tools address repos by alias, not by the+ # id in this URL, so every tool call is scoped to it.+ repo_alias=_workspace_alias(request, repo_path, repo_name),+ storage=factory,+ )++ async def open_session() -> ChatSession:+ return await ChatSession.open(+ scope=scope,+ provider=provider,+ principal=request_principal(request),+ fallback_policy=WEB_POLICY,+ conversation_id=body.conversation_id,+ # Placeholder; the opening turn retitles it from what it read.+ title=" ".join(body.message.split()[:6]),+ )++ def run(session: ChatSession) -> AsyncIterator[dict[str, Any]]:+ return session.stream(+ body.message, context=body.context, is_cancelled=request.is_disconnected+ )++ return _sse_response(_session_sse(open_session, run))++@router.get("/api/repos/{repo_id}/chat/suggestions",response_model=ChatSuggestionsResponse,@@ -513,14 +239,14 @@ async def chat_suggestions():"""Questions this page has earned, from the read a first question makes.- Goes through the same two grounding functions ``chat_messages`` uses, so the- two can never map a page kind differently, and makes no model call. Returns- the measured tier only: an empty list leaves the client's static tier- standing rather than restating copy the UI already ships.+ Goes through the same grounding functions and tool backend a chat turn+ uses, so the two can never map a page kind differently, and makes no+ model call. Returns the measured tier only: an empty list leaves the+ client's static tier standing rather than restating copy the UI already+ ships."""factory = resolve_request_session_factory(request)repo_name, repo_path = await _get_repo_info(factory, repo_id)- repo_alias = _workspace_alias(request, repo_path, repo_name)try:context = ChatPageContext(kind=kind, label=kind, target=target)@@ -530,17 +256,21 @@ async def chat_suggestions(return {"suggestions": []}principal = request_principal(request)- tool_catalog = get_tool_catalog(repo_path, principal)- plan = plan_grounding(context, (tool.entry for tool in tool_catalog))+ scope = SessionScope(+ kind="repo",+ repo_id=repo_id,+ repo_name=repo_name,+ repo_path=repo_path,+ repo_alias=_workspace_alias(request, repo_path, repo_name),+ storage=factory,+ )+ tools = tool_backends.get()(scope, principal)+ catalog = [t for t in tools.catalog_for(WEB_POLICY, principal) if WEB_POLICY.admits(t)]+ plan = plan_grounding(context, (tool.entry for tool in catalog))if plan is None:return {"suggestions": []}- async def _execute(name: str, args: dict) -> dict:- return await execute_tool(- name, args, repo_path=repo_path, repo=repo_alias, principal=principal, repo_id=repo_id- )-- grounding = await run_grounding(plan, _execute)+ grounding = await run_grounding(plan, tools.execute)if grounding is None:return {"suggestions": []}return {@@ -550,6 +280,204 @@ async def chat_suggestions(}+# ---------------------------------------------------------------------------+# Headless sessions+# ---------------------------------------------------------------------------+++def _requested_policy(requested: ChatSessionPolicyRequest | None) -> SessionPolicy:+ """The default session policy narrowed by *requested*; widening is refused."""+ base = DEFAULT_POLICY+ if requested is None:+ return base+ caps = {+ "max_tool_loops": base.max_tool_loops,+ "max_output_tokens": base.max_output_tokens,+ }+ for name, cap in caps.items():+ value = getattr(requested, name)+ if value is not None and value > cap:+ raise HTTPException(422, f"policy.{name} may not exceed {cap}")+ values = {+ name: value+ for name, value in requested.model_dump(exclude_none=True).items()+ if name != "tool_allowlist"+ }+ if requested.tool_allowlist is not None:+ values["tool_allowlist"] = frozenset(requested.tool_allowlist)+ return SessionPolicy(**{**asdict(base), **values})+++def _require_repo_access(principal: Principal | None, repo_id: str, repo_name: str) -> None:+ if principal is not None and not get_authorizer().can_access_repo(+ principal, (repo_id, repo_name)+ ):+ raise HTTPException(403, "Repository is outside this credential's scope")+++def _index_factories(request: Request) -> list[Any]:+ """Every index database this server serves: the primary, then each workspace repo's."""+ state = request.app.state+ factories = [state.session_factory]+ for factory in (getattr(state, "workspace_sessions", None) or {}).values():+ if all(factory is not seen for seen in factories):+ factories.append(factory)+ return factories+++def _lookup_store(factory: Any) -> Any:+ """A store over *factory* for finding a conversation before its repo is known."""+ return conversation_stores.get()(+ SessionScope(kind="repo", repo_id="", repo_name="", repo_path="", storage=factory)+ )+++def _session_response(+ conv: StoredConversation, *, created: bool = False+) -> ChatSessionResponse:+ policy = SessionPolicy.from_json(conv.policy_json, default=DEFAULT_POLICY)+ return ChatSessionResponse(+ id=conv.id,+ repository_id=conv.repository_id,+ title=conv.title,+ scope=conv.scope.get("kind", "repo"),+ namespace=conv.namespace,+ external_ref=conv.external_ref,+ created=created,+ policy=json.loads(policy.to_json()),+ turns=conv.turns,+ input_tokens=conv.input_tokens,+ output_tokens=conv.output_tokens,+ )+++async def _session_scope(+ request: Request, repo_id: str, kind: str, alias: str | None = None+) -> SessionScope:+ factory = resolve_session_factory(request.app.state, repo_id)+ repo_name, repo_path = await _get_repo_info(factory, repo_id)+ _require_repo_access(request_principal(request), repo_id, repo_name)+ if kind == "workspace" and getattr(request.app.state, "workspace_config", None) is None:+ raise HTTPException(422, "A workspace session needs a server started on a workspace")+ if kind == "repo" and alias is None:+ alias = _workspace_alias(request, repo_path, repo_name)+ return SessionScope(+ kind=kind, # type: ignore[arg-type]+ repo_id=repo_id,+ repo_name=repo_name,+ repo_path=repo_path,+ repo_alias=alias if kind == "repo" else None,+ storage=factory,+ )++[email protected]("/api/chat/sessions", response_model=ChatSessionResponse)+async def open_chat_session(body: ChatSessionOpenRequest, request: Request):+ """Open a session, or resume the one ``(namespace, external_ref)`` names.++ A resumed session keeps the policy it was opened with.+ """+ scope = await _session_scope(request, body.repo_id, body.scope)+ try:+ session = await ChatSession.open(+ scope=scope,+ principal=request_principal(request),+ policy=_requested_policy(body.policy),+ namespace=body.namespace if body.external_ref else None,+ external_ref=body.external_ref,+ title=body.title or "New conversation",+ )+ except SessionNotFoundError as exc:+ raise HTTPException(404, str(exc)) from exc+ return _session_response(session.conversation, created=session.created)++[email protected]("/api/chat/sessions", response_model=list[ChatSessionResponse])+async def find_chat_sessions(request: Request, external_ref: str, namespace: str = "default"):+ """The live session a caller's thread key names, as a list of zero or one."""+ principal = request_principal(request)+ for factory in _index_factories(request):+ conv = await _lookup_store(factory).find(namespace, external_ref)+ if conv is None or conv.deleted:+ continue+ async with get_session(factory) as session:+ repo = await crud.get_repository(session, conv.repository_id)+ if repo is None:+ continue+ if principal is not None and not get_authorizer().can_access_repo(+ principal, (repo.id, repo.name)+ ):+ return []+ return [_session_response(conv)]+ return []+++async def _find_session(request: Request, session_id: str) -> StoredConversation:+ for factory in _index_factories(request):+ conv = await _lookup_store(factory).get(session_id)+ if conv is not None and not conv.deleted:+ return conv+ raise HTTPException(404, "Session not found")+++ "/api/chat/sessions/{session_id}/messages",+ response_model=ChatTurnResultResponse,+ responses={+ 200: {"content": {"text/event-stream": {}}},+ 409: {"description": "The idempotency key was already sent with another message"},+ },+)+async def send_chat_session_message(+ session_id: str, body: ChatSessionMessageRequest, request: Request+):+ """Run one turn: SSE events when ``stream`` is true, else the turn's result."""+ conv = await _find_session(request, session_id)+ scope = await _session_scope(+ request, conv.repository_id, conv.scope.get("kind", "repo"), conv.scope.get("alias")+ )+ provider = _chat_provider(scope.repo_path, scope.repo_id, body.provider, body.model)++ try:+ session = await ChatSession.open(+ scope=scope,+ provider=provider,+ principal=request_principal(request),+ conversation_id=session_id,+ )+ await session.check_send(body.message, body.idempotency_key)+ except SessionNotFoundError as exc:+ raise HTTPException(404, str(exc)) from exc+ except IdempotencyConflictError as exc:+ raise HTTPException(409, str(exc)) from exc++ async def opened() -> ChatSession:+ return session++ if body.stream:+ return _sse_response(+ _session_sse(+ opened,+ lambda session: session.stream(+ body.message,+ context=body.context,+ idempotency_key=body.idempotency_key,+ is_cancelled=request.is_disconnected,+ ),+ )+ )+ try:+ result = await session.send(+ body.message,+ context=body.context,+ idempotency_key=body.idempotency_key,+ is_cancelled=request.is_disconnected,+ )+ except IdempotencyConflictError as exc: # a concurrent send won the key+ raise HTTPException(409, str(exc)) from exc+ return ChatTurnResultResponse.model_validate(asdict(result))++# ---------------------------------------------------------------------------# Conversation history endpoints# ---------------------------------------------------------------------------@@ -724,28 +652,3 @@ async def fork_conversation(def _sse_event(event: str, data: dict[str, Any]) -> str:"""Format a single SSE event."""return f"event: {event}\ndata: {json.dumps(data)}\n\n"---def _stored_tool_call(- tool_id: str,- name: str,- arguments: dict[str, Any],- summary: str,- artifact: dict[str, Any],- origin: str | None = None,-) -> dict[str, Any]:- """Persist one durable artifact payload with the assistant message.-- ``origin`` marks a call the server made for the page rather than the- model; absent for model-made calls so stored rows keep their shape.- """- stored = {- "id": tool_id,- "name": name,- "arguments": arguments,- "summary": summary,- "artifact": artifact,- }- if origin:- stored["origin"] = origin- return storeddiff --git a/packages/server/src/repowise/server/schemas/chat.py b/packages/server/src/repowise/server/schemas/chat.pyindex 85eb4fa40..300da7e1b 100644--- a/packages/server/src/repowise/server/schemas/chat.py+++ b/packages/server/src/repowise/server/schemas/chat.py@@ -167,3 +167,94 @@ class ChatSuggestionsResponse(BaseModel):class ConversationDetailResponse(BaseModel):conversation: ConversationResponsemessages: list[ChatMessageResponse] = []+++# ---------------------------------------------------------------------------+# Headless chat sessions+# ---------------------------------------------------------------------------+++class ChatSessionPolicyRequest(BaseModel):+ """Limits a caller asks for. Each may only narrow the server's default+ session policy; a wider value is refused."""++ tool_allowlist: list[str] | None = None+ max_tool_loops: int | None = Field(default=None, ge=1)+ max_turns: int | None = Field(default=None, ge=1)+ max_output_tokens: int | None = Field(default=None, ge=1)+ max_turn_tokens: int | None = Field(default=None, ge=1)+ max_session_tokens: int | None = Field(default=None, ge=1)+ audience: Literal["engineer", "business"] | None = None+++class ChatSessionOpenRequest(BaseModel):+ """Open a session, or resume the one ``(namespace, external_ref)`` names."""++ repo_id: str+ scope: Literal["repo", "workspace"] = "repo"+ namespace: str = Field(default="default", min_length=1, max_length=128)+ external_ref: str | None = Field(default=None, min_length=1, max_length=512)+ title: str | None = Field(default=None, min_length=1, max_length=200)+ policy: ChatSessionPolicyRequest | None = None+++class ChatSessionResponse(BaseModel):+ id: str+ repository_id: str+ title: str+ scope: Literal["repo", "workspace"]+ namespace: str | None = None+ external_ref: str | None = None+ #: True when this call created the conversation.+ created: bool = False+ policy: dict[str, Any] = {}+ turns: int = 0+ input_tokens: int = 0+ output_tokens: int = 0+++class ChatSessionMessageRequest(BaseModel):+ message: str = Field(min_length=1, max_length=32_000)+ #: A retried send with the same key returns the stored reply.+ idempotency_key: str | None = Field(default=None, min_length=1, max_length=128)+ context: ChatPageContext | None = None+ #: True streams the turn as SSE events; false returns one ``ChatTurnResultResponse``.+ stream: bool = False+ provider: str | None = None+ model: str | None = None+++class ChatToolTraceEntry(BaseModel):+ name: str+ summary: str+ ok: bool+ basis: str+ origin: str | None = None+++class ChatTurnUsage(BaseModel):+ """Null token counts mean the provider reported none."""++ input_tokens: int | None = None+ output_tokens: int | None = None+ model_calls: int = 0+++class ChatTurnResultResponse(BaseModel):+ conversation_id: str+ message_id: str | None = None+ user_message_id: str | None = None+ answer: str+ stop_reason: Literal[+ "answered", "loop_cap", "token_budget", "turn_budget", "refused", "cancelled", "error"+ ]+ provider: str+ model: str+ citations: list[dict[str, Any]] = []+ cards: list[dict[str, Any]] = []+ views: list[dict[str, Any]] = []+ tool_trace: list[ChatToolTraceEntry] = []+ follow_ups: list[ChatSuggestion] = []+ usage: ChatTurnUsage = ChatTurnUsage()+ error: str | None = None+ replayed: bool = Falsediff --git a/packages/types/src/chat.ts b/packages/types/src/chat.tsindex 9755609d6..23a998c09 100644--- a/packages/types/src/chat.ts+++ b/packages/types/src/chat.ts@@ -14,6 +14,17 @@ import type { DecisionRecord } from "./decisions.js";import type { EvidenceCard } from "./cards.js";import type { ViewPart } from "./views.js";+/** Headless chat session wire types, generated from the server schema. */+export type {+ ChatSessionMessageRequest,+ ChatSessionOpenRequest,+ ChatSessionPolicyRequest,+ ChatSessionResponse,+ ChatToolTraceEntry,+ ChatTurnResultResponse,+ ChatTurnUsage,+} from "./generated/http.js";+// ---------------------------------------------------------------------------// Product context surrounding a chat composer// ---------------------------------------------------------------------------@@ -698,10 +709,11 @@ export type ChatSSEEvent =/** A table or chart the server built from a tool result of this turn,* sent right after the `show_view` call's `tool_result`. */| { type: "view"; tool_id: string; view: ViewPart }- /** Every turn ended in a tool call; `done` still follows. */- | { type: "truncated"; loops: number }+ /** A limit stopped the turn before a final answer; `done` still follows.+ * `reason` is `loop_cap` (every call ended in a tool call) or `token_budget`. */+ | { type: "truncated"; loops: number; reason?: "loop_cap" | "token_budget" }/** Next steps for the turn that just finished, sent just before `done`.* A turn that failed or called no tool sends none. */| { type: "suggestions"; suggestions: ChatSuggestion[] }- | { type: "done"; conversation_id: string; message_id: string; user_message_id?: string; provider?: string; model?: string }+ | { type: "done"; conversation_id: string; message_id: string; user_message_id?: string; provider?: string; model?: string; replayed?: boolean }| { type: "error"; message: string };diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex ca2a98ab5..65824ff42 100644--- a/packages/types/src/generated/http.ts+++ b/packages/types/src/generated/http.ts@@ -521,6 +521,53 @@ export interface ChatRequest {context?: ChatPageContext | null;}+export interface ChatSessionMessageRequest {+ message: string;+ idempotency_key?: string | null;+ context?: ChatPageContext | null;+ stream?: boolean;+ provider?: string | null;+ model?: string | null;+}++/** Open a session, or resume the one ``(namespace, external_ref)`` names. */+export interface ChatSessionOpenRequest {+ repo_id: string;+ scope?: "repo" | "workspace";+ namespace?: string;+ external_ref?: string | null;+ title?: string | null;+ policy?: ChatSessionPolicyRequest | null;+}++/**+ * Limits a caller asks for. Each may only narrow the server's default+ * session policy; a wider value is refused.+ */+export interface ChatSessionPolicyRequest {+ tool_allowlist?: string[] | null;+ max_tool_loops?: number | null;+ max_turns?: number | null;+ max_output_tokens?: number | null;+ max_turn_tokens?: number | null;+ max_session_tokens?: number | null;+ audience?: "engineer" | "business" | null;+}++export interface ChatSessionResponse {+ id: string;+ repository_id: string;+ title: string;+ scope: "repo" | "workspace";+ namespace?: string | null;+ external_ref?: string | null;+ created?: boolean;+ policy?: Record<string, unknown>;+ turns?: number;+ input_tokens?: number;+ output_tokens?: number;+}+/*** One composer chip. ``source`` lets a client rank a measured question* above the static tier it already ships.@@ -539,6 +586,39 @@ export interface ChatSuggestionsResponse {suggestions?: ChatSuggestion[];}+export interface ChatToolTraceEntry {+ name: string;+ summary: string;+ ok: boolean;+ basis: string;+ origin?: string | null;+}++export interface ChatTurnResultResponse {+ conversation_id: string;+ message_id?: string | null;+ user_message_id?: string | null;+ answer: string;+ stop_reason: "answered" | "loop_cap" | "token_budget" | "turn_budget" | "refused" | "cancelled" | "error";+ provider: string;+ model: string;+ citations?: Record<string, unknown>[];+ cards?: Record<string, unknown>[];+ views?: Record<string, unknown>[];+ tool_trace?: ChatToolTraceEntry[];+ follow_ups?: ChatSuggestion[];+ usage?: ChatTurnUsage;+ error?: string | null;+ replayed?: boolean;+}++/** Null token counts mean the provider reported none. */+export interface ChatTurnUsage {+ input_tokens?: number | null;+ output_tokens?: number | null;+ model_calls?: number;+}+/*** One file on the churn-vs-complexity scatter.*diff --git a/tests/unit/server/test_chat_change_risk_summary.py b/tests/unit/server/test_chat_change_risk_summary.pyindex 3caade999..b85bbfec9 100644--- a/tests/unit/server/test_chat_change_risk_summary.py+++ b/tests/unit/server/test_chat_change_risk_summary.py@@ -2,8 +2,8 @@from __future__ import annotations+from repowise.server.chat_summaries import _build_tool_summaryfrom repowise.server.chat_tools import get_tool_catalog-from repowise.server.routers.chat import _build_tool_summarydef test_get_change_risk_summary_is_not_generic_completed():diff --git a/tests/unit/server/test_chat_router.py b/tests/unit/server/test_chat_router.pyindex 44f57e362..f7a503f19 100644--- a/tests/unit/server/test_chat_router.py+++ b/tests/unit/server/test_chat_router.py@@ -10,8 +10,9 @@ import pytestfrom httpx import ASGITransport, AsyncClientfrom repowise.core.providers.llm.base import ChatStreamEvent, ChatToolCall, ProviderError+from repowise.server.chat_prompt import _build_system_prompt+from repowise.server.chat_session import WEB_POLICYfrom repowise.server.chat_tools import get_tool_catalog-from repowise.server.routers.chat import _MAX_AGENTIC_LOOPS, _build_system_promptfrom repowise.server.schemas.chat import ChatPageContextfrom tests.unit.server.test_chat_stream_terminal_event import (_REPO_ID,@@ -21,7 +22,8 @@ from tests.unit.server.test_chat_stream_terminal_event import ()_PROVIDER = "repowise.server.routers.chat.get_chat_provider_instance"-_EXECUTE = "repowise.server.routers.chat.execute_tool"+_EXECUTE = "repowise.server.chat_tools.execute_tool"+_MAX_AGENTIC_LOOPS = WEB_POLICY.max_tool_loops_FILE_PAGE = {"kind": "file", "label": "Files", "target": "src/a.py", "target_kind": "path"}_CONTEXT_RESULT = {"targets": {"src/a.py": {"docs": {"title": "A", "content_md": "alpha"}}}}diff --git a/tests/unit/server/test_chat_session.py b/tests/unit/server/test_chat_session.pynew file mode 100644index 000000000..927f012a5--- /dev/null+++ b/tests/unit/server/test_chat_session.py@@ -0,0 +1,701 @@+"""Conformance suite for ChatSession and its seams.++Every test runs the real session engine against a scripted provider and a fake+``ToolBackend``; the store-dependent ones run against both an in-memory+``ConversationStore`` and the local SQL store, so another store can join the+``store`` fixture and must pass the same checks.+"""++from __future__ import annotations++import asyncio+import json+from collections.abc import AsyncIterator, Callable, Iterable+from dataclasses import replace+from typing import Any++import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine+from sqlalchemy.pool import StaticPool++from repowise.core.persistence.database import init_db+from repowise.core.persistence.models import Repository+from repowise.core.providers.llm.base import ChatStreamEvent, ChatToolCall, ProviderError+from repowise.core.registry import ToolEntry+from repowise.server.chat_context import (+ OVERFLOW_MESSAGE,+ bound_history,+ bound_tool_messages,+ compose_request,+)+from repowise.server.chat_seams import (+ ConversationStore,+ NoTurnHooks,+ SessionPolicy,+ SessionScope,+ StoredConversation,+ StoredMessage,+ ToolBackend,+ TurnUsage,+)+from repowise.server.chat_session import ChatSession, SessionNotFoundError+from repowise.server.chat_store import SqlConversationStore+from repowise.server.chat_tools import ChatToolContract+from repowise.server.chat_views import SHOW_VIEW_TOOL++_REPO_ID = "repo-1"+_SCOPE = SessionScope(kind="repo", repo_id=_REPO_ID, repo_name="demo", repo_path="/tmp/demo")+++# ---------------------------------------------------------------------------+# Fakes+# ---------------------------------------------------------------------------+++def _text(text: str) -> ChatStreamEvent:+ return ChatStreamEvent(type="text_delta", text=text)+++def _tool(tool_id: str, name: str, arguments: dict | None = None) -> ChatStreamEvent:+ return ChatStreamEvent(+ type="tool_start",+ tool_call=ChatToolCall(id=tool_id, name=name, arguments=arguments or {}),+ )+++def _usage(input_tokens: int, output_tokens: int) -> ChatStreamEvent:+ return ChatStreamEvent(type="usage", input_tokens=input_tokens, output_tokens=output_tokens)+++class ScriptedProvider:+ """Plays one scripted turn per call; a turn may be an exception to raise."""++ provider_name = "test"+ model_name = "test-model"++ def __init__(self, turns: Iterable[Any] | Callable[[int], Any]) -> None:+ self._turns = turns if callable(turns) else list(turns)+ self.calls: list[dict[str, Any]] = []++ async def stream_chat(self, **kwargs) -> AsyncIterator[ChatStreamEvent]:+ index = len(self.calls)+ self.calls.append(+ {+ "messages": [dict(m) for m in kwargs["messages"]],+ "tools": [t["function"]["name"] for t in kwargs["tools"]],+ "max_tokens": kwargs["max_tokens"],+ }+ )+ if callable(self._turns):+ turn = self._turns(index)+ else:+ turn = self._turns[index] if index < len(self._turns) else []+ if isinstance(turn, BaseException):+ raise turn+ for event in turn:+ yield event+++class FakeTools:+ """One read-only, one generative and one mutating tool; records every run."""++ def __init__(self) -> None:+ self.executed: list[str] = []+ self.catalog_requests: list[Any] = []++ def catalog_for(self, policy, principal) -> list[ChatToolContract]:+ self.catalog_requests.append(principal)+ risk = ToolEntry(+ fn=_noop,+ name="get_risk",+ artifact_type="risk",+ presentation="table",+ evidence_basis="measured",+ )+ return [+ ChatToolContract(entry=entry, description=entry.name, parameters={})+ for entry in (+ risk,+ ToolEntry(fn=_noop, name="get_context"),+ ToolEntry(fn=_noop, name="gen_code", safety="generative"),+ ToolEntry(fn=_noop, name="set_status", safety="mutating"),+ )+ ]++ async def execute(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:+ self.executed.append(name)+ return {"ok": True, "citations": ["src/a.py"], "files": [{"path": "src/a.py", "fixes": 3}]}+++async def _noop() -> dict:+ return {}+++class MemoryStore:+ """A ConversationStore with no database, the reference for the conformance suite."""++ def __init__(self) -> None:+ self.conversations: dict[str, StoredConversation] = {}+ self.messages_by_conv: dict[str, list[tuple[StoredMessage, str | None]]] = {}++ async def get_or_create(self, *, repository_id, title, scope, namespace, external_ref, principal_id, policy_json):+ if namespace is not None and external_ref is not None:+ found = await self.find(namespace, external_ref)+ if found is not None:+ return found, False+ conv = StoredConversation(+ id=f"c{len(self.conversations) + 1}",+ repository_id=repository_id,+ title=title,+ scope=scope,+ namespace=namespace,+ external_ref=external_ref,+ principal_id=principal_id,+ policy_json=policy_json,+ input_tokens=0,+ output_tokens=0,+ turns=0,+ deleted=False,+ )+ self.conversations[conv.id] = conv+ self.messages_by_conv[conv.id] = []+ return conv, True++ async def get(self, conversation_id):+ return self.conversations.get(conversation_id)++ async def find(self, namespace, external_ref):+ return next(+ (+ c+ for c in self.conversations.values()+ if c.namespace == namespace and c.external_ref == external_ref+ ),+ None,+ )++ async def messages(self, conversation_id):+ return [m for m, _ in self.messages_by_conv[conversation_id]]++ async def find_sent(self, conversation_id, idempotency_key):+ rows = self.messages_by_conv[conversation_id]+ for index, (message, key) in enumerate(rows):+ if key == idempotency_key:+ after = rows[index + 1 : index + 2]+ reply = after[0][0] if after and after[0][0].role == "assistant" else None+ return message, reply+ return None++ async def add_user_message(self, conversation_id, content, *, idempotency_key):+ return self._add(conversation_id, "user", content, idempotency_key)++ async def add_reply(self, conversation_id, content, *, title, usage):+ message_id = self._add(conversation_id, "assistant", content, None)+ conv = self.conversations[conversation_id]+ self.conversations[conversation_id] = replace(+ conv,+ title=title if title is not None else conv.title,+ turns=conv.turns + 1,+ input_tokens=conv.input_tokens + (usage.input_tokens or 0),+ output_tokens=conv.output_tokens + (usage.output_tokens or 0),+ )+ return message_id++ def _add(self, conversation_id, role, content, key) -> str:+ rows = self.messages_by_conv[conversation_id]+ message = StoredMessage(id=f"{conversation_id}-m{len(rows) + 1}", role=role, content=content)+ rows.append((message, key))+ return message.id+++async def _sql_store() -> SqlConversationStore:+ engine = create_async_engine(+ "sqlite+aiosqlite:///:memory:",+ connect_args={"check_same_thread": False},+ poolclass=StaticPool,+ )+ await init_db(engine)+ factory = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)+ async with factory() as session:+ session.add(+ Repository(+ id=_REPO_ID,+ name="demo",+ url="https://example.com/demo",+ local_path="/tmp/demo",+ default_branch="main",+ settings_json="{}",+ )+ )+ await session.commit()+ return SqlConversationStore(factory)++[email protected](params=["memory", "sql"])+async def store(request) -> ConversationStore:+ return MemoryStore() if request.param == "memory" else await _sql_store()+++async def _open(store, provider, *, policy=None, tools=None, hooks=None, **kwargs) -> ChatSession:+ return await ChatSession.open(+ scope=_SCOPE,+ provider=provider,+ policy=policy,+ store=store,+ tools=tools or FakeTools(),+ hooks=hooks or NoTurnHooks(),+ **kwargs,+ )+++async def _collect(stream: AsyncIterator[dict]) -> list[dict]:+ return [event async for event in stream]+++def test_the_fakes_satisfy_the_seam_protocols():+ assert isinstance(FakeTools(), ToolBackend)+ assert isinstance(MemoryStore(), ConversationStore)+++# ---------------------------------------------------------------------------+# Tool allowlist: what the model sees and what can run+# ---------------------------------------------------------------------------+++async def test_default_policy_shows_only_read_only_tools(store):+ provider = ScriptedProvider([[_text("hi")]])+ session = await _open(store, provider)++ await session.send("hello")++ assert provider.calls[0]["tools"] == ["get_risk", "get_context", SHOW_VIEW_TOOL]+++async def test_allowlist_narrows_the_schemas_sent_to_the_model(store):+ provider = ScriptedProvider([[_text("hi")]])+ session = await _open(store, provider, policy=SessionPolicy(tool_allowlist=frozenset({"get_risk"})))++ await session.send("hello")++ assert provider.calls[0]["tools"] == ["get_risk"]+++async def test_a_hidden_tool_named_by_the_model_never_runs(store):+ tools = FakeTools()+ provider = ScriptedProvider([[_tool("t1", "gen_code"), _tool("t2", "get_context")], [_text("done")]])+ session = await _open(+ store, provider, tools=tools, policy=SessionPolicy(tool_allowlist=frozenset({"get_risk", "gen_code"}))+ )++ result = await session.send("generate")++ # gen_code is allowlisted but above the read-only ceiling; get_context is+ # under the ceiling but not allowlisted. Neither reaches the backend.+ assert tools.executed == []+ errors = {t.name: t.ok for t in result.tool_trace}+ assert errors == {"gen_code": False, "get_context": False}+ tool_messages = [m for m in provider.calls[1]["messages"] if m["role"] == "tool"]+ assert all(json.loads(m["content"])["error_code"] == "tool_not_enabled" for m in tool_messages)+++async def test_artifact_metadata_comes_from_the_catalog_entry(store):+ provider = ScriptedProvider([[_tool("t1", "get_risk"), _tool("t2", "missing")], [_text("ok")]])+ session = await _open(store, provider)++ events = await _collect(session.stream("q"))++ artifacts = {e["tool_name"]: e["artifact"] for e in events if e["type"] == "tool_result"}+ assert (artifacts["get_risk"]["type"], artifacts["get_risk"]["presentation"]) == ("risk", "table")+ assert artifacts["get_risk"]["evidence"]["basis"] == "measured"+ assert (artifacts["missing"]["type"], artifacts["missing"]["presentation"]) == ("generic", "generic")+ assert artifacts["missing"]["evidence"]["basis"] == "unknown"+++async def test_the_catalog_is_asked_for_the_sessions_principal(store):+ from repowise.server.auth import Principal++ tools = FakeTools()+ principal = Principal("token:t", "token")+ session = await _open(store, ScriptedProvider([[_text("x")]]), tools=tools, principal=principal)++ await session.send("hi")++ assert tools.catalog_requests == [principal]+++# ---------------------------------------------------------------------------+# Limits and stop reasons+# ---------------------------------------------------------------------------+++async def test_the_loop_cap_stops_the_turn_and_says_so(store):+ provider = ScriptedProvider(lambda i: [_tool(f"t{i}", "get_risk")])+ session = await _open(store, provider, policy=SessionPolicy(max_tool_loops=3))++ events = await _collect(session.stream("loop"))+ result = await session.send("loop again")++ assert len(provider.calls) == 6+ truncated = next(e for e in events if e["type"] == "truncated")+ assert truncated == {"type": "truncated", "loops": 3, "reason": "loop_cap"}+ assert events[-1]["type"] == "done"+ assert result.stop_reason == "loop_cap"+ assert result.message_id is not None+++async def test_a_turn_token_budget_stops_before_the_next_model_call(store):+ provider = ScriptedProvider(lambda i: [_tool(f"t{i}", "get_risk"), _usage(400, 200)])+ session = await _open(store, provider, policy=SessionPolicy(max_turn_tokens=1000))++ result = await session.send("spend")++ assert len(provider.calls) == 2+ assert result.stop_reason == "token_budget"+ assert result.usage == TurnUsage(800, 400, 2)+++async def test_a_session_token_budget_refuses_the_next_turn(store):+ provider = ScriptedProvider(lambda i: [_text("ok"), _usage(700, 300)])+ session = await _open(store, provider, policy=SessionPolicy(max_session_tokens=1000))++ first = await session.send("one")+ second = await session.send("two")++ assert first.stop_reason == "answered"+ assert second.stop_reason == "token_budget"+ assert second.message_id is None+ assert len(provider.calls) == 1+++async def test_a_turn_budget_refuses_the_turn_after_the_last(store):+ provider = ScriptedProvider(lambda i: [_text("ok")])+ session = await _open(store, provider, policy=SessionPolicy(max_turns=1))++ await session.send("one")+ second = await session.send("two")++ assert second.stop_reason == "turn_budget"+ assert len(provider.calls) == 1+++async def test_usage_is_unknown_when_the_provider_reports_none(store):+ session = await _open(store, ScriptedProvider([[_text("ok")]]))++ result = await session.send("hi")++ assert result.usage == TurnUsage(None, None, 1)+++async def test_a_cancelled_turn_stores_no_reply(store):+ provider = ScriptedProvider([[_text("partial"), _text(" more")]])+ session = await _open(store, provider)+ calls = 0++ async def cancelled() -> bool:+ nonlocal calls+ calls += 1+ return calls > 1++ result = await session.send("hi", is_cancelled=cancelled)++ assert result.stop_reason == "cancelled"+ assert result.message_id is None+ assert [m.role for m in await store.messages(session.id)] == ["user"]+++async def test_preflight_refusal_runs_nothing(store):+ class Refusing(NoTurnHooks):+ async def preflight(self, principal, policy, conversation):+ return "allowance used up"++ provider = ScriptedProvider([[_text("never")]])+ session = await _open(store, provider, hooks=Refusing())++ events = await _collect(session.stream("hi"))++ assert events == [{"type": "error", "message": "allowance used up"}]+ assert provider.calls == []+ assert await store.messages(session.id) == []+++async def test_hooks_see_usage_and_can_add_events(store):+ seen: list[TurnUsage] = []++ class Metering(NoTurnHooks):+ async def on_usage(self, principal, conversation, usage):+ seen.append(usage)++ async def on_event(self, event):+ return [{"type": "allowance", "left": 1}] if event["type"] == "done" else []++ session = await _open(store, ScriptedProvider([[_text("ok"), _usage(5, 6)]]), hooks=Metering())++ events = await _collect(session.stream("hi"))++ assert seen == [TurnUsage(5, 6, 1)]+ assert [e["type"] for e in events][-2:] == ["done", "allowance"]+++# ---------------------------------------------------------------------------+# Conversations: get-or-create, idempotency, turn lock+# ---------------------------------------------------------------------------+++async def test_get_or_create_resumes_by_namespace_and_external_ref(store):+ provider = ScriptedProvider(lambda i: [_text("ok")])+ first = await _open(+ store, provider, namespace="bot", external_ref="T1/C2/123.4", policy=SessionPolicy(max_tool_loops=4)+ )+ again = await _open(+ store, provider, namespace="bot", external_ref="T1/C2/123.4", policy=SessionPolicy(max_tool_loops=9)+ )+ other = await _open(store, provider, namespace="other", external_ref="T1/C2/123.4")++ assert first.created and not again.created and other.created+ assert again.id == first.id != other.id+ # The policy is frozen when the conversation is created.+ assert again.policy.max_tool_loops == 4+++async def test_a_conversation_of_another_repository_is_not_found(store):+ session = await _open(store, ScriptedProvider([]))+ elsewhere = replace(_SCOPE, repo_id="repo-2")++ with pytest.raises(SessionNotFoundError):+ await ChatSession.open(+ scope=elsewhere, provider=ScriptedProvider([]), conversation_id=session.id, store=store, tools=FakeTools()+ )+++async def test_a_retried_send_returns_the_stored_reply(store):+ provider = ScriptedProvider(lambda i: [_tool(f"t{i}", "get_risk")] if i == 0 else [_text("answer")])+ session = await _open(store, provider)++ first = await session.send("q", idempotency_key="k1")+ events = await _collect(session.stream("q", idempotency_key="k1"))+ again = await session.send("q", idempotency_key="k1")++ assert len(provider.calls) == 2+ assert again.replayed and not first.replayed+ assert again.message_id == first.message_id+ assert again.answer == first.answer == "answer"+ assert again.citations == first.citations == [{"file_path": "src/a.py"}]+ assert events[-1]["type"] == "done" and events[-1]["replayed"] is True+ assert [m.role for m in await store.messages(session.id)] == ["user", "assistant"]+++async def test_a_retry_of_a_failed_send_runs_on_the_stored_question(store):+ provider = ScriptedProvider([ProviderError("test", "boom"), [_text("second try")]])+ session = await _open(store, provider)++ failed = await session.send("q", idempotency_key="k1")+ retried = await session.send("q", idempotency_key="k1")++ assert failed.stop_reason == "error" and failed.message_id is None+ assert retried.stop_reason == "answered" and retried.answer == "second try"+ assert retried.user_message_id == failed.user_message_id+ assert [m.role for m in await store.messages(session.id)] == ["user", "assistant"]+++async def test_turns_of_one_conversation_never_overlap(store):+ active = 0+ peak = 0++ class SlowProvider(ScriptedProvider):+ async def stream_chat(self, **kwargs):+ nonlocal active, peak+ active += 1+ peak = max(peak, active)+ await asyncio.sleep(0.01)+ active -= 1+ yield _text("ok")++ provider = SlowProvider([])+ session = await _open(store, provider)+ twin = await _open(store, provider, conversation_id=session.id)++ await asyncio.gather(session.send("a"), twin.send("b"), session.send("c"))++ assert peak == 1+ assert (await store.get(session.id)).turns == 3+++async def test_the_opening_turn_titles_the_conversation_and_later_ones_do_not(store):+ provider = ScriptedProvider(lambda i: [_text("ok")])+ session = await _open(store, provider, title="placeholder")++ await session.send("What are the riskiest files to modify?")+ titled = (await store.get(session.id)).title+ await session.send("And the next ones?")++ assert titled != "placeholder"+ assert (await store.get(session.id)).title == titled+++# ---------------------------------------------------------------------------+# Context: overflow retry and trimming+# ---------------------------------------------------------------------------+++async def test_an_overflow_is_retried_once_with_the_emergency_request(store):+ provider = ScriptedProvider(+ [+ [_tool("t1", "get_risk")],+ ProviderError("test", "prompt is too long: 300000 tokens > 200000 maximum"),+ [_text("fits now")],+ ]+ )+ session = await _open(store, provider)++ result = await session.send("big question")++ assert result.stop_reason == "answered" and result.answer == "fits now"+ emergency = provider.calls[2]["messages"]+ assert [m["role"] for m in emergency] == ["user", "assistant", "tool"]+ assert emergency[0]["content"] == "big question"+++async def test_a_second_overflow_fails_with_a_plain_message(store):+ overflow = ProviderError("test", "context_length_exceeded")+ session = await _open(store, ScriptedProvider([overflow, overflow]))++ result = await session.send("q")++ assert result.stop_reason == "error"+ assert result.error == OVERFLOW_MESSAGE+++async def test_an_error_after_streaming_is_not_retried(store):+ class Midway(ScriptedProvider):+ async def stream_chat(self, **kwargs):+ self.calls.append(kwargs)+ yield _text("partial")+ raise ProviderError("test", "context window exceeded")++ provider = Midway([])+ session = await _open(store, provider)++ result = await session.send("q")++ assert len(provider.calls) == 1+ assert result.stop_reason == "error"+++def test_history_keeps_the_newest_whole_turns_within_budget():+ turns = []+ for i in range(5):+ turns += [+ {"role": "user", "content": f"q{i}"},+ {"role": "assistant", "content": "x" * 400},+ ]+ turns.append({"role": "user", "content": "now"})++ kept = bound_history(turns, budget=1000)++ assert kept[0]["role"] == "user"+ assert kept[-1] == {"role": "user", "content": "now"}+ assert 1 < len(kept) < len(turns)+ assert [m["content"] for m in kept if m["role"] == "user"] == ["q3", "q4", "now"]+++def test_a_huge_question_is_truncated_not_dropped():+ kept = bound_history([{"role": "user", "content": "y" * 50_000}], budget=5_000)++ assert len(kept) == 1+ assert len(kept[0]["content"]) <= 5_000+ assert "omitted" in kept[0]["content"]+++def test_an_oversized_tool_result_becomes_a_marked_excerpt():+ message = {"role": "tool", "tool_call_id": "t", "name": "x", "content": "z" * 100_000}++ bounded = bound_tool_messages([message], limit=10_000)[0]++ payload = json.loads(bounded["content"])+ assert payload["truncated"] is True and payload["original_chars"] == 100_000+ assert len(bounded["content"]) < 11_000+++def test_a_request_over_budget_sheds_its_oldest_whole_rounds(monkeypatch):+ monkeypatch.setattr("repowise.server.chat_context.REQUEST_CHAR_BUDGET", 2_500)+ base = [{"role": "user", "content": "q"}]+ rounds = [+ [+ {"role": "assistant", "tool_calls": [{"id": f"t{i}"}]},+ {"role": "tool", "tool_call_id": f"t{i}", "content": "r" * 900},+ ]+ for i in range(4)+ ]++ messages = compose_request(base, rounds)++ assert messages[0] == base[0]+ ids = [m["tool_call_id"] for m in messages if m["role"] == "tool"]+ assert ids == ["t2", "t3"]+++# ---------------------------------------------------------------------------+# show_view: the chat-only tool that builds views from this turn's results+# ---------------------------------------------------------------------------+++def _show_view_turns(provider_ref: list) -> Callable[[int], list]:+ def turns(index: int) -> list:+ if index == 0:+ return [_tool("t1", "get_risk")]+ if index == 1:+ stamped = json.loads(provider_ref[0].calls[1]["messages"][-1]["content"])+ arguments = {"artifact_id": stamped["artifact_id"], "view": "table", "options": {"path": "files"}}+ return [_tool("t2", SHOW_VIEW_TOOL, arguments)]+ return [_text("See the table.")]++ return turns+++async def test_show_view_streams_a_view_and_the_result_carries_it(store):+ ref: list = []+ provider = ScriptedProvider(_show_view_turns(ref))+ ref.append(provider)+ tools = FakeTools()+ session = await _open(store, provider, tools=tools)++ events = await _collect(session.stream("table please"))++ types = [e["type"] for e in events]+ assert types[:5] == ["tool_start", "tool_result", "tool_start", "tool_result", "view"]+ assert tools.executed == ["get_risk"]+ view = events[4]["view"]+ assert view["kind"] == "table"+ assert view["source"]["artifact_id"] == events[1]["artifact"]["id"]+ stored = (await store.messages(session.id))[-1].content+ assert stored["views"] == [view]+ replay = await session.send("again")+ assert replay.views == []+++async def test_show_view_is_offered_under_the_read_only_ceiling_but_follows_the_allowlist(store):+ open_provider = ScriptedProvider([[_text("x")]])+ await (await _open(store, open_provider)).send("q")+ narrow = ScriptedProvider([[_tool("t1", SHOW_VIEW_TOOL, {"artifact_id": "a", "view": "table"})], [_text("x")]])+ result = await (+ await _open(store, narrow, policy=SessionPolicy(tool_allowlist=frozenset({"get_risk"})))+ ).send("q")++ assert SHOW_VIEW_TOOL in open_provider.calls[0]["tools"]+ assert SHOW_VIEW_TOOL not in narrow.calls[0]["tools"]+ assert [t.ok for t in result.tool_trace] == [False]+++async def test_a_key_reused_with_another_message_conflicts(store):+ from repowise.server.chat_session import IdempotencyConflictError++ provider = ScriptedProvider(lambda i: [_text("ok")])+ session = await _open(store, provider)+ await session.send("first question", idempotency_key="k1")++ with pytest.raises(IdempotencyConflictError):+ await session.check_send("another question", "k1")+ with pytest.raises(IdempotencyConflictError):+ await session.send("another question", idempotency_key="k1")+ await session.check_send("first question", "k1")+ assert len(provider.calls) == 1diff --git a/tests/unit/server/test_chat_session_routes.py b/tests/unit/server/test_chat_session_routes.pynew file mode 100644index 000000000..e10aafcfa--- /dev/null+++ b/tests/unit/server/test_chat_session_routes.py@@ -0,0 +1,173 @@+"""The headless session routes: open or resume, look up by thread, send."""++from __future__ import annotations++from unittest.mock import patch++import pytest+from fastapi import HTTPException+from httpx import ASGITransport, AsyncClient++from repowise.server.auth import Principal, set_authenticator+from tests.unit.server.test_chat_router import _ScriptedProvider, _text, _tool+from tests.unit.server.test_chat_stream_terminal_event import _REPO_ID, _data_events, _make_app++_PROVIDER = "repowise.server.routers.chat.get_chat_provider_instance"+_EXECUTE = "repowise.server.chat_tools.execute_tool"+++async def _client(app) -> AsyncClient:+ return AsyncClient(transport=ASGITransport(app=app), base_url="http://testserver")+++async def _open(client: AsyncClient, **body) -> dict:+ response = await client.post("/api/chat/sessions", json={"repo_id": _REPO_ID, **body})+ assert response.status_code == 200, response.text+ return response.json()+++async def test_a_thread_key_resumes_the_same_session():+ app = await _make_app()+ async with await _client(app) as client:+ first = await _open(client, namespace="bot", external_ref="C1/171.2")+ again = await _open(client, namespace="bot", external_ref="C1/171.2")+ fresh = await _open(client)+ found = await client.get(+ "/api/chat/sessions", params={"namespace": "bot", "external_ref": "C1/171.2"}+ )+ missing = await client.get("/api/chat/sessions", params={"external_ref": "nope"})++ assert first["created"] and not again["created"] and fresh["created"]+ assert again["id"] == first["id"] != fresh["id"]+ assert first["scope"] == "repo"+ assert first["policy"]["safety_ceiling"] == "read_only"+ assert first["policy"]["max_tool_loops"] == 20+ assert [row["id"] for row in found.json()] == [first["id"]]+ assert missing.json() == []+++async def test_a_policy_may_narrow_but_not_widen():+ app = await _make_app()+ async with await _client(app) as client:+ narrowed = await _open(client, policy={"max_tool_loops": 5, "tool_allowlist": ["get_risk"]})+ widened = await client.post(+ "/api/chat/sessions", json={"repo_id": _REPO_ID, "policy": {"max_tool_loops": 50}}+ )++ assert narrowed["policy"]["max_tool_loops"] == 5+ assert narrowed["policy"]["tool_allowlist"] == ["get_risk"]+ assert widened.status_code == 422+++async def test_send_returns_the_turn_result_as_json_and_replays_a_retry():+ app = await _make_app()+ provider = _ScriptedProvider(+ [[_tool("t1", "get_risk", {"targets": ["src/a.py"]})], [_text("Risky.")]]+ )+ async with await _client(app) as client:+ session = await _open(client)+ with patch(_PROVIDER, return_value=provider), patch(+ _EXECUTE, return_value={"targets": {}, "citations": ["src/a.py"]}+ ):+ url = f"/api/chat/sessions/{session['id']}/messages"+ body = {"message": "Is a.py risky?", "idempotency_key": "evt-1"}+ first = await client.post(url, json=body)+ retry = await client.post(url, json=body)++ assert first.status_code == 200, first.text+ result = first.json()+ assert result["answer"] == "Risky."+ assert result["stop_reason"] == "answered"+ assert result["citations"] == [{"file_path": "src/a.py"}]+ assert [t["name"] for t in result["tool_trace"]] == ["get_risk"]+ assert result["usage"]["model_calls"] == 2+ assert retry.json()["replayed"] is True+ assert retry.json()["message_id"] == result["message_id"]+ assert len(provider.calls) == 2+++async def test_a_reused_key_with_another_message_is_a_conflict():+ app = await _make_app()+ provider = _ScriptedProvider(lambda _i: [_text("ok")])+ async with await _client(app) as client:+ session = await _open(client)+ url = f"/api/chat/sessions/{session['id']}/messages"+ with patch(_PROVIDER, return_value=provider):+ first = await client.post(url, json={"message": "one", "idempotency_key": "k"})+ json_conflict = await client.post(url, json={"message": "two", "idempotency_key": "k"})+ sse_conflict = await client.post(+ url, json={"message": "two", "idempotency_key": "k", "stream": True}+ )++ assert first.status_code == 200+ assert json_conflict.status_code == 409+ assert sse_conflict.status_code == 409+ assert len(provider.calls) == 1+++async def test_send_can_stream_the_same_events_the_web_reads():+ app = await _make_app()+ provider = _ScriptedProvider([[_text("Hello.")]])+ async with await _client(app) as client:+ session = await _open(client)+ with patch(_PROVIDER, return_value=provider):+ response = await client.post(+ f"/api/chat/sessions/{session['id']}/messages",+ json={"message": "hi", "stream": True},+ )++ events = _data_events(response.text)+ assert [e["type"] for e in events] == ["text_delta", "done"]+ assert events[-1]["conversation_id"] == session["id"]+++async def test_a_session_turn_never_offers_a_non_read_only_tool():+ app = await _make_app()+ provider = _ScriptedProvider([[_text("ok")]])+ async with await _client(app) as client:+ session = await _open(client)+ with patch(_PROVIDER, return_value=provider):+ await client.post(f"/api/chat/sessions/{session['id']}/messages", json={"message": "hi"})++ assert "generate_refactoring_code" not in provider.calls[0]["system_prompt"]+ assert "set_finding_status" not in provider.calls[0]["system_prompt"]+++async def test_an_unknown_session_is_not_found():+ app = await _make_app()+ async with await _client(app) as client:+ response = await client.post("/api/chat/sessions/nope/messages", json={"message": "hi"})++ assert response.status_code == 404+++class _RepoScoped:+ authorization_servers = ()++ def configured(self) -> bool:+ return True++ async def verify_token(self, token):+ return None++ async def authenticate(self, request):+ if request.headers.get("authorization") != "Bearer scoped":+ raise HTTPException(401, "no")+ return Principal("token:t", "token", repo_scope=frozenset({"elsewhere"}))+++def repo_scoped_auth():+ set_authenticator(_RepoScoped())+ yield {"Authorization": "Bearer scoped"}+ set_authenticator(None)+++async def test_a_principal_outside_the_repo_is_refused(repo_scoped_auth):+ app = await _make_app()+ async with await _client(app) as client:+ refused = await client.post(+ "/api/chat/sessions", json={"repo_id": _REPO_ID}, headers=repo_scoped_auth+ )++ assert refused.status_code == 403diff --git a/tests/unit/server/test_chat_system_prompt_tools.py b/tests/unit/server/test_chat_system_prompt_tools.pyindex 2cede6915..2765ad296 100644--- a/tests/unit/server/test_chat_system_prompt_tools.py+++ b/tests/unit/server/test_chat_system_prompt_tools.py@@ -2,12 +2,9 @@from __future__ import annotations+from repowise.server.chat_prompt import _build_system_prompt, _with_navigation_context+from repowise.server.chat_session import _stored_tool_callfrom repowise.server.chat_tools import get_tool_catalog-from repowise.server.routers.chat import (- _build_system_prompt,- _stored_tool_call,- _with_navigation_context,-)from repowise.server.schemas.chat import ChatPageContextdiff --git a/tests/unit/server/test_chat_tools_execution.py b/tests/unit/server/test_chat_tools_execution.pyindex 2e0d8c21d..15f246794 100644--- a/tests/unit/server/test_chat_tools_execution.py+++ b/tests/unit/server/test_chat_tools_execution.py@@ -43,18 +43,6 @@ def test_an_entry_without_a_fastmcp_contract_is_left_out(monkeypatch, caplog) ->assert "orphan" in caplog.text-def test_artifact_metadata_comes_from_the_entry(one_tool) -> None:- assert chat_tools.get_artifact_type("probe", None) == "risk"- assert chat_tools.get_artifact_presentation("probe", None) == "table"- assert chat_tools.get_artifact_evidence_basis("probe", None) == "measured"---def test_a_tool_outside_the_catalog_gets_the_generic_metadata(one_tool) -> None:- assert chat_tools.get_artifact_type("missing", None) == "generic"- assert chat_tools.get_artifact_presentation("missing", None) == "generic"- assert chat_tools.get_artifact_evidence_basis("missing", None) == "unknown"--@pytest.mark.asyncioasync def test_a_tool_outside_the_catalog_is_refused(one_tool) -> None:result = await chat_tools.execute_tool("missing", {})diff --git a/tests/unit/server/test_chat_views.py b/tests/unit/server/test_chat_views.pyindex 693f007fd..c12688e20 100644--- a/tests/unit/server/test_chat_views.py+++ b/tests/unit/server/test_chat_views.py@@ -502,7 +502,7 @@ async def test_show_view_streams_a_view_event_and_stores_the_view():execute = AsyncMock(return_value=DEAD_CODE)with patch(_PROVIDER, return_value=provider), patch(- "repowise.server.routers.chat.execute_tool", execute+ "repowise.server.chat_tools.execute_tool", execute):events = _data_events(await _post(app, {"message": "Show dead code by tier"}))@@ -526,7 +526,7 @@ async def test_a_turn_without_show_view_stores_no_views():app = await _make_app()provider = _ScriptedProvider([[_call("t1", "get_risk", {})], [ChatStreamEvent(type="text_delta", text="ok")]])with patch(_PROVIDER, return_value=provider), patch(- "repowise.server.routers.chat.execute_tool", AsyncMock(return_value=RISK)+ "repowise.server.chat_tools.execute_tool", AsyncMock(return_value=RISK)):events = _data_events(await _post(app, {"message": "risk?"}))assert "view" not in [event["type"] for event in events]diff --git a/tests/unit/test_providers/test_anthropic_provider.py b/tests/unit/test_providers/test_anthropic_provider.pyindex eb0a5940c..baf92dafc 100644--- a/tests/unit/test_providers/test_anthropic_provider.py+++ b/tests/unit/test_providers/test_anthropic_provider.py@@ -314,3 +314,18 @@ def test_assistant_provider_content_is_replayed_verbatim():}assert _to_anthropic_messages([message]) == [{"role": "assistant", "content": blocks}]+++async def test_stream_chat_ends_with_the_calls_usage():+ provider = AnthropicProvider(api_key="sk-ant-test", model="claude-haiku-5-5")+ stream = _finished_stream([TextBlock(type="text", text="hi")])+ usage = MagicMock(+ input_tokens=200, output_tokens=80, cache_read_input_tokens=50, cache_creation_input_tokens=None+ )+ stream.get_final_message = AsyncMock(return_value=MagicMock(content=[], usage=usage))+ provider._client = MagicMock()+ provider._client.messages.stream = MagicMock(return_value=stream)++ events = [e async for e in provider.stream_chat([], [], "sys")]++ assert [(e.type, e.input_tokens, e.output_tokens) for e in events] == [("usage", 250, 80)]diff --git a/tests/unit/test_providers/test_gemini_provider.py b/tests/unit/test_providers/test_gemini_provider.pyindex 214f60af2..616ac364b 100644--- a/tests/unit/test_providers/test_gemini_provider.py+++ b/tests/unit/test_providers/test_gemini_provider.py@@ -267,3 +267,16 @@ async def test_provider_error_message_includes_exception_type():mock_client.return_value.models.generate_content.side_effect = CustomError("bad request")with pytest.raises(ProviderError, match="CustomError"):await provider.generate("sys", "user")+++async def test_stream_chat_ends_with_the_usage_of_its_calls():+ provider = GeminiProvider(api_key="fake-key")+ response = _make_mock_response()+ response.candidates[0].content.parts = [MagicMock(text="hi", function_call=None)]+ provider._client = MagicMock()+ provider._client.models.generate_content.return_value = response++ events = [e async for e in provider.stream_chat([], [], "sys")]++ assert [e.type for e in events] == ["text_delta", "stop", "usage"]+ assert (events[-1].input_tokens, events[-1].output_tokens) == (100, 50)diff --git a/tests/unit/test_providers/test_openai_provider.py b/tests/unit/test_providers/test_openai_provider.pyindex 7ab7a0514..916788f36 100644--- a/tests/unit/test_providers/test_openai_provider.py+++ b/tests/unit/test_providers/test_openai_provider.py@@ -585,3 +585,22 @@ async def test_api_status_error():provider._client = mock_client.return_valuewith pytest.raises(ProviderError):await provider.generate("sys", "user")+++async def test_stream_chat_asks_the_hosted_api_for_a_usage_chunk(monkeypatch):+ monkeypatch.delenv("OPENAI_BASE_URL", raising=False)+ captured: list[dict] = []++ async def fake_create(**kwargs):+ captured.append(kwargs)+ return _EmptyChatStream()++ for base_url in (None, "http://127.0.0.1:8000/v1"):+ provider = OpenAIProvider(api_key="sk-test", model="gpt-5.6", base_url=base_url)+ provider._client = MagicMock()+ provider._client.chat.completions.create = fake_create+ [e async for e in provider.stream_chat(messages=[], tools=[], system_prompt="s")]++ assert captured[0]["stream_options"] == {"include_usage": True}+ # A compatible server may reject the field, so it is not asked.+ assert "stream_options" not in captured[1]