copass-context-agents 0.1.0__tar.gz

copass_context_agents-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+coverage/
+
+# Lerna
+lerna-debug.log
+.nx/cache
+.nx/workspace-data
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.venv/
+venv/
+.olane

copass_context_agents-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: copass-context-agents
+Version: 0.1.0
+Summary: Copass context-engineering primitives (retrieval tools, ingest tool, Context Window turn recorder) for copass-core-agents
+Project-URL: Homepage, https://github.com/olane-labs/copass-harness
+Project-URL: Repository, https://github.com/olane-labs/copass-harness.git
+Author: Olane Inc.
+License: MIT
+Keywords: agents,context-window,copass,ingest,knowledge-graph,retrieval
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: copass-config>=0.1.0
+Requires-Dist: copass-core-agents>=0.1.0
+Requires-Dist: copass-core>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# copass-context-agents
+
+Copass context-engineering primitives for `copass-core-agents`.
+
+Three provider-neutral pieces every Copass-aware agent uses:
+
+- **`copass_retrieval_tools(...)`** — returns `discover` / `interpret` / `search` as `AgentTool` instances, window-aware when a `ContextWindow` is passed.
+- **`copass_ingest_tool(...)`** — returns `ingest` as an `AgentTool` so agents can promote content into durable sandbox storage.
+- **`CopassTurnRecorder`** — mirrors user / assistant turns into a `ContextWindow` with fire-and-forget pushes and author-prefix provenance.
+
+These are the primitives the provider adapter packages — `copass-anthropic-agents`, `copass-google-agents` — compose into their `run()` / `stream()` loops. The descriptions come from `copass_config` so every Copass surface (TS adapters, MCP server, CLI) shows the LLM identical tool semantics.
+
+## Install
+
+```bash
+pip install copass-context-agents
+```
+
+Usually a transitive dep — `pip install copass-anthropic-agents` / `copass-google-agents` pulls it in.
+
+## Usage
+
+```python
+from copass_core import CopassClient
+from copass_context_agents import (
+    copass_retrieval_tools,
+    copass_ingest_tool,
+    CopassTurnRecorder,
+)
+
+client = CopassClient(...)
+window = await client.context_window.create(sandbox_id=sandbox_id)
+
+tools = [
+    *copass_retrieval_tools(client=client, sandbox_id=sandbox_id, window=window),
+    copass_ingest_tool(
+        client=client,
+        sandbox_id=sandbox_id,
+        data_source_id=my_source_id,
+        default_source_type="decision",
+        author="agent:support-bot",
+    ),
+]
+
+recorder = CopassTurnRecorder(window=window, author="agent:support-bot", include_author_prefix=True)
+# ...wire into your provider's stream loop; see copass-anthropic-agents or
+# copass-google-agents for the full wiring.
+```
+
+See the provider adapter packages for the full `CopassManagedAgent` / `CopassGoogleAgent` integrations that wire these primitives into discover-as-step-1 + auto-record flows.

copass_context_agents-0.1.0/README.md

@@ -0,0 +1,50 @@
+# copass-context-agents
+
+Copass context-engineering primitives for `copass-core-agents`.
+
+Three provider-neutral pieces every Copass-aware agent uses:
+
+- **`copass_retrieval_tools(...)`** — returns `discover` / `interpret` / `search` as `AgentTool` instances, window-aware when a `ContextWindow` is passed.
+- **`copass_ingest_tool(...)`** — returns `ingest` as an `AgentTool` so agents can promote content into durable sandbox storage.
+- **`CopassTurnRecorder`** — mirrors user / assistant turns into a `ContextWindow` with fire-and-forget pushes and author-prefix provenance.
+
+These are the primitives the provider adapter packages — `copass-anthropic-agents`, `copass-google-agents` — compose into their `run()` / `stream()` loops. The descriptions come from `copass_config` so every Copass surface (TS adapters, MCP server, CLI) shows the LLM identical tool semantics.
+
+## Install
+
+```bash
+pip install copass-context-agents
+```
+
+Usually a transitive dep — `pip install copass-anthropic-agents` / `copass-google-agents` pulls it in.
+
+## Usage
+
+```python
+from copass_core import CopassClient
+from copass_context_agents import (
+    copass_retrieval_tools,
+    copass_ingest_tool,
+    CopassTurnRecorder,
+)
+
+client = CopassClient(...)
+window = await client.context_window.create(sandbox_id=sandbox_id)
+
+tools = [
+    *copass_retrieval_tools(client=client, sandbox_id=sandbox_id, window=window),
+    copass_ingest_tool(
+        client=client,
+        sandbox_id=sandbox_id,
+        data_source_id=my_source_id,
+        default_source_type="decision",
+        author="agent:support-bot",
+    ),
+]
+
+recorder = CopassTurnRecorder(window=window, author="agent:support-bot", include_author_prefix=True)
+# ...wire into your provider's stream loop; see copass-anthropic-agents or
+# copass-google-agents for the full wiring.
+```
+
+See the provider adapter packages for the full `CopassManagedAgent` / `CopassGoogleAgent` integrations that wire these primitives into discover-as-step-1 + auto-record flows.

