@agentsdock/server 1.0.10 → 1.0.11-beta.2

package/server/gemini_api.py

@@ -0,0 +1,128 @@
+"""Bounded Gemini Developer API discovery; never OpenAI protocol guessing."""
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import time
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+MODEL = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,199}\Z")
+
+
+def supports_auto(selected: dict) -> bool:
+    """Only Google's API is known to support the models chosen by CLI Auto.
+
+    Auto is a CLI routing alias, not a model returned by the REST inventory.
+    Do not assume a Gemini-compatible gateway implements that model family.
+    """
+    url = urlsplit(selected.get("base_url") or "")
+    return (url.scheme == "https" and url.netloc.lower() in {
+        "generativelanguage.googleapis.com", "generativelanguage.googleapis.com:443"
+    } and url.path.rstrip("/") in {"", "/v1", "/v1beta"}
+        and not url.query and not url.fragment)
+
+
+def default_model(selected: dict) -> str | None:
+    # Preserve an explicit chat model or its immutable connection default.
+    return selected.get("model") or ("auto" if supports_auto(selected) else None)
+
+
+def model_options(selected: dict, models: list[dict]) -> list[dict]:
+    if supports_auto(selected):
+        return [{"value": "auto", "label": "Auto (Gemini CLI)"},
+                *[item for item in models if item["value"] != "auto"]]
+    return models
+
+
+def api_base(selected):
+    base = selected["base_url"].rstrip("/")
+    return base if base.endswith(("/v1", "/v1beta")) else base + "/v1beta"
+
+
+def parse_models(value):
+    if not isinstance(value, dict) or not isinstance(value.get("models"), list):
+        raise ValueError("Invalid Gemini model catalog")
+    result = []
+    for item in value["models"]:
+        if not isinstance(item, dict):
+            raise ValueError("Invalid Gemini model entry")
+        model = str(item.get("name") or "").removeprefix("models/")
+        if not MODEL.fullmatch(model) or "generateContent" not in item.get("supportedGenerationMethods", []):
+            continue
+        label = item.get("displayName") or model
+        if not isinstance(label, str) or not label or len(label) > 256 or any(ord(c) < 32 or ord(c) == 127 for c in label):
+            label = model
+        result.append({"value": model, "label": label})
+    return result
+
+
+def catalog(selected):
+    models, seen = [], set()
+    deadline = time.monotonic() + 10
+    status = "unavailable"
+    try:
+        with httpx.Client(follow_redirects=False, trust_env=False) as client:
+            page = None
+            for _ in range(5):
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                params = {"pageSize": "100", **({"pageToken": page} if page else {})}
+                with client.stream("GET", api_base(selected) + "/models", params=params,
+                        headers={"x-goog-api-key": selected["api_key"]}, timeout=remaining) as response:
+                    if response.status_code in {401, 403}: return {"models": [], "discovery_status": "authentication_failed"}
+                    if response.status_code != 200: break
+                    raw = bytearray()
+                    for chunk in response.iter_bytes():
+                        raw.extend(chunk)
+                        if len(raw) > 2 * 1024 * 1024 or time.monotonic() > deadline: raise ValueError()
+                    value = json.loads(raw)
+                    for item in parse_models(value):
+                        if item["value"] not in seen:
+                            seen.add(item["value"]); models.append(item)
+                    page = value.get("nextPageToken")
+                    if not page:
+                        return {"models": models[:512], "discovery_status": "ready" if models else "empty"}
+                    if not isinstance(page, str) or len(page) > 4096: raise ValueError()
+    except (ValueError, TypeError, httpx.HTTPError):
+        pass
+    return {"models": models[:512], "discovery_status": "partial" if models else status}
+
+
+async def probe(selected):
+    async def send():
+        headers = {"x-goog-api-key": selected["api_key"]}
+        model = selected.get("model")
+        async with httpx.AsyncClient(timeout=10, follow_redirects=False, trust_env=False) as client:
+            if model:
+                if not MODEL.fullmatch(model): return "unsupported"
+                method, target = "POST", api_base(selected) + "/models/" + quote(model, safe="") + ":generateContent"
+                kwargs = {"json": {"contents": [{"role": "user", "parts": [{"text": "Reply OK only."}]}],
+                                   "generationConfig": {"maxOutputTokens": 256}}}
+            else:
+                method, target, kwargs = "GET", api_base(selected) + "/models?pageSize=1", {}
+            async with client.stream(method, target, headers=headers, **kwargs) as response:
+                if response.status_code in {400, 401, 403}: return "authentication_failed" if not model or response.status_code != 400 else "unsupported"
+                if response.status_code == 429: return "rate_limited"
+                if response.status_code != 200: return "connection_failed"
+                raw = bytearray()
+                async for chunk in response.aiter_bytes():
+                    raw.extend(chunk)
+                    if len(raw) > 128 * 1024: return "invalid_response"
+                value = json.loads(raw)
+            if model:
+                return "verified" if any(part.get("text", "").strip() for candidate in value.get("candidates", [])
+                    for part in candidate.get("content", {}).get("parts", []) if not part.get("thought")) else "invalid_response"
+            parse_models(value)
+            # A public gateway catalog cannot prove its key was accepted.
+            async with client.stream("GET", target) as public:
+                return "verified" if public.status_code in {400, 401, 403} else "model_required"
+    try:
+        return await asyncio.wait_for(send(), 20)
+    except (asyncio.TimeoutError, httpx.HTTPError):
+        return "connection_failed"
+    except (ValueError, TypeError, AttributeError):
+        return "invalid_response"

