fix(agent): polish interrupt-resume flow for merge readiness

backend/src/v1/agent/schemas.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
+from datetime import datetime
+from enum import Enum
+from typing import Literal
 from typing import Any
 from uuid import UUID
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
 class RunAgentInput(BaseModel):
@@ -40,3 +43,46 @@ class AgentChatRunResponse(BaseModel):
     session_id: UUID
     output: str
     events: list[AgentChatEvent]
+
+
+class PendingToolStatus(str, Enum):
+    PENDING_APPROVAL = "PENDING_APPROVAL"
+    APPROVED_EXECUTING = "APPROVED_EXECUTING"
+    EXECUTED = "EXECUTED"
+    REJECTED = "REJECTED"
+    EXPIRED = "EXPIRED"
+
+
+class PendingToolCall(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    interrupt_id: str = Field(min_length=1, max_length=255)
+    tool_name: str = Field(min_length=1, max_length=255)
+    tool_args: dict[str, Any] = Field(default_factory=dict)
+    status: PendingToolStatus
+    expires_at: datetime
+    decision: dict[str, Any] | None = None
+    result: dict[str, Any] | None = None
+    updated_at: datetime
+
+    @field_validator("expires_at", "updated_at")
+    @classmethod
+    def _validate_timezone_aware(cls, value: datetime) -> datetime:
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("datetime must be timezone-aware")
+        return value
+
+
+class SnapshotRunContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    thread_id: str = Field(min_length=1, max_length=255)
+    run_id: str = Field(min_length=1, max_length=255)
+
+
+class AgentSessionSnapshot(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    version: Literal[2]
+    pending_tool_call: PendingToolCall | None
+    run_context: SnapshotRunContext