ss-tools/specs/033-gradio-agent-chat/contracts/modules.md

#region AgentChat.Contracts [C:4] [TYPE ADR] [SEMANTICS contracts,modules,agent-chat,langgraph,final] @BRIEF Final module contracts — LangGraph create_react_agent(), @tool, interrupt()/Command(resume=...), PostgresSaver, structured JSON metadata, dual-identity RBAC.

Backend

Contract	C	File	Notes
AgentChat.GradioApp	C4	backend/src/agent/app.py	gr.ChatInterface(type="messages", multimodal=True, additional_inputs=[gr.Textbox("conversation_id"), gr.Textbox("action")], examples=[["Покажи дашборды",null,null],["Статус системы",null,null]]). Handler: def handler(message, history, request: gr.Request, conversation_id=None, action=None). Per-user lock via in-memory dict (no global concurrency_limit — Gradio handles concurrent users by default).
AgentChat.GradioApp.Handler	C4	↑	Creates create_react_agent() with PostgresSaver. astream_events(config={"configurable":{"thread_id":conversation_id}}). Resume: detects action="confirm"/"deny" in additional_inputs, loads checkpoint, invokes Command(resume=...).
AgentChat.LangGraph.Setup	C4	backend/src/agent/langgraph_setup.py	create_react_agent(model, tools=ALL_TOOLS, checkpointer=PostgresSaver(conn_string)). interrupt_before=DANGEROUS_TOOLS. Wrapped in RunnableWithMessageHistory. No custom middleware.
AgentChat.Tools	C4	backend/src/agent/tools.py	Native @tool functions. Each: Pydantic BaseModel args_schema, calls FastAPI REST with dual-identity headers (Authorization: service JWT + X-User-JWT: user JWT).
AgentChat.Middleware	C3	backend/src/agent/middleware.py	LoggingMiddleware only (audit trail).
AgentChat.Document.Parser	C3	backend/src/agent/document_parser.py	pdfplumber (PDF) + openpyxl (XLSX).
AgentChat.Api.Conversations	C3	backend/src/api/routes/agent_conversations.py	CRUD (list, history, create, archive) + multi-tab gate GET .../conversations/{id}/active.
AgentChat.Api.ServiceToken	C3	backend/src/api/routes/auth.py	POST /api/auth/service-token — returns service JWT (role agent).
Models.Agent	C2	backend/src/models/agent.py	AgentConversation, AgentMessage.
Schemas.Agent	C1	backend/src/schemas/agent.py	Pydantic: ConversationItem, ConversationListResponse, MessageItem, HistoryResponse, DeleteResponse.

Frontend

Contract	C	File	Notes
AgentChat.Model	C4	frontend/src/lib/models/AgentChatModel.svelte.ts	submit("/chat", {text,files}, [conversationId, action]) lifecycle. Structured ChatMessage.metadata parsing. HITL resume via second submit with additional_inputs[1]="confirm"/"deny". No tabRole, no follower.
AgentChat.Panel	C4	frontend/src/lib/components/assistant/AssistantChatPanel.svelte	Client.connect("/api/agent/gradio"), submit(), metadata-based rendering of tool cards + confirmation cards.
AgentChat.Page	C3	frontend/src/routes/agent/+page.svelte	Two-column layout: conversation list (240px) + chat area.
AgentChat.ConversationList	C3	frontend/src/lib/components/assistant/ConversationList.svelte	Search, infinite scroll, date grouping, archive action.
AgentChat.ToolCallCard	C2	frontend/src/lib/components/assistant/ToolCallCard.svelte	Props from metadata.type="tool_start"/"tool_end"/"tool_error".
AgentChat.ConfirmationCard	C3	frontend/src/lib/components/assistant/ConfirmationCard.svelte	Renders on metadata.type="confirm_required". Calls second submit() with additional_inputs=[conversation_id, "confirm"/"deny"].

Contracts Removed (vs prior versions)

• AgentChat.LangChain.Setup → renamed to AgentChat.LangGraph.Setup
• HumanInTheLoopMiddleware → replaced by interrupt_before=DANGEROUS_TOOLS (LangGraph native)
• __resume__ field → replaced by additional_inputs[1]="confirm"/"deny"

#endregion AgentChat.Contracts