package/server/gemini_content.py

@@ -0,0 +1,102 @@
+"""Bounded native ACP content and provider-reported metadata (no estimates)."""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import stat
+
+from fastapi import HTTPException
+from gemini_acp_client import GeminiProtocolError
+
+MAX_FILE_BYTES = 512 * 1024
+MAX_TOTAL_BYTES = 2 * 1024 * 1024
+MAX_FILES = 8
+MEDIA = {"image/png", "image/jpeg", "image/webp", "image/gif", "audio/wav", "audio/mpeg", "audio/ogg", "audio/flac"}
+
+
+def tool_output(content) -> str:
+    """Keep native diffs/resources in traces, not just text-only tool results."""
+    if not isinstance(content, list):
+        return json.dumps(content, ensure_ascii=False)
+    parts = []
+    for item in content:
+        block = item.get("content") if isinstance(item, dict) and item.get("type") == "content" else None
+        if isinstance(block, dict) and block.get("type") == "text" and isinstance(block.get("text"), str):
+            parts.append(block["text"])
+        else:
+            parts.append(json.dumps(item, ensure_ascii=False))
+    return "\n".join(parts)
+
+
+def attachments(api, session_id: str, file_ids: list[str]) -> list[dict]:
+    ids = api.validate_session_file_ids(session_id, file_ids)
+    if len(ids) > MAX_FILES:
+        raise HTTPException(413, "Gemini accepts at most 8 attachments per turn.")
+    result, total = [], 0
+    for file_id in ids:
+        record = api.load_file_meta(file_id)
+        source = api.fork_file_source_path(file_id, record)
+        if source is None:
+            raise HTTPException(409, "Gemini attachment is no longer available.")
+        try:
+            descriptor = os.open(source, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+            with os.fdopen(descriptor, "rb") as handle:
+                before = os.fstat(handle.fileno())
+                if not stat.S_ISREG(before.st_mode) or before.st_size > MAX_FILE_BYTES:
+                    raise HTTPException(413, "Gemini attachments must be regular files of at most 512 KiB each.")
+                raw = handle.read(MAX_FILE_BYTES + 1)
+                after = os.fstat(handle.fileno())
+            if len(raw) > MAX_FILE_BYTES or (before.st_size, before.st_mtime_ns) != (after.st_size, after.st_mtime_ns):
+                raise HTTPException(409, "Gemini attachment changed while reading; attach it again.")
+        except OSError:
+            raise HTTPException(409, "Gemini attachment could not be safely read.") from None
+        total += len(raw)
+        if total > MAX_TOTAL_BYTES:
+            raise HTTPException(413, "Gemini attachments exceed the 2 MiB total limit.")
+        mime = str(record.get("content_type") or "").split(";", 1)[0].strip().lower()
+        if mime in MEDIA:
+            result.append({"type": "image" if mime.startswith("image/") else "audio",
+                           "mimeType": mime, "data": base64.b64encode(raw).decode("ascii")})
+        else:
+            try:
+                text = raw.decode("utf-8")
+                if "\0" in text:
+                    raise ValueError()
+            except (UnicodeError, ValueError):
+                raise HTTPException(415, "Gemini supports UTF-8 text, PNG/JPEG/WebP/GIF images and WAV/MP3/OGG/FLAC audio attachments.") from None
+            # Pinned ACP resolvePrompt drops inline media when resource blocks
+            # are mixed with it. Explicit text parts preserve mixed uploads;
+            # no URL fetching or arbitrary path resolution is involved.
+            result.append({"type": "text", "text": "\nAttached file (quoted content): "
+                + json.dumps({"name": str(record.get("filename") or file_id)[:256], "text": text}, ensure_ascii=False)})
+    return result
+
+
+def plan_entries(value) -> list[dict]:
+    if not isinstance(value, list) or len(value) > 128:
+        raise GeminiProtocolError("Gemini returned an invalid plan.")
+    result = []
+    for row in value:
+        if (not isinstance(row, dict) or not isinstance(row.get("content"), str)
+                or len(row["content"]) > 2048 or row.get("status") not in {"pending", "in_progress", "completed"}
+                or row.get("priority") not in {"high", "medium", "low"}):
+            raise GeminiProtocolError("Gemini returned an invalid plan entry.")
+        result.append({key: row[key] for key in ("content", "status", "priority")})
+    return result
+
+
+def usage(value) -> dict:
+    if not isinstance(value, dict):
+        return {}
+    result = {}
+    for source, target in (("inputTokens", "input_tokens"), ("outputTokens", "output_tokens"),
+                           ("totalTokens", "total_tokens"), ("cachedReadTokens", "cached_input_tokens"),
+                           ("thoughtTokens", "reasoning_tokens")):
+        count = value.get(source)
+        if count is None:
+            continue
+        if type(count) is not int or not 0 <= count <= 2**53 - 1:
+            raise GeminiProtocolError("Gemini returned invalid token usage.")
+        result[target] = count
+    return result

package/server/gemini_history.py

@@ -0,0 +1,293 @@
+"""Read-only replay fence for the pinned CLI's asynchronous session/load.
+
+Gemini 0.64.0 returns load before streamHistory finishes, with no replay-end
+notification. Match a bounded native snapshot BEFORE sending a new prompt.
+Unknown formats fail closed; this is not an import/reconciliation API.
+"""
+from __future__ import annotations
+
+import hashlib
+from copy import deepcopy
+import json
+import os
+from pathlib import Path
+import stat
+import math
+
+from gemini_acp_client import GeminiProtocolError, identifier
+from gemini_runtime import native_home
+
+MAX_BYTES = 16 * 1024 * 1024
+MAX_ENTRIES = 10000
+
+
+def replay_text(value) -> str:
+    """Match pinned partListUnionToString for supported text/tool history.
+
+    Native skill/tool responses are user-role functionResponse parts. They
+    replay as placeholders, not additional user turns. This is only a replay
+    fence: do not import those placeholders into the AgentsDock timeline.
+    Unknown media/part shapes still fail closed.
+    """
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        if len(value) > MAX_ENTRIES or any(isinstance(part, list) for part in value):
+            raise GeminiProtocolError("Unsupported Gemini replay part list.")
+        return "".join(replay_text(part) for part in value)
+    if isinstance(value, dict):
+        if set(value) <= {"text", "thought", "thoughtSignature"} and isinstance(value.get("text"), str):
+            if "thought" in value:
+                if not isinstance(value["thought"], bool):
+                    raise GeminiProtocolError("Invalid Gemini native thought part.")
+                return "[Thought: true]" if value["thought"] else "[Thought: false]"
+            return value["text"]
+        for key, label in (("functionCall", "Function Call"), ("functionResponse", "Function Response")):
+            if set(value) <= {key, "thoughtSignature"} and isinstance(value.get(key), dict):
+                name = identifier(value[key].get("name"))
+                return f"[{label}: {name}]"
+        if set(value) <= {"inlineData", "thoughtSignature"} and isinstance(value.get("inlineData"), dict):
+            media = value["inlineData"]
+            mime, data = media.get("mimeType"), media.get("data")
+            if isinstance(mime, str) and isinstance(data, str):
+                category = next((label for prefix, label in (("audio/", "Audio"), ("video/", "Video"), ("image/", "Image")) if mime.startswith(prefix)), "Media")
+                # Match JS toFixed(1), including its half-up behavior.
+                kb = math.floor(math.ceil(len(data) * 3 / 4) / 1024 * 10 + .5) / 10
+                return f"[{category}: {mime}, {kb:.1f} KB]"
+    raise GeminiProtocolError("This Gemini history format needs a newer resume adapter; continue it in Gemini CLI.")
+
+
+def fingerprint(update: dict) -> tuple[str, str]:
+    kind = update.get("sessionUpdate")
+    if kind in {"user_message_chunk", "agent_message_chunk", "agent_thought_chunk"}:
+        content = update.get("content")
+        if not isinstance(content, dict) or content.get("type") != "text" or not isinstance(content.get("text"), str):
+            raise GeminiProtocolError("Unsupported Gemini replay content.")
+        return kind, hashlib.sha256(content["text"].encode()).hexdigest()
+    if kind == "tool_call":
+        return kind, identifier(update.get("toolCallId"))
+    raise GeminiProtocolError("Unsupported Gemini replay event.")
+
+
+def native_snapshot(env: dict[str, str], cwd: str, session_id: str, *, missing_ok: bool = False) -> dict | None:
+    identifier(session_id, session=True)
+    root = native_home(env) / ".gemini" / "tmp"
+    found = []
+    count = 0
+    def entries(directory):
+        nonlocal count
+        if directory.is_symlink():
+            raise GeminiProtocolError("Linked Gemini history cannot be resumed safely.")
+        with os.scandir(directory) as iterator:
+            for entry in iterator:
+                count += 1
+                if count > MAX_ENTRIES:
+                    raise GeminiProtocolError("Gemini history exceeds the supported scan limit.")
+                yield entry
+    try:
+        if missing_ok and not root.exists():
+            return None
+        for project in entries(root):
+            if not project.is_dir(follow_symlinks=False):
+                continue
+            chats = Path(project.path) / "chats"
+            if not chats.is_dir():
+                continue
+            for entry in entries(chats):
+                if (entry.name.startswith("session-") and entry.name.endswith((f"-{session_id[:8]}.json", f"-{session_id[:8]}.jsonl"))
+                        and entry.is_file(follow_symlinks=False)):
+                    value = read_snapshot(Path(entry.path))
+                    if value.get("sessionId") == session_id:
+                        found.append(value)
+    except (OSError, ValueError, TypeError, RecursionError):
+        raise GeminiProtocolError("Gemini native history cannot be safely read for resume.") from None
+    if not found and missing_ok:
+        return None
+    if len(found) != 1 or found[0].get("projectHash") != hashlib.sha256(cwd.encode()).hexdigest():
+        raise GeminiProtocolError("Gemini native history does not uniquely match this chat and workspace.")
+    return found[0]
+
+
+def replay_snapshot(env: dict[str, str], cwd: str, session_id: str) -> list[tuple[str, str]]:
+    return snapshot_replay(native_snapshot(env, cwd, session_id))
+
+
+def snapshot_replay(snapshot: dict) -> list[tuple[str, str]]:
+    result = []
+    for message in snapshot["messages"]:
+        if not isinstance(message, dict):
+            raise GeminiProtocolError("Invalid Gemini native message.")
+        kind = message.get("type")
+        if kind not in {"user", "gemini"}:
+            continue  # Pinned streamHistory ignores native info/error records.
+        content = replay_text(message.get("content"))
+        if kind == "gemini":
+            for thought in message.get("thoughts") or []:
+                if not isinstance(thought, dict) or not all(isinstance(thought.get(key), str) for key in ("subject", "description")):
+                    raise GeminiProtocolError("Invalid Gemini native thought.")
+                result.append(fingerprint({"sessionUpdate": "agent_thought_chunk", "content": {"type": "text", "text": f"**{thought['subject']}**\n{thought['description']}"}}))
+        if content.strip():
+            result.append(fingerprint({"sessionUpdate": "user_message_chunk" if kind == "user" else "agent_message_chunk", "content": {"type": "text", "text": content}}))
+        if kind == "gemini":
+            for tool in message.get("toolCalls") or []:
+                result.append(fingerprint({"sessionUpdate": "tool_call", "toolCallId": tool.get("id")}))
+        if len(result) > MAX_ENTRIES:
+            raise GeminiProtocolError("Gemini replay exceeds the supported limit.")
+    return result
+
+
+def verify_resume_snapshot(before: dict, after: dict) -> None:
+    """Allow only the pinned loader's exact text/tool normalization.
+
+    streamHistory emits the pre-normalization messages, while resumeChat writes
+    converted model parts and deterministic *_response rows back to disk. Merely
+    comparing replay fingerprints therefore rejects every resumed tool turn.
+    Preserve the concurrency fence by predicting those mutations, not by
+    dropping it or allowing arbitrary appended records.
+    """
+    failure = "Gemini history changed during resume; close the other client before retrying."
+    if any(before.get(key) != after.get(key) for key in ("sessionId", "projectHash")):
+        raise GeminiProtocolError(failure)
+    if before["messages"] == after["messages"]:
+        return
+    records = deepcopy(before["messages"])
+    by_id = {row["id"]: row for row in records}
+    if len(by_id) != len(records):
+        raise GeminiProtocolError(failure)
+    converted = []
+    generated = set()
+    empty_model_ids = set()
+
+    def parts(value):
+        values = value if isinstance(value, list) else [value]
+        return [{"text": part} if isinstance(part, str) else deepcopy(part) for part in values]
+
+    for row in records:
+        kind, content = row.get("type"), row.get("content")
+        if kind == "user":
+            text = replay_text(content).strip()
+            if not text or text.startswith(("/", "?", "<session_context>", "<hook_context>")):
+                continue
+            row["content"] = parts(content)
+            converted.append(row)
+        elif kind == "gemini":
+            model_parts = parts(content) if content else []
+            if not any(p.get("functionCall") or p.get("thought") for p in model_parts):
+                thoughts = [{"text": f"**{t['subject']}** {t['description']}" if t.get("subject") else t["description"],
+                             "thought": True} for t in row.get("thoughts", [])]
+                calls = [{"functionCall": {key: tool[key] for key in ("id", "name", "args")}}
+                         for tool in row.get("toolCalls", [])]
+                model_parts = thoughts + model_parts + calls
+            if not model_parts:
+                empty_model_ids.add(row["id"])
+                continue
+            row["content"] = model_parts
+            converted.append(row)
+            responses = []
+            for tool in row.get("toolCalls", []):
+                value = tool.get("result")
+                if not value:
+                    continue
+                if isinstance(value, str):
+                    responses.append({"functionResponse": {"id": tool["id"], "name": tool["name"], "response": {"output": value}}})
+                else:
+                    responses.extend(parts(value))
+            if responses:
+                key = row["id"] + "_response"
+                response = deepcopy(by_id.get(key, {"id": key, "type": "user"}))
+                if response.get("type") != "user":
+                    raise GeminiProtocolError(failure)
+                response["content"] = responses
+                generated.add(key)
+                converted.append(response)
+    # updateMessagesFromHistory keeps ignored native context/info records, then
+    # writes converted orderIds. Native JSONL loading de-duplicates those IDs.
+    ordered = {row["id"]: row for row in converted}
+    tools = {tool["id"]: tool for row in records for tool in row.get("toolCalls", [])}
+    for row in converted:
+        if row.get("type") == "user":
+            for part in row["content"]:
+                response = part.get("functionResponse", {})
+                if response.get("id") in tools:
+                    tools[response["id"]]["result"] = deepcopy(row["content"])
+    # Cancelling while awaiting approval can leave an empty model record. The
+    # native loader drops precisely these records, not user text/tool history.
+    expected = [row for row in records if row["id"] not in ordered and row["id"] not in empty_model_ids] + list(ordered.values())
+    actual = deepcopy(after["messages"])
+    # Pinned startChat rebuilds its leading environment header (directory tree,
+    # date, etc.) on resume. A tool that created a file legitimately changes it.
+    # Only that first, exact native context row is allowed to refresh; real user
+    # content, tool results, identities, metadata and additional rows stay exact.
+    def environment_header(row):
+        parts = row.get("content")
+        return (row.get("type") == "user" and isinstance(parts, list) and len(parts) == 1
+                and isinstance(parts[0], dict) and set(parts[0]) == {"text"}
+                and isinstance(parts[0]["text"], str)
+                and parts[0]["text"].startswith("<session_context>\n")
+                and parts[0]["text"].endswith("\n</session_context>"))
+    if expected and actual and environment_header(expected[0]) and environment_header(actual[0]):
+        if {k: v for k, v in expected[0].items() if k != "content"} == {k: v for k, v in actual[0].items() if k != "content"}:
+            actual[0]["content"] = expected[0]["content"]
+    for rows in (expected, actual):
+        for row in rows:
+            if row["id"] in generated and row["id"] not in by_id:
+                row.pop("timestamp", None)  # The only newly generated metadata.
+    if expected != actual:
+        raise GeminiProtocolError(failure)
+
+
+def read_snapshot(path: Path) -> dict:
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    with os.fdopen(descriptor, "rb") as handle:
+        before = os.fstat(handle.fileno())
+        if not stat.S_ISREG(before.st_mode) or before.st_size > MAX_BYTES:
+            raise GeminiProtocolError("Gemini history exceeds the supported file limit.")
+        raw = handle.read(MAX_BYTES + 1)
+        after = os.fstat(handle.fileno())
+        if len(raw) > MAX_BYTES or (before.st_size, before.st_mtime_ns) != (after.st_size, after.st_mtime_ns):
+            raise GeminiProtocolError("Gemini history changed while preparing resume; retry after the other client stops.")
+    if path.suffix == ".json":
+        return json.loads(raw)
+    metadata, messages = {}, {}
+    for line in raw.splitlines():
+        if not line.strip():
+            continue
+        value = json.loads(line)
+        if not isinstance(value, dict):
+            raise GeminiProtocolError("Invalid Gemini history record.")
+        if "$rewindTo" in value:
+            ids = list(messages)
+            target = value["$rewindTo"]
+            messages = {key: messages[key] for key in ids[:ids.index(target)]} if target in ids else {}
+        elif "$patch" in value:
+            patch = value["$patch"]
+            if not isinstance(patch, dict) or set(patch) - {"id", "content", "toolCalls", "updates", "removeIds", "orderIds"}:
+                raise GeminiProtocolError("Unsupported Gemini history patch.")
+            for update in ([patch] if "id" in patch else []) + patch.get("updates", []):
+                if not isinstance(update, dict) or set(update) - {"id", "content", "toolCalls"}:
+                    raise GeminiProtocolError("Unsupported Gemini message patch.")
+                existing = messages.get(update.get("id"))
+                if existing and "content" in update:
+                    existing["content"] = update["content"]
+                for tool_patch in update.get("toolCalls", []):
+                    if not isinstance(tool_patch, dict) or set(tool_patch) - {"id", "result"}:
+                        raise GeminiProtocolError("Unsupported Gemini tool-result patch.")
+                    tool = next((row for row in (existing or {}).get("toolCalls", []) if row.get("id") == tool_patch.get("id")), None)
+                    if tool is not None and "result" in tool_patch:
+                        tool["result"] = tool_patch["result"]
+            for key in patch.get("removeIds", []):
+                messages.pop(key, None)
+            order = patch.get("orderIds", [])
+            if order:
+                messages = {**{key: row for key, row in messages.items() if key not in order},
+                            **{key: messages[key] for key in order if key in messages}}
+        elif "id" in value:
+            messages[value["id"]] = value
+        else:
+            update = value.get("$set", value)
+            if "messages" in update:
+                messages = {row["id"]: row for row in update["messages"]}
+            metadata.update(update)
+    return {**metadata, "messages": list(messages.values())}

package/server/gemini_import.py

@@ -0,0 +1,126 @@
+"""Read-only Gemini 0.64 main-session discovery and initial text snapshots.
+
+The native .project_root marker plus transcript hash binds an exact workspace.
+Never reverse a slug, launch Gemini, or treat tool responses as user messages.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+import stat
+
+from gemini_acp_client import GeminiProtocolError, identifier
+from gemini_history import MAX_ENTRIES, read_snapshot
+from gemini_runtime import native_home
+
+
+def _regular_text(path: Path) -> str:
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    with os.fdopen(descriptor, "rb") as handle:
+        info = os.fstat(handle.fileno())
+        if not stat.S_ISREG(info.st_mode) or info.st_size > 16384:
+            raise ValueError("Invalid Gemini workspace marker")
+        raw = handle.read(16385)
+    if len(raw) > 16384:
+        raise ValueError("Invalid Gemini workspace marker")
+    return raw.decode("utf-8").strip()
+
+
+def records(env: dict):
+    root = native_home(env) / ".gemini" / "tmp"
+    if not root.exists():
+        return
+    if root.is_symlink() or root.parent.is_symlink():
+        raise GeminiProtocolError("Linked Gemini history is not supported.")
+    count = 0
+    with os.scandir(root) as projects:
+        for project in projects:
+            count += 1
+            if count > MAX_ENTRIES:
+                raise GeminiProtocolError("Gemini discovery exceeded its scan limit.")
+            if not project.is_dir(follow_symlinks=False):
+                continue
+            directory = Path(project.path)
+            chats = directory / "chats"
+            try:
+                cwd = _regular_text(directory / ".project_root")
+                if not Path(cwd).is_absolute() or not Path(cwd).is_dir() or os.path.normpath(cwd) != cwd:
+                    continue
+                if chats.is_symlink() or not chats.is_dir():
+                    continue
+                with os.scandir(chats) as entries:
+                    for entry in entries:
+                        count += 1
+                        if count > MAX_ENTRIES:
+                            raise GeminiProtocolError("Gemini discovery exceeded its scan limit.")
+                        if not entry.name.startswith("session-") or not entry.name.endswith((".json", ".jsonl")) or not entry.is_file(follow_symlinks=False):
+                            continue
+                        try:
+                            path = Path(entry.path)
+                            value = read_snapshot(path)
+                            provider_id = identifier(value.get("sessionId"), session=True)
+                            if (value.get("kind", "main") != "main" or value.get("archived") or value.get("deleted")
+                                    or value.get("parentSessionId") or value.get("projectHash") != hashlib.sha256(cwd.encode()).hexdigest()
+                                    or not any(row.get("type") == "gemini" for row in value["messages"])):
+                                continue
+                            yield path, cwd, provider_id, value
+                        except (OSError, ValueError, TypeError, KeyError, AttributeError, RecursionError, GeminiProtocolError):
+                            continue  # A malformed entry cannot hide other main conversations.
+            except (OSError, ValueError, UnicodeError):
+                continue
+
+
+def visible_items(api, snapshot: dict) -> list[dict]:
+    result = []
+    for row in snapshot["messages"]:
+        role = row.get("type")
+        if role not in {"user", "gemini"}:
+            continue
+        content = row.get("content")
+        parts = content if isinstance(content, list) else [content]
+        # A user-role functionResponse is tool I/O, never a new human turn.
+        if role == "user" and any(isinstance(part, dict) and "functionResponse" in part for part in parts):
+            continue
+        text = "".join(part if isinstance(part, str) else part.get("text", "")
+                       if isinstance(part, dict) and not part.get("thought") else "" for part in parts)
+        if role == "user":
+            if text.lstrip().startswith(("<session_context>", "<hook_context>", "/", "?")):
+                continue
+            text = api.strip_agentsdock_provider_context(text, allow_jobless_legacy=True)
+            text = api.strip_agentsdock_generated_user_text(text, provider_history=True)
+        if text.strip():
+            result.append({"kind": "user" if role == "user" else "assistant", "text": text,
+                           "provider_message_id": identifier(row.get("id"))})
+    return result
+
+
+def candidates(api, env: dict, known: set[str]) -> list[dict]:
+    unique, ambiguous = {}, set()
+    for path, cwd, provider_id, snapshot in records(env):
+        if provider_id in known:
+            continue
+        if provider_id in unique:
+            ambiguous.add(provider_id)
+            continue
+        try:
+            items = visible_items(api, snapshot)
+            first_user = next((item["text"] for item in items if item["kind"] == "user"), None)
+            if not first_user:
+                continue
+            unique[provider_id] = {"provider_session_id": provider_id, "backend": "gemini", "cwd": cwd,
+                "label": api.local_session_label(api.native_session_title(snapshot.get("summary")) or first_user, f"Gemini chat {provider_id[:8]}"),
+                "updated_at": api.iso_from_timestamp(path.stat().st_mtime)}
+        except (OSError, ValueError, GeminiProtocolError):
+            continue
+    return [value for key, value in unique.items() if key not in ambiguous]
+
+
+def initial_history(api, env: dict, provider_id: str, cwd: str, limit=None):
+    identifier(provider_id, session=True)
+    matches = [(path, value) for path, workspace, pid, value in records(env) if pid == provider_id and workspace == cwd]
+    if len(matches) != 1:
+        raise GeminiProtocolError("Gemini history does not uniquely match this ID and workspace.")
+    path, value = matches[0]
+    items = visible_items(api, value)
+    return path, items[-limit:] if limit else items