copass_context_agents-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copass-context-agents"
+version = "0.1.0"
+description = "Copass context-engineering primitives (retrieval tools, ingest tool, Context Window turn recorder) for copass-core-agents"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Olane Inc." }]
+requires-python = ">=3.10"
+keywords = [
+    "copass",
+    "knowledge-graph",
+    "agents",
+    "context-window",
+    "retrieval",
+    "ingest",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "copass-core>=0.1.0",
+    "copass-core-agents>=0.1.0",
+    "copass-config>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.10",
+    "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/olane-labs/copass-harness"
+Repository = "https://github.com/olane-labs/copass-harness.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/copass_context_agents"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

copass_context_agents-0.1.0/src/copass_context_agents/__init__.py

@@ -0,0 +1,28 @@
+"""Copass context-engineering primitives for the core agent runtime.
+
+Three provider-neutral pieces every Copass-aware agent composes:
+
+* :func:`copass_retrieval_tools` — ``discover`` / ``interpret`` /
+  ``search`` as :class:`AgentTool` instances.
+* :func:`copass_ingest_tool` — ``ingest`` as an :class:`AgentTool`.
+* :class:`CopassTurnRecorder` — mirror conversation turns into a
+  Copass :class:`ContextWindow`.
+
+Sits between :mod:`copass_core_agents` (the ABCs / runtime) and the
+per-provider adapter packages
+(:mod:`copass_anthropic_agents`, :mod:`copass_google_agents`) which
+compose these primitives into their ``run()`` / ``stream()`` loops.
+"""
+
+from copass_context_agents.ingest_tool import copass_ingest_tool
+from copass_context_agents.retrieval_tools import copass_retrieval_tools
+from copass_context_agents.turn_recorder import CopassTurnRecorder
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "copass_retrieval_tools",
+    "copass_ingest_tool",
+    "CopassTurnRecorder",
+]

copass_context_agents-0.1.0/src/copass_context_agents/ingest_tool.py

