feat: allow session_name with session_id to rename sessions (#5056)

## Summary

- MCP agents (everyrow-cc) naturally pass both `session_id` and
`session_name` when resuming sessions — this previously threw a
`ValueError`
- Instead of rejecting it, we now use `session_name` as a rename: the
session is resumed via `session_id`, and renamed to `session_name`
- Adds `PATCH /sessions/{id}` to the public API v0, backed by the
existing `update_session_from_spec()` DB function

## Changes

- **Engine API**: New `PATCH /sessions/{session_id}` endpoint +
`UpdateSession` request model
- **Generated client**: New `update_session_endpoint` module +
`UpdateSession` attrs model
- **SDK `create_session()`**: Fires a PATCH rename when both
`session_id` and `name` are provided
- **MCP models**: Removed `_check_session_exclusivity` and all 4 call
sites; updated 8 field descriptions
- **MCP instructions**: Updated "Session and artifact reuse" section to
document rename behavior
- **Tests**: Converted 5 rejection tests → acceptance/rename
verification tests

## Test plan

- [x] `pytest tests/test_session.py` — 17 passed
- [x] `pytest futuresearch-mcp/tests/test_server.py -k session` — 24
passed
- [x] Full SDK suite — 40 passed
- [x] Full MCP suite — 356 passed
- [x] Pre-commit hooks (format, lint, typecheck) — all passed

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Sourced from commit 9f76f1f3886fea1766b58d9e23c32bb4ab936a73

Author: jackwildman

futuresearch-mcp/src/futuresearch_mcp/app.py

@@ -116,10 +116,11 @@ async def no_auth_http_lifespan(_server: FastMCP):
 
 ## Session and artifact reuse
 
-Every operation creates a session. After your first operation or upload, pass the \
-returned `session_id` to subsequent operations to keep tasks grouped. When an \
-operation completes, its `artifact_id` can be passed directly to the next operation \
-instead of re-uploading data.
+Every operation creates a session. After your first operation or upload, **always pass \
+the returned `session_id`** to subsequent operations to keep tasks grouped. You may \
+pass `session_id` together with `session_name` — the session is resumed and renamed \
+to the given name. When an operation completes, its `artifact_id` can be passed \
+directly to the next operation instead of re-uploading data.
 
 ## Key rules
 - Be concise. Keep summaries to 1-2 sentences. Do not output markdown tables, \

futuresearch-mcp/src/futuresearch_mcp/models.py

@@ -134,18 +134,6 @@ def _validate_session_id(v: str | None) -> str | None:
     return v
 
 
-def _check_session_exclusivity(
-    session_id: str | None, session_name: str | None
-) -> None:
-    """Raise if both session_id and session_name are provided."""
-    if session_id is not None and session_name is not None:
-        raise ValueError(
-            "session_id and session_name are mutually exclusive — "
-            "pass session_id to resume an existing session, "
-            "or session_name to create a new one."
-        )
-
-
 class _SingleSourceInput(BaseModel):
     model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
 
@@ -159,11 +147,11 @@ class _SingleSourceInput(BaseModel):
     )
     session_id: str | None = Field(
         default=None,
-        description="Session ID (UUID) to resume. Mutually exclusive with session_name.",
+        description="Session ID (UUID) to add to an existing session. If session_name is also provided, the session is renamed.",
     )
     session_name: str | None = Field(
         default=None,
-        description="Human-readable name for a new session. Mutually exclusive with session_id.",
+        description="Human-readable name for a new session. If session_id is also provided, renames the existing session.",
     )
 
     @field_validator("artifact_id")
@@ -202,7 +190,6 @@ def check_input_source(self):
             field_names=("artifact_id", "data"),
             label="Input",
         )
-        _check_session_exclusivity(self.session_id, self.session_name)
         return self
 
     @property
@@ -377,11 +364,11 @@ class MergeInput(BaseModel):
 
     session_id: str | None = Field(
         default=None,
-        description="Session ID (UUID) to resume. Mutually exclusive with session_name.",
+        description="Session ID (UUID) to add to an existing session. If session_name is also provided, the session is renamed.",
     )
     session_name: str | None = Field(
         default=None,
-        description="Human-readable name for a new session. Mutually exclusive with session_id.",
+        description="Human-readable name for a new session. If session_id is also provided, renames the existing session.",
     )
 
     @field_validator("left_artifact_id", "right_artifact_id")
@@ -425,7 +412,6 @@ def check_sources(self) -> "MergeInput":
             field_names=("right_artifact_id", "right_data"),
             label="Right table",
         )
-        _check_session_exclusivity(self.session_id, self.session_name)
         return self
 
     @property
@@ -524,11 +510,11 @@ class UploadDataInput(BaseModel):
     )
     session_id: str | None = Field(
         default=None,
-        description="Session ID (UUID) to resume. Mutually exclusive with session_name.",
+        description="Session ID (UUID) to add to an existing session. If session_name is also provided, the session is renamed.",
     )
     session_name: str | None = Field(
         default=None,
-        description="Human-readable name for a new session. Mutually exclusive with session_id.",
+        description="Human-readable name for a new session. If session_id is also provided, renames the existing session.",
     )
 
     @field_validator("source")
