Python
Allow mid-session model switching with a persisted transcript marker
Rohit C Prasadf1eb652d6169
diff --git a/coworker/engine.py b/coworker/engine.pyindex 5b002c83..7e0530f9 100644--- a/coworker/engine.py+++ b/coworker/engine.py@@ -177,6 +177,43 @@ class TurnEngine:async for event in self._loop():yield event+ def switch_model(self, model: str) -> Optional[str]:+ """Rebind the session's model mid-conversation (roadmap item 3). History is+ canonical OpenAI shape and every provider converts per call, so the switch is just+ the field write — plus a persisted notice marking WHERE it happened, with a+ degradation warning when history carries images the new model can't see (those are+ sent as placeholders — see `_outbound_messages`). Returns the notice text, or None+ when nothing changed (same model, or first bind on a fresh session)."""+ if not model or model == self.model:+ return None+ had_history = any(m.get("role") != "system" for m in self.messages)+ self.model = model+ if not had_history:+ return None+ from .providers.matrix import model_labels++ text = f"Model switched to {model_labels().get(model, model)}"+ try:+ caps = self.provider.capabilities(model)+ except Exception:+ caps = None+ if (+ caps is not None+ and not getattr(caps, "vision", False)+ and self._history_has_images()+ ):+ text += " — earlier images can't be read by this model"+ self._append_notice("model_switch", text)+ return text++ def _history_has_images(self) -> bool:+ return any(+ isinstance(p, dict) and p.get("type") == "image_url"+ for msg in self.messages+ if isinstance(msg.get("content"), list)+ for p in msg["content"]+ )+def _append_notice(self, kind: str, text: Optional[str] = None) -> None:"""Persist a turn-ending marker (error/interrupted) as a display-only `notice`message: it survives reload like the transcript does, but `_outbound_messages`@@ -868,6 +905,41 @@ class TurnEngine:for msg in out]+ # Images get the same per-turn treatment: a model without vision receives a visible+ # placeholder instead of a payload it would reject. Like the PDF path, this re-decides+ # per call, so a mid-session switch to/from a vision model always does the right thing.+ if any(+ isinstance(p, dict) and p.get("type") == "image_url"+ for msg in out+ if isinstance(msg.get("content"), list)+ for p in msg["content"]+ ):+ caps = self.provider.capabilities(self.model)+ if not getattr(caps, "vision", False):+ placeholder = {+ "type": "text",+ "text": "[image attachment — not viewable by this model]",+ }+ out = [+ (+ {+ **msg,+ "content": [+ (+ placeholder+ if isinstance(p, dict)+ and p.get("type") == "image_url"+ else p+ )+ for p in msg["content"]+ ],+ }+ if isinstance(msg.get("content"), list)+ else msg+ )+ for msg in out+ ]+context = (self.context_provider() if self.context_provider is not None else "") or ""diff --git a/coworker/server/app.py b/coworker/server/app.pyindex 3908ccc3..e4322739 100644--- a/coworker/server/app.py+++ b/coworker/server/app.py@@ -1508,11 +1508,23 @@ def create_app(manager: SessionManager) -> FastAPI:}return {"approved": True, "mode": resp.get("mode") or "interactive"}- def _model_locked() -> bool:- # The model is chosen until the first real turn, then fixed for the session's life- # (system message doesn't count as history). Enforced HERE, not just in the GUI,- # so API callers and message races can't rebind a running conversation.- return any(m.get("role") != "system" for m in engine.messages)+ async def _apply_model(model: Optional[str]) -> None:+ # Mid-session rebind is allowed (roadmap item 3, supersedes the 2026-07-04+ # lock): history is canonical and providers convert per call. A real switch+ # appends a persisted notice; broadcast it so live views render the marker+ # and update their header. Never rebind mid-turn — the running loop reads+ # `engine.model` per iteration and a mixed turn is exactly the breakage the+ # old lock existed to prevent.+ if not model or manager.is_running(session_id):+ return+ notice = engine.switch_model(model)+ if notice is None: # same model, or first bind on a fresh session+ return+ manager.persist_session(session_id)+ await manager.broadcast_session(+ session_id,+ {"type": "model_changed", "data": {"model": model, "text": notice}},+ )def _resolve_pending(resolution: str) -> None:# Live WS responses resolve THE session's single pending prompt (one at a time, since the@@ -1641,20 +1653,14 @@ def create_app(manager: SessionManager) -> FastAPI:except ValueError:passelif kind == "set_model":- model = message.get("model")- if model and not _model_locked():- engine.model = model+ await _apply_model(message.get("model"))elif kind == "user_message":text = (message.get("text") or "").strip()attachments = message.get("attachments") or []- # The composer sends its visible model with every message — the FIRST one- # binds the session's model (race-proof across reconnects; see api.ts- # Session.userMessage). After that the model is FIXED for the session's- # life (owner call, 2026-07-04): mixed-model transcripts invite- # provider-quirk breakage. Start a new session to switch.- model = message.get("model")- if model and not _model_locked():- engine.model = model+ # The composer sends its visible model with every message — the FIRST+ # one binds the session (race-proof across reconnects; see api.ts+ # Session.userMessage), later ones may switch it (notice persisted).+ await _apply_model(message.get("model"))if text or attachments:content = build_user_content(text, attachments)asyncio.create_task(run_turn(content))diff --git a/surfaces/gui/e2e/chat.spec.ts b/surfaces/gui/e2e/chat.spec.tsindex 8658a877..b7b42d61 100644--- a/surfaces/gui/e2e/chat.spec.ts+++ b/surfaces/gui/e2e/chat.spec.ts@@ -21,9 +21,9 @@ test("send → user bubble → streamed echo reply renders", async ({ page }) =>// The message carried the composer's visible model (model-per-message contract): what the// user sees at send time is exactly what serves the turn.await expect(page.getByText("[model=anthropic:claude-opus-4-8]")).toBeVisible();- // …and having sent, the model is now FIXED for this session (§17/§22): the composer picker is- // gone and the fact reads in the topbar's facts subtitle instead.- await expect(page.locator(".dd").filter({ hasText: "Claude Opus" })).toHaveCount(0);+ // …and the picker STAYS actionable after the first turn (§17 rev 2026-07-22 — mid-session+ // switching shipped); the fact also reads in the topbar's facts subtitle.+ await expect(page.locator(".dd").filter({ hasText: "Claude Opus" })).toBeVisible();await expect(page.getByTestId("session-subtitle")).toContainText("Claude Opus 4.8");// Composer cleared and re-armed for the next turn.await expect(box).toHaveValue("");diff --git a/surfaces/gui/e2e/fixtures.ts b/surfaces/gui/e2e/fixtures.tsindex 5d11d97e..82a52b58 100644--- a/surfaces/gui/e2e/fixtures.ts+++ b/surfaces/gui/e2e/fixtures.ts@@ -568,9 +568,11 @@ export async function mockApi(page: import("@playwright/test").Page) {send("ready");let pendingTool = "run_shell"; // which proposal the next approval decision resolveslet epicTimer: ReturnType<typeof setInterval> | null = null; // the slow stream, stoppable via interrupt+ let hadTurn = false; // a user_message landed — set_model is now a mid-session switchws.onMessage((raw) => {const msg = JSON.parse(String(raw));if (msg.type === "user_message") {+ hadTurn = true;send("turn_start", { input: msg.text });if (/run a tool/i.test(msg.text)) {pendingTool = "run_shell";@@ -703,6 +705,14 @@ export async function mockApi(page: import("@playwright/test").Page) {}send("interrupted", {});send("turn_done");+ } else if (msg.type === "set_model") {+ // Mid-session switch: the server applies it and broadcasts the persisted marker.+ // Like the real server, the FIRST bind (fresh session) is silent.+ if (hadTurn)+ send("model_changed", {+ model: msg.model,+ text: `Model switched to ${msg.model}`,+ });} else if (msg.type === "retry") {// Like the real engine: re-runs with NO new user message (turn_start input is empty).send("turn_start", { input: "" });diff --git a/surfaces/gui/e2e/model-switch.spec.ts b/surfaces/gui/e2e/model-switch.spec.tsnew file mode 100644index 00000000..949fdc1e--- /dev/null+++ b/surfaces/gui/e2e/model-switch.spec.ts@@ -0,0 +1,33 @@+// Model-layer roadmap item 3 (2026-07-22): the model picker stays actionable for the+// session's whole life (supersedes the 2026-07-04 lock that hid it after the first turn).+// A mid-session switch drops a persisted info marker into the transcript, and later+// messages ride the new model.+import { expect } from "@playwright/test";+import { test } from "./fixtures";++test("mid-session model switch shows the marker and later turns use the new model", async ({+ page,+}) => {+ await page.goto("/");+ await page.getByText("Draft the launch note").first().click();+ const box = page.getByPlaceholder(/Ask the coworker/);+ await box.fill("hello there");+ await box.press("Enter");+ await expect(page.getByText("Echo: hello there", { exact: false }).first()).toBeVisible();++ // The picker is still in the composer after the first turn (the old lock hid it).+ const picker = page.locator(".dd").filter({ hasText: "Claude Opus 4.8" });+ await expect(picker).toBeVisible();+ await picker.locator(".pill").click();+ await page.locator(".dd-item").filter({ hasText: "GPT-5.5" }).click();++ // The switch marker lands in the transcript…+ await expect(page.getByText(/Model switched to gpt-5.5/).first()).toBeVisible();++ // …and the next message carries the new model (the fixture echoes it back).+ await box.fill("after the switch");+ await box.press("Enter");+ await expect(+ page.getByText("Echo: after the switch [model=gpt-5.5]", { exact: false }).first(),+ ).toBeVisible();+});diff --git a/surfaces/gui/e2e/session-shell.spec.ts b/surfaces/gui/e2e/session-shell.spec.tsindex e4aff754..39389a52 100644--- a/surfaces/gui/e2e/session-shell.spec.ts+++ b/surfaces/gui/e2e/session-shell.spec.ts@@ -44,7 +44,8 @@ test("facts subtitle: absent on a fresh session, persona · model after the firsawait expect(page.getByRole("button", { name: "About this persona" })).toHaveCount(0);await expect(page.locator(".dd").filter({ hasText: "Claude Opus 4.8" })).toBeVisible();- // First turn → the model chip leaves the composer; the facts move up to the subtitle.+ // First turn → the facts move up to the subtitle; the picker STAYS in the composer+ // (§17 rev 2026-07-22: mid-session model switching shipped, so it remains actionable).const box = page.getByPlaceholder(/Ask the coworker/);await box.fill("hello");await page.getByRole("button", { name: "Send" }).click();@@ -52,7 +53,7 @@ test("facts subtitle: absent on a fresh session, persona · model after the firsconst sub = page.getByTestId("session-subtitle");await expect(sub).toContainText("Coworker · Claude Opus 4.8");- await expect(page.locator(".dd").filter({ hasText: "Claude Opus 4.8" })).toHaveCount(0);+ await expect(page.locator(".dd").filter({ hasText: "Claude Opus 4.8" })).toBeVisible();// The subtitle is the session's fixed facts — clicking it opens the coworker (persona) page,// replacing the old topbar sliders button.diff --git a/surfaces/gui/src/App.tsx b/surfaces/gui/src/App.tsxindex 62ca9fff..2e41e34c 100644--- a/surfaces/gui/src/App.tsx+++ b/surfaces/gui/src/App.tsx@@ -638,6 +638,12 @@ export function App() {if (d.status === "max_iterations_exceeded")setItems((p) => [...p, { kind: "notice", tone: "warn", text: "Stopped: max iterations reached." }]);break;+ case "model_changed":+ // Mid-session switch (server-applied): update the header fact and drop the+ // persisted marker into the live transcript (replay renders it from history).+ if (d.model) setModel(d.model);+ setItems((p) => [...p, { kind: "notice", tone: "info", text: d.text || "Model switched" }]);+ break;case "interrupted":flushPartialStream();setItems((p) => [...p, { kind: "notice", tone: "warn", text: "Interrupted." }]);@@ -812,6 +818,7 @@ export function App() {sessionRef.current?.setMode(m);};const changeModel = (m: string) => {+ if (running) return; // the server refuses mid-turn rebinds — don't let the header liesetModel(m);sessionRef.current?.setModel(m);};@@ -1451,7 +1458,6 @@ export function App() {model={model}models={models}modelLabels={modelLabels}- modelLocked={items.length > 0}running={running}connected={connected}modelReady={modelReady}diff --git a/surfaces/gui/src/components/Composer.tsx b/surfaces/gui/src/components/Composer.tsxindex 011a8e19..894c892e 100644--- a/surfaces/gui/src/components/Composer.tsx+++ b/surfaces/gui/src/components/Composer.tsx@@ -49,7 +49,6 @@ interface Props {// The model is FIXED once the session has history (§17): the picker renders ONLY on a fresh// session; after the first turn the fact lives in the topbar subtitle (§22) — no// interactive-then-disabled control.- modelLocked?: boolean;running: boolean;connected: boolean;// False when the default model's provider has no key — the composer shows a "connect a model"@@ -461,8 +460,9 @@ export function Composer(props: Props) {<span className="ml-auto" />- {/* model — a quiet chip on a FRESH session only; once the session has history the- fact moves up to the topbar subtitle (§17 expressed spatially). */}+ {/* model — a quiet chip, now for the session's whole life (§17 rev 2026-07-22:+ mid-session switching shipped, so the picker stays actionable; the topbar+ subtitle still states the current model). */}{!dictation?.recording && (needsModel ? (<buttonclassName="pill model-warn chip"@@ -473,20 +473,17 @@ export function Composer(props: Props) {<span className="pill-label">No model</span><span className="model-warn-ico" aria-hidden>⚠</span></button>+ ) : modelsLoaded ? (+ <Dropdown value={props.model} options={modelOptions} onChange={props.onModelChange} align="right" />) : (- !props.modelLocked &&- (modelsLoaded ? (- <Dropdown value={props.model} options={modelOptions} onChange={props.onModelChange} align="right" />- ) : (- <button- className="pill chip text-faint cursor-default"- disabled- data-testid="models-loading"- title="Fetching the model list from the server"- >- <span className="pill-label">Loading models…</span>- </button>- ))+ <button+ className="pill chip text-faint cursor-default"+ disabled+ data-testid="models-loading"+ title="Fetching the model list from the server"+ >+ <span className="pill-label">Loading models…</span>+ </button>))}{/* mic — immediately before send (owner call, DMG #28 walkthrough) */}diff --git a/surfaces/gui/src/itemsFromMessages.test.ts b/surfaces/gui/src/itemsFromMessages.test.tsindex f8b9cf95..993c5e8b 100644--- a/surfaces/gui/src/itemsFromMessages.test.ts+++ b/surfaces/gui/src/itemsFromMessages.test.ts@@ -68,3 +68,17 @@ describe("itemsFromMessages notices", () => {]);});});++describe("itemsFromMessages model switch", () => {+ it("replays the persisted model_switch marker as an info notice", () => {+ const items = itemsFromMessages([+ { role: "user", content: "hi" },+ { role: "notice", kind: "model_switch", text: "Model switched to Kimi K2.6 · Moonshot" },+ ] as any);+ expect(items[1]).toEqual({+ kind: "notice",+ tone: "info",+ text: "Model switched to Kimi K2.6 · Moonshot",+ });+ });+});diff --git a/surfaces/gui/src/itemsFromMessages.ts b/surfaces/gui/src/itemsFromMessages.tsindex 1ac8b53c..1f8b3c98 100644--- a/surfaces/gui/src/itemsFromMessages.ts+++ b/surfaces/gui/src/itemsFromMessages.ts@@ -59,13 +59,15 @@ export function itemsFromMessages(messages: ConversationMessage[]): Item[] {});}} else if (m.role === "notice") {- // Persisted turn-ending marker (engine `_append_notice`): error/interrupted survive+ // Persisted markers (engine `_append_notice`): error/interrupted/model-switch survive// reload exactly like the live view rendered them. An error notice is retriable —// the Transcript only offers the button when it's the transcript tail.items.push(m.kind === "interrupted"? { kind: "notice", tone: "warn", text: "Interrupted." }- : { kind: "notice", tone: "warn", text: "Error: " + (m.text || "unknown"), retriable: true },+ : m.kind === "model_switch"+ ? { kind: "notice", tone: "info", text: m.text || "Model switched" }+ : { kind: "notice", tone: "warn", text: "Error: " + (m.text || "unknown"), retriable: true },);}// system messages are omitted; tool-result messages are folded into the tool row abovediff --git a/surfaces/gui/src/types.ts b/surfaces/gui/src/types.tsindex b835eeee..27f87763 100644--- a/surfaces/gui/src/types.ts+++ b/surfaces/gui/src/types.ts@@ -15,6 +15,7 @@ export type EventType =| "turn_end"| "error"| "interrupted"+ | "model_changed"| "turn_done";export interface WsEvent {diff --git a/tests/test_engine.py b/tests/test_engine.pyindex 98f5537c..90e38fdb 100644--- a/tests/test_engine.py+++ b/tests/test_engine.py@@ -381,3 +381,61 @@ def test_provider_extras_persist_on_message_and_survive_outbound(tmp_path):outbound = engine._outbound_messages()[-1]assert outbound["_gemini"] == {"text_sig": "c2ln", "call_sigs": []}assert "ts" not in outbound # display sidecars still stripped+++def test_switch_model_appends_notice_only_midsession(tmp_path):+ engine, _ = _engine(tmp_path, [_text_turn("ok")])+ # Fresh session: first bind is silent.+ assert engine.switch_model("zai:glm-5.2") is None+ assert engine.model == "zai:glm-5.2"+ _collect(engine, "hi")+ # Same model: no-op.+ assert engine.switch_model("zai:glm-5.2") is None+ # Real mid-session switch: persisted marker with the matrix label.+ text = engine.switch_model("kimi:kimi-k2.6")+ assert "Kimi K2.6" in text and engine.model == "kimi:kimi-k2.6"+ notice = engine.messages[-1]+ assert notice["role"] == "notice" and notice["kind"] == "model_switch"+ assert all(m.get("role") != "notice" for m in engine._outbound_messages())+++def test_switch_model_warns_when_images_meet_text_only_model(tmp_path):+ class NoVisionProvider(ScriptedProvider):+ def capabilities(self, model):+ return ModelCapabilities(vision=False)++ engine, _ = _engine(tmp_path, [_text_turn("ok")])+ engine.provider = NoVisionProvider([_text_turn("ok")])+ engine.messages.append(+ {+ "role": "user",+ "content": [+ {"type": "text", "text": "look"},+ {"type": "image_url", "image_url": {"url": "data:image/png;base64,AA=="}},+ ],+ }+ )+ text = engine.switch_model("zai:glm-5.2")+ assert "images" in text # degradation is called out in the marker+++def test_outbound_replaces_images_for_non_vision_models(tmp_path):+ class NoVisionProvider(ScriptedProvider):+ def capabilities(self, model):+ return ModelCapabilities(vision=False)++ engine, _ = _engine(tmp_path, [_text_turn("ok")])+ engine.provider = NoVisionProvider([_text_turn("ok")])+ engine.messages.append(+ {+ "role": "user",+ "content": [+ {"type": "text", "text": "look"},+ {"type": "image_url", "image_url": {"url": "data:image/png;base64,AA=="}},+ ],+ }+ )+ parts = engine._outbound_messages()[-1]["content"]+ assert all(p["type"] != "image_url" for p in parts)+ assert "not viewable" in parts[-1]["text"]+ assert engine.messages[-1]["content"][1]["type"] == "image_url" # history untoucheddiff --git a/tests/test_server.py b/tests/test_server.pyindex 40614c64..686fdb47 100644--- a/tests/test_server.py+++ b/tests/test_server.py@@ -614,33 +614,38 @@ def test_ws_session_resume_via_store(tmp_path):assert any(s["session_id"] == "keep" and s["messages"] > 0 for s in sessions)-def test_ws_first_message_binds_the_session_model_then_locks(tmp_path):- """The FIRST user_message's model binds the session (race-proof across reconnects — found- 2026-07-04: a new cowork session reconnects to adopt its scratch dir, which could drop a- queued set_model and leave the engine on a stale/resumed model). After the first turn the- model is FIXED for the session's life: later message models and set_model are ignored- (owner call, 2026-07-04 — mixed-model transcripts invite provider-quirk breakage).- """- client = _client(tmp_path, [_text("ok"), _text("ok again"), _text("still ok")])+def test_ws_first_message_binds_then_midsession_switch_persists_notice(tmp_path):+ """The FIRST user_message's model binds the session silently (race-proof across+ reconnects — found 2026-07-04). Mid-session rebinds are ALLOWED (roadmap item 3,+ 2026-07-22, supersedes the 07-04 lock): the switch lands as a persisted model_switch+ notice and a model_changed broadcast, and the next turn runs on the new model."""+ # 4 turns: 3 user turns + the autotitle's fire-and-forget complete() after turn 1.+ client = _client(+ tmp_path, [_text("ok"), _text("Session title"), _text("ok again"), _text("still ok")]+ )with client.websocket_connect("/ws/session/model-per-msg") as ws:ready = ws.receive_json()assert ready["type"] == "ready"- default_model = ready["data"]["model"]ws.send_json({"type": "user_message", "text": "hi", "model": "zai:glm-5.2"})- _drain(ws)+ assert "model_changed" not in _drain(ws) # first bind is silent# message WITHOUT a model keeps the bound one (no silent reset to default)ws.send_json({"type": "user_message", "text": "again"})_drain(ws)- # locked: neither a different message model nor set_model can rebind mid-sessionws.send_json({"type": "set_model", "model": "kimi:kimi-k2.6"})- ws.send_json(- {"type": "user_message", "text": "switch?", "model": "kimi:kimi-k2.6"}- )+ changed = ws.receive_json()+ assert changed["type"] == "model_changed"+ assert changed["data"]["model"] == "kimi:kimi-k2.6"+ assert "Kimi" in changed["data"]["text"]+ ws.send_json({"type": "user_message", "text": "switched now"})_drain(ws)mgr = client.app.state.managerengine = mgr._engines["model-per-msg"]- assert engine.model == "zai:glm-5.2"- assert engine.model != default_model+ assert engine.model == "kimi:kimi-k2.6"+ # The marker is persisted between the turns; the provider never sees it.+ messages = client.get("/v1/sessions/model-per-msg/messages").json()["messages"]+ notices = [m for m in messages if m["role"] == "notice"]+ assert [n["kind"] for n in notices] == ["model_switch"]+ assert all(m.get("role") != "notice" for m in engine._outbound_messages())def test_session_messages_prefers_the_live_engine(tmp_path):