@@ -0,0 +1,181 @@
+"""Copass ingestion as a provider-neutral :class:`AgentTool`.
+
+Python analogue of the ``ingest`` tool registered by
+``typescript/packages/mcp/src/tools/ingest.ts``. Same HTTP call
+(``client.sources.ingest(...)``), same semantics — just shaped for
+the core agent runtime's tool catalog.
+
+Intent: let an agent **voluntarily commit** content worth preserving
+into durable sandbox storage. Complements
+:class:`CopassTurnRecorder`, which mirrors every turn into the
+ephemeral Context Window. The LLM calls ``ingest`` when it learns
+something that should outlive this conversation — architecture
+decisions, user-shared framing, corrections, durable notes.
+
+Not for turn-by-turn capture. Every agent turn is already pushed to
+the Context Window by :class:`CopassTurnRecorder`. Ingest is the
+intentional "promote this to durable knowledge" call. The LLM-facing
+description says so explicitly.
+
+Cache-safety: same story as the retrieval tools — :class:`ToolSpec`
+is built from frozen strings + a constant JSON schema, so rebuilding
+on each invocation yields an identical fingerprint and the
+provider's agent cache keeps hitting.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from copass_core import CopassClient
+from copass_core_agents.base_tool import AgentTool, ToolSpec
+from copass_core_agents.invocation_context import AgentInvocationContext
+
+
+# Canonical copy with `typescript/packages/mcp/src/tools/ingest.ts`. When
+# `INGEST_DESCRIPTION` lands in `copass_config.tool_descriptions` (and
+# `@copass/config`), switch this + the MCP server to an import.
+_INGEST_DESCRIPTION = (
+    "Push content into the knowledge graph via a data source. Use for: "
+    'architecture decisions (source_type: "decision"), user-shared context '
+    '("user_input"), corrections ("correction"), durable notes, any '
+    "significant new concept. Do NOT ingest trivial changes or ephemeral "
+    "debug context — those belong in the Context Window (every agent turn "
+    "is already mirrored there automatically). Call this only when the "
+    "content is worth preserving beyond the current conversation."
+)
+
+_CONTENT_PARAM = "The content to ingest. Non-empty."
+_SOURCE_TYPE_PARAM = (
+    "Type tag: code, markdown, json, text, conversation, decision, correction, "
+    "user_input. Defaults to the tool's configured default_source_type when omitted."
+)
+_STORAGE_ONLY_PARAM = "If true, chunk and store but skip ontology ingestion."
+
+
+class _CopassIngestTool(AgentTool):
+    def __init__(
+        self,
+        *,
+        client: CopassClient,
+        sandbox_id: str,
+        data_source_id: str,
+        project_id: Optional[str],
+        default_source_type: str,
+        author: Optional[str],
+    ) -> None:
+        self._client = client
+        self._sandbox_id = sandbox_id
+        self._data_source_id = data_source_id
+        self._project_id = project_id
+        self._default_source_type = default_source_type
+        self._author = author
+
+    @property
+    def spec(self) -> ToolSpec:
+        return ToolSpec(
+            name="ingest",
+            description=_INGEST_DESCRIPTION,
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "content": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": _CONTENT_PARAM,
+                    },
+                    "source_type": {
+                        "type": "string",
+                        "description": _SOURCE_TYPE_PARAM,
+                    },
+                    "storage_only": {
+                        "type": "boolean",
+                        "description": _STORAGE_ONLY_PARAM,
+                    },
+                },
+                "required": ["content"],
+                "additionalProperties": False,
+            },
+        )
+
+    async def invoke(
+        self,
+        arguments: dict,
+        *,
+        context: Optional[AgentInvocationContext] = None,
+    ) -> dict:
+        content = str(arguments.get("content", "")).strip()
+        if not content:
+            return {"error": "content is required and must be non-empty"}
+
+        # Provenance prefix — until the ingest API / ChatMessage grow
+        # a first-class author envelope, embed it as a structured
+        # header so downstream retrieval can see who committed this
+        # knowledge.
+        if self._author:
+            content = f"[author={self._author}]\n{content}"
+
+        source_type = arguments.get("source_type") or self._default_source_type
+        storage_only = arguments.get("storage_only")
+
+        response = await self._client.sources.ingest(
+            self._sandbox_id,
+            self._data_source_id,
+            text=content,
+            source_type=source_type,
+            storage_only=storage_only,
+            project_id=self._project_id,
+        )
+        return {
+            "job_id": response.get("job_id"),
+            "status": response.get("status"),
+            "data_source_id": self._data_source_id,
+        }
+
+
+def copass_ingest_tool(
+    *,
+    client: CopassClient,
+    sandbox_id: str,
+    data_source_id: str,
+    project_id: Optional[str] = None,
+    default_source_type: str = "text",
+    author: Optional[str] = None,
+) -> AgentTool:
+    """Return the ``ingest`` :class:`AgentTool`.
+
+    Args:
+        client: An authenticated :class:`copass_core.CopassClient`.
+        sandbox_id: Sandbox the target data source lives in.
+        data_source_id: Target data source for durable ingestion.
+            Must be pre-registered — use
+            ``client.sources.register(sandbox_id, ...)`` or the
+            ``copass source register`` CLI to create one.
+        project_id: Optional project scoping.
+        default_source_type: Default ``source_type`` when the model
+            omits the argument. ``"text"`` matches the MCP server's
+            behavior; override to ``"conversation"`` for chat-style
+            agents or ``"decision"`` for agents whose primary job
+            is architecture capture.
+        author: Optional identifier of whoever is running the agent
+            (``"agent:support-bot"``, ``"user"``, etc.). When set,
+            ingested content is prefixed with ``"[author=...]\\n"``
+            so retrieval can distinguish provenance. Remove once the
+            ingest API / :class:`ChatMessage` grows a first-class
+            author field.
+
+    Returns:
+        One :class:`AgentTool` — register it via
+        ``AgentToolRegistry.add(...)``.
+    """
+    return _CopassIngestTool(
+        client=client,
+        sandbox_id=sandbox_id,
+        data_source_id=data_source_id,
+        project_id=project_id,
+        default_source_type=default_source_type,
+        author=author,
+    )
+
+
+__all__ = ["copass_ingest_tool"]

copass_context_agents-0.1.0/src/copass_context_agents/retrieval_tools.py

@@ -0,0 +1,301 @@
+"""Copass retrieval as provider-neutral :class:`AgentTool` instances.
+
+Python analogue of ``typescript/packages/langchain/src/tools.ts`` ·
+``copassTools(...)``. Returns the three context-engineering primitives
+— ``discover``, ``interpret``, ``search`` — shaped for the core agent
+runtime, so any :class:`BaseAgent` subclass (Anthropic managed agents,
+Google Vertex AI Agent Engine, …) registers them with one call.
+
+Why these three, and why always together:
+
+* ``discover`` — window-aware ranked menu. Cheap, repeatable, and the
+  first call every agent should make when a new goal lands. Because
+  the server filters items already surfaced in this conversation's
+  window, subsequent calls always return NEW signal — agents can
+  lean on it freely without wasting tokens.
+* ``interpret`` — paragraph brief pinned to specific items returned
+  by ``discover``. Lets the model drill down without paying for a
+  full retrieval round-trip.
+* ``search`` — one-shot synthesized answer. Heavier; prefer
+  ``discover`` → ``interpret`` for exploration.
+
+Descriptions come from :mod:`copass_config` — the single source of
+truth the TypeScript ``@copass/config`` package mirrors. Editing here
+is a bug; edit the shared module and rebuild all adapters.
+
+Cache-safety note (Anthropic Managed Agents):
+
+    Provider adapters that cache managed-agent resources by a
+    fingerprint of ``(model, system_prompt, tool_specs)`` rely on
+    :class:`ToolSpec` being stable across invocations. Every spec
+    returned here is built from frozen module-level strings +
+    a constant JSON schema — so rebuilding the tool list on each
+    invocation produces an identical fingerprint. Re-creating the
+    tools does NOT invalidate the cache. Safe to call
+    :func:`copass_retrieval_tools` once at agent construction and
+    forget about it.
+
+Example::
+
+    from copass_core import CopassClient
+    from copass_core_agents import AgentToolRegistry
+    from copass_context_agents import copass_retrieval_tools
+
+    copass = CopassClient(...)
+    window = await copass.context_window.create(sandbox_id=sandbox_id)
+
+    registry = AgentToolRegistry()
+    registry.extend(
+        copass_retrieval_tools(
+            client=copass,
+            sandbox_id=sandbox_id,
+            window=window,
+        )
+    )
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from copass_config.param_descriptions import (
+    DISCOVER_QUERY_PARAM,
+    INTERPRET_ITEMS_PARAM,
+    INTERPRET_QUERY_PARAM,
+    SEARCH_QUERY_PARAM,
+)
+from copass_config.tool_descriptions import (
+    DISCOVER_DESCRIPTION,
+    INTERPRET_DESCRIPTION,
+    SEARCH_DESCRIPTION,
+)
+from copass_core import CopassClient
+from copass_core.types import SearchPreset, WindowLike
+from copass_core_agents.base_tool import AgentTool, ToolSpec
+from copass_core_agents.invocation_context import AgentInvocationContext
+
+
+class _CopassDiscoverTool(AgentTool):
+    def __init__(
+        self,
+        *,
+        client: CopassClient,
+        sandbox_id: str,
+        project_id: Optional[str],
+        window: Optional[WindowLike],
+    ) -> None:
+        self._client = client
+        self._sandbox_id = sandbox_id
+        self._project_id = project_id
+        self._window = window
+
+    @property
+    def spec(self) -> ToolSpec:
+        return ToolSpec(
+            name="discover",
+            description=DISCOVER_DESCRIPTION,
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": DISCOVER_QUERY_PARAM,
+                    },
+                },
+                "required": ["query"],
+                "additionalProperties": False,
+            },
+        )
+
+    async def invoke(
+        self,
+        arguments: dict,
+        *,
+        context: Optional[AgentInvocationContext] = None,
+    ) -> dict:
+        response = await self._client.retrieval.discover(
+            self._sandbox_id,
+            query=str(arguments.get("query", "")),
+            project_id=self._project_id,
+            window=self._window,
+        )
+        return {
+            "header": response.get("header"),
+            "items": [
+                {
+                    "score": item.get("score"),
+                    "summary": item.get("summary"),
+                    "canonical_ids": item.get("canonical_ids", []),
+                }
+                for item in response.get("items", [])
+            ],
+            "next_steps": response.get("next_steps"),
+        }
+
+
+class _CopassInterpretTool(AgentTool):
+    def __init__(
+        self,
+        *,
+        client: CopassClient,
+        sandbox_id: str,
+        project_id: Optional[str],
+        window: Optional[WindowLike],
+        preset: SearchPreset,
+    ) -> None:
+        self._client = client
+        self._sandbox_id = sandbox_id
+        self._project_id = project_id
+        self._window = window
+        self._preset = preset
+
+    @property
+    def spec(self) -> ToolSpec:
+        return ToolSpec(
+            name="interpret",
+            description=INTERPRET_DESCRIPTION,
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": INTERPRET_QUERY_PARAM,
+                    },
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "minItems": 1,
+                        },
+                        "minItems": 1,
+                        "description": INTERPRET_ITEMS_PARAM,
+                    },
+                },
+                "required": ["query", "items"],
+                "additionalProperties": False,
+            },
+        )
+
+    async def invoke(
+        self,
+        arguments: dict,
+        *,
+        context: Optional[AgentInvocationContext] = None,
+    ) -> dict:
+        raw_items = arguments.get("items", []) or []
+        items: List[List[str]] = [
+            [str(x) for x in tup] for tup in raw_items if tup
+        ]
+        response = await self._client.retrieval.interpret(
+            self._sandbox_id,
+            query=str(arguments.get("query", "")),
+            items=items,
+            project_id=self._project_id,
+            window=self._window,
+            preset=self._preset,
+        )
+        return {"brief": response.get("brief")}
+
+
+class _CopassSearchTool(AgentTool):
+    def __init__(
+        self,
+        *,
+        client: CopassClient,
+        sandbox_id: str,
+        project_id: Optional[str],
+        window: Optional[WindowLike],
+        preset: SearchPreset,
+    ) -> None:
+        self._client = client
+        self._sandbox_id = sandbox_id
+        self._project_id = project_id
+        self._window = window
+        self._preset = preset
+
+    @property
+    def spec(self) -> ToolSpec:
+        return ToolSpec(
+            name="search",
+            description=SEARCH_DESCRIPTION,
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": SEARCH_QUERY_PARAM,
+                    },
+                },
+                "required": ["query"],
+                "additionalProperties": False,
+            },
+        )
+
+    async def invoke(
+        self,
+        arguments: dict,
+        *,
+        context: Optional[AgentInvocationContext] = None,
+    ) -> dict:
+        response = await self._client.retrieval.search(
+            self._sandbox_id,
+            query=str(arguments.get("query", "")),
+            project_id=self._project_id,
+            window=self._window,
+            preset=self._preset,
+        )
+        return {"answer": response.get("answer")}
+
+
+def copass_retrieval_tools(
+    *,
+    client: CopassClient,
+    sandbox_id: str,
+    project_id: Optional[str] = None,
+    window: Optional[WindowLike] = None,
+    preset: SearchPreset = "auto",
+) -> List[AgentTool]:
+    """Return ``[discover, interpret, search]`` as :class:`AgentTool` instances.
+
+    Args:
+        client: An authenticated :class:`copass_core.CopassClient`.
+        sandbox_id: Sandbox all retrieval runs against.
+        project_id: Optional project scoping applied to every call.
+        window: Optional :class:`WindowLike` (typically a
+            :class:`ContextWindow`). When set, every retrieval call
+            is window-aware — repeated ``discover`` calls skip items
+            already surfaced earlier in this conversation.
+        preset: Preset for ``interpret`` / ``search``. Defaults to
+            ``"auto"`` — required for ``interpret`` (with ``"fast"``,
+            ``interpret`` silently returns "No supporting context").
+
+    Returns:
+        ``[discover, interpret, search]`` ready to pass to
+        :meth:`AgentToolRegistry.extend`.
+    """
+    return [
+        _CopassDiscoverTool(
+            client=client,
+            sandbox_id=sandbox_id,
+            project_id=project_id,
+            window=window,
+        ),
+        _CopassInterpretTool(
+            client=client,
+            sandbox_id=sandbox_id,
+            project_id=project_id,
+            window=window,
+            preset=preset,
+        ),
+        _CopassSearchTool(
+            client=client,
+            sandbox_id=sandbox_id,
+            project_id=project_id,
+            window=window,
+            preset=preset,
+        ),
+    ]
+
+
+__all__ = ["copass_retrieval_tools"]

