Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(chat): headless chat sessions on one transport-neutral engine (#3746)

Raghav Chamadiya876eb77593de
diff --git a/docs/architecture/chat.md b/docs/architecture/chat.md
index 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 native
Content 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.py
new file mode 100644
index 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.py
index 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) -> Conve
return 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) -> lis
return 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.py
index 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 | assistant
content_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.py
index 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 usage
def _translate_anthropic_errors() -> AbstractContextManager[None]:
@@ -361,21 +365,30 @@ async def _iter_anthropic_stream_events(stream: Any) -> AsyncIterator[ChatStream
def _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.py
index 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 as
diff --git a/packages/core/src/repowise/core/providers/llm/gemini.py b/packages/core/src/repowise/core/providers/llm/gemini.py
index 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 Gemini
try:
@@ -512,10 +513,11 @@ class GeminiProvider(BaseProvider):
raise
except 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 turn
model_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 turn
contents.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 = True
def _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.py
index 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_URL
loopback = 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"] = tools
kwargs.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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.id
diff --git a/packages/server/src/repowise/server/chat_tools.py b/packages/server/src/repowise/server/chat_tools.py
index 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.py
index 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.py
index 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 annotations
import json
import logging
from collections.abc import AsyncIterator, Iterator
+from dataclasses import asdict
from pathlib import Path
from typing import Any
@@ -14,42 +20,30 @@ from starlette.responses import StreamingResponse
from repowise.core.persistence import crud
from 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_pinned
from 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_suggestions
from 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 exc
except 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 stored
diff --git a/packages/server/src/repowise/server/schemas/chat.py b/packages/server/src/repowise/server/schemas/chat.py
index 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: ConversationResponse
messages: 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 = False
diff --git a/packages/types/src/chat.ts b/packages/types/src/chat.ts
index 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.ts
index 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.py
index 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_summary
from repowise.server.chat_tools import get_tool_catalog
-from repowise.server.routers.chat import _build_tool_summary
def 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.py
index 44f57e362..f7a503f19 100644
--- a/tests/unit/server/test_chat_router.py
+++ b/tests/unit/server/test_chat_router.py
@@ -10,8 +10,9 @@ import pytest
from httpx import ASGITransport, AsyncClient
from 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_POLICY
from repowise.server.chat_tools import get_tool_catalog
-from repowise.server.routers.chat import _MAX_AGENTIC_LOOPS, _build_system_prompt
from repowise.server.schemas.chat import ChatPageContext
from 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.py
new file mode 100644
index 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) == 1
diff --git a/tests/unit/server/test_chat_session_routes.py b/tests/unit/server/test_chat_session_routes.py
new file mode 100644
index 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 == 403
diff --git a/tests/unit/server/test_chat_system_prompt_tools.py b/tests/unit/server/test_chat_system_prompt_tools.py
index 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_call
from 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 ChatPageContext
diff --git a/tests/unit/server/test_chat_tools_execution.py b/tests/unit/server/test_chat_tools_execution.py
index 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.asyncio
async 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.py
index 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.py
index 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.py
index 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.py
index 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_value
with 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]