@@ -553,11 +539,6 @@ def validate_source(cls, v: str) -> str:
     def validate_session_id(cls, v: str | None) -> str | None:
         return _validate_session_id(v)
 
-    @model_validator(mode="after")
-    def check_session_exclusivity(self) -> "UploadDataInput":
-        _check_session_exclusivity(self.session_id, self.session_name)
-        return self
-
 
 class SingleAgentInput(BaseModel):
     """Input for a single agent operation (no CSV)."""
@@ -604,11 +585,11 @@ class SingleAgentInput(BaseModel):
     )
     session_id: str | None = Field(
         default=None,
-        description="Session ID (UUID) to resume. Mutually exclusive with session_name.",
+        description="Session ID (UUID) to add to an existing session. If session_name is also provided, the session is renamed.",
     )
     session_name: str | None = Field(
         default=None,
-        description="Human-readable name for a new session. Mutually exclusive with session_id.",
+        description="Human-readable name for a new session. If session_id is also provided, renames the existing session.",
     )
 
     @field_validator("response_schema")
@@ -623,11 +604,6 @@ def validate_response_schema(
     def validate_session_id(cls, v: str | None) -> str | None:
         return _validate_session_id(v)
 
-    @model_validator(mode="after")
-    def check_session_exclusivity(self) -> "SingleAgentInput":
-        _check_session_exclusivity(self.session_id, self.session_name)
-        return self
-
 
 def _validate_task_id(v: str) -> str:
     """Validate task_id is a valid UUID."""

futuresearch-mcp/tests/test_server.py

@@ -1635,14 +1635,16 @@ def test_single_source_accepts_session_name(self):
         )
         assert params.session_name == "My Session"
 
-    def test_single_source_rejects_both_session_params(self):
-        with pytest.raises(ValidationError, match="mutually exclusive"):
-            AgentInput(
-                task="test",
-                artifact_id=str(uuid4()),
-                session_id=str(uuid4()),
-                session_name="conflict",
-            )
+    def test_single_source_accepts_both_session_params(self):
+        sid = str(uuid4())
+        params = AgentInput(
+            task="test",
+            artifact_id=str(uuid4()),
+            session_id=sid,
+            session_name="also-provided",
+        )
+        assert params.session_id == sid
+        assert params.session_name == "also-provided"
 
     def test_single_source_rejects_invalid_session_id(self):
         with pytest.raises(ValidationError, match="session_id must be a valid UUID"):
@@ -1661,15 +1663,17 @@ def test_merge_accepts_session_id(self):
         )
         assert params.session_id is not None
 
-    def test_merge_rejects_both_session_params(self):
-        with pytest.raises(ValidationError, match="mutually exclusive"):
-            MergeInput(
-                task="match",
-                left_data=[{"a": 1}],
-                right_data=[{"b": 2}],
-                session_id=str(uuid4()),
-                session_name="conflict",
-            )
+    def test_merge_accepts_both_session_params(self):
+        sid = str(uuid4())
+        params = MergeInput(
+            task="match",
+            left_data=[{"a": 1}],
+            right_data=[{"b": 2}],
+            session_id=sid,
+            session_name="also-provided",
+        )
+        assert params.session_id == sid
+        assert params.session_name == "also-provided"
 
     def test_single_agent_accepts_session_id(self):
         params = SingleAgentInput(task="test", session_id=str(uuid4()))
@@ -1692,27 +1696,31 @@ def test_single_agent_accepts_custom_params(self):
         assert params.iteration_budget == 5
         assert params.include_reasoning is True
 
-    def test_single_agent_rejects_both_session_params(self):
-        with pytest.raises(ValidationError, match="mutually exclusive"):
-            SingleAgentInput(
-                task="test",
-                session_id=str(uuid4()),
-                session_name="conflict",
-            )
+    def test_single_agent_accepts_both_session_params(self):
+        sid = str(uuid4())
+        params = SingleAgentInput(
+            task="test",
+            session_id=sid,
+            session_name="also-provided",
+        )
+        assert params.session_id == sid
+        assert params.session_name == "also-provided"
 
     def test_upload_data_accepts_session_id(self):
         params = UploadDataInput(
             source="https://example.com/data.csv", session_id=str(uuid4())
         )
         assert params.session_id is not None
 
-    def test_upload_data_rejects_both_session_params(self):
-        with pytest.raises(ValidationError, match="mutually exclusive"):
-            UploadDataInput(
-                source="https://example.com/data.csv",
-                session_id=str(uuid4()),
-                session_name="conflict",
-            )
+    def test_upload_data_accepts_both_session_params(self):
+        sid = str(uuid4())
+        params = UploadDataInput(
+            source="https://example.com/data.csv",
+            session_id=sid,
+            session_name="also-provided",
+        )
+        assert params.session_id == sid
+        assert params.session_name == "also-provided"
 
     # ── Tool invocations ─────────────────────────────────────