copass_context_agents-0.1.0/src/copass_context_agents/turn_recorder.py

@@ -0,0 +1,224 @@
+"""CopassTurnRecorder — mirror agent turns into a Copass Context Window.
+
+Python analogue of the TypeScript ``CopassWindowCallback``
+(``typescript/packages/langchain/src/callback.ts``). Fire-and-forget
+recorder for ``user`` / ``assistant`` turns emitted by provider
+backends' :class:`AgentEvent` streams (Anthropic
+:class:`ManagedAgentBackend`, Google :class:`GoogleAgentBackend`, …).
+
+Event-driven: pass each event to :meth:`record_event`, or wrap the
+stream with :meth:`record_stream` for a drop-in ``async for``.
+
+Deduplication: ``role + sha256(content[:500])`` — stable across
+restarts so an existing window's pre-seeded turns don't get
+re-recorded.
+
+Assistant-turn coalescing: :class:`AgentTextDelta` events are
+buffered; one LLM response becomes one ``assistant`` turn in the
+window, not N partial deltas. Flushes on :class:`AgentFinish` or when
+the next user turn arrives.
+
+Latency: pushes to the Context Window run in the background via
+``asyncio.create_task``, so the agent loop never blocks on the ingest
+HTTP round-trip (~100–300 ms/call). Pending tasks are tracked on
+``self._pending_pushes``; call :meth:`flush` at end-of-session to
+guarantee no turn is dropped. :meth:`record_stream` handles the flush
+in its ``finally`` block, so the default path through a provider's
+``stream()`` override is leak-free without user work.
+
+Envelope caveat: ``copass_core.types.ChatMessage`` currently carries
+only ``{role, content}``. Richer provenance (agent_id, model,
+tool_calls) can't be a first-class field yet — if you need that
+today, pass ``author=...`` + ``include_author_prefix=True`` to embed
+it as a ``[author=...]`` prefix in ``content``. Promote to a real
+field in ``ChatMessage`` when the envelope is widened.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+from typing import AsyncIterator, Optional
+
+from copass_core.context_window import ContextWindow
+from copass_core.types import ChatMessage
+from copass_core_agents.events import (
+    AgentEvent,
+    AgentFinish,
+    AgentTextDelta,
+    AgentToolCall,
+    AgentToolResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class CopassTurnRecorder:
+    """Push agent turns into a Copass :class:`ContextWindow`.
+
+    Args:
+        window: The :class:`ContextWindow` to mirror turns into.
+        include_tool_events: When True, record ``AgentToolCall`` /
+            ``AgentToolResult`` as ``system`` turns. Default False —
+            tool output is noisy and the retrieval graph already
+            indexes the underlying content, so recording it would
+            double-count.
+        author: Optional identifier for whoever is running the agent
+            (``"agent"``, ``"user"``, or something richer like
+            ``"agent:support-bot"``). Recorded as a prefix on
+            assistant turns when ``include_author_prefix`` is True.
+            Until :class:`ChatMessage` grows an ``author`` field this
+            is the only way to carry provenance into the window.
+        include_author_prefix: When True, assistant turns are stored
+            as ``"[author=...]\\n<content>"`` so downstream retrieval
+            can distinguish agent-authored vs. user-authored turns.
+            Default False — most callers don't need provenance, and
+            the prefix marginally pollutes the embedding.
+    """
+
+    def __init__(
+        self,
+        *,
+        window: ContextWindow,
+        include_tool_events: bool = False,
+        author: Optional[str] = None,
+        include_author_prefix: bool = False,
+    ) -> None:
+        self._window = window
+        self._include_tool_events = include_tool_events
+        self._author = author
+        self._include_author_prefix = include_author_prefix
+        self._seen: set[str] = set()
+        self._pending_assistant_text: list[str] = []
+        self._pending_pushes: set[asyncio.Task] = set()
+
+        # Seed dedupe set with whatever turns the window already has,
+        # so resuming a conversation doesn't double-record.
+        for turn in window.get_turns():
+            self._seen.add(self._dedupe_key(turn))
+
+    # ── Public recording API ───────────────────────────────────────
+
+    async def record_user(self, content: str) -> None:
+        """Record a user turn. Drops empty content. Flushes any
+        in-flight assistant text first — a new user turn finalizes
+        the prior assistant response."""
+        await self._flush_assistant()
+        await self._record(ChatMessage(role="user", content=content))
+
+    async def record_assistant_delta(self, text: str) -> None:
+        """Buffer an assistant text delta. Flushed by
+        :meth:`flush_assistant`, :meth:`record_event` (on
+        :class:`AgentFinish`), or :meth:`record_user`."""
+        if text:
+            self._pending_assistant_text.append(text)
+
+    async def flush_assistant(self) -> None:
+        """Coalesce buffered deltas into one assistant turn."""
+        await self._flush_assistant()
+
+    async def record_event(self, event: AgentEvent) -> None:
+        """Ingest one :class:`AgentEvent`. Convenience for drivers
+        that already iterate over the backend's event stream."""
+        if isinstance(event, AgentTextDelta):
+            await self.record_assistant_delta(event.text)
+        elif isinstance(event, AgentFinish):
+            await self._flush_assistant()
+        elif isinstance(event, AgentToolCall):
+            if self._include_tool_events:
+                await self._record(
+                    ChatMessage(
+                        role="system",
+                        content=f"[tool_call name={event.name!r} args={event.arguments!r}]",
+                    )
+                )
+        elif isinstance(event, AgentToolResult):
+            if self._include_tool_events:
+                await self._record(
+                    ChatMessage(
+                        role="system",
+                        content=(
+                            f"[tool_result name={event.name!r} "
+                            f"result={event.result!r}]"
+                        ),
+                    )
+                )
+
+    async def record_stream(
+        self, stream: AsyncIterator[AgentEvent]
+    ) -> AsyncIterator[AgentEvent]:
+        """Wrap a backend event stream — records every event and
+        re-yields it unchanged. Drop-in for existing ``async for``
+        loops::
+
+            async for evt in recorder.record_stream(agent.stream(...)):
+                ...
+
+        Awaits :meth:`flush` in a ``finally`` block so pending
+        background pushes complete before the wrapper returns.
+        Callers that drive events through :meth:`record_event`
+        directly (without going through this wrapper) must call
+        ``await recorder.flush()`` themselves at end-of-session.
+        """
+        try:
+            async for event in stream:
+                await self.record_event(event)
+                yield event
+        finally:
+            await self.flush()
+
+    async def flush(self) -> None:
+        """Await every in-flight ingestion task. Call at
+        end-of-session to guarantee no turn is dropped. Idempotent;
+        safe to call even when nothing is pending."""
+        pending = list(self._pending_pushes)
+        if not pending:
+            return
+        await asyncio.gather(*pending, return_exceptions=True)
+
+    # ── Internals ─────────────────────────────────────────────────
+
+    async def _flush_assistant(self) -> None:
+        if not self._pending_assistant_text:
+            return
+        text = "".join(self._pending_assistant_text).strip()
+        self._pending_assistant_text.clear()
+        if not text:
+            return
+        if self._include_author_prefix and self._author:
+            text = f"[author={self._author}]\n{text}"
+        await self._record(ChatMessage(role="assistant", content=text))
+
+    async def _record(self, turn: ChatMessage) -> None:
+        if not turn.content.strip():
+            return
+        key = self._dedupe_key(turn)
+        if key in self._seen:
+            return
+        self._seen.add(key)
+        # Fire the push in the background so the agent loop doesn't
+        # pay ingestion latency (~100–300 ms) on every turn. Failures
+        # are logged inside ``_push``; callers can await
+        # :meth:`flush` to observe completion.
+        task = asyncio.create_task(self._push(turn))
+        self._pending_pushes.add(task)
+        task.add_done_callback(self._pending_pushes.discard)
+
+    async def _push(self, turn: ChatMessage) -> None:
+        try:
+            await self._window.add_turn(turn)
+        except Exception as err:
+            logger.warning(
+                "CopassTurnRecorder: add_turn failed (dropping turn)",
+                extra={"error": str(err), "role": turn.role},
+            )
+
+    @staticmethod
+    def _dedupe_key(turn: ChatMessage) -> str:
+        body = turn.content[:500].encode("utf-8", errors="replace")
+        digest = hashlib.sha256(body).hexdigest()[:16]
+        return f"{turn.role}:{digest}"
+
+
+__all__ = ["CopassTurnRecorder"]