Add run export/undo, audit chain, config loader, plugins, and integration tests

Author: johnteee

AGENTS.md

@@ -23,3 +23,47 @@
 
 - Keep `SKILL.md` short and route details into `REFERENCE.md` or examples.
 - Treat skills as reviewed supply-chain assets, not casual prompt snippets.
+
+
+<claude-mem-context>
+# Memory Context
+
+# [teaagent] recent context, 2026-05-14 4:12pm GMT+8
+
+Legend: 🎯session 🔴bugfix 🟣feature 🔄refactor ✅change 🔵discovery ⚖️decision 🚨security_alert 🔐security_note
+Format: ID TIME TYPE TITLE
+Fetch details: get_observations([IDs]) | Search: mem-search skill
+
+Stats: 21 obs (8,973t read) | 185,455t work | 95% savings
+
+### May 8, 2026
+22 12:31a 🟣 TeaAgent P0 Agent Harness — Initial Implementation
+23 12:35a 🟣 teaagent P1 primitives: trace, context, eval, RAG, skill review, AI-BOM
+24 12:54a 🟣 GraphQLite Graph RAG persistence layer added to teaagent
+25 1:00a 🟣 TeaAgent CLI with GraphQLite subcommands added
+S4 Generate commit message for staged changes adding interactive TUI to teaagent CLI (May 8 at 1:01 AM)
+S3 Generate commit message for staged CLI additions to teaagent project (May 8 at 1:01 AM)
+26 1:04a 🟣 Interactive TUI added to teaagent CLI
+S5 Generate commit message for staged changes adding LLM adapters, workspace tools, and chat agent to teaagent (May 8 at 1:05 AM)
+27 8:04a 🟣 Multi-Provider LLM Adapter Layer Added to teaagent
+28 " 🟣 ChatAgentConfig and ModelDecisionEngine for Autonomous Agent Runs
+29 " 🟣 Agent Prompt Assembly and JSON Decision Parsing in prompt.py
+30 " 🟣 CLI Extended with agent run, model, doctor model, and workspace subcommands
+31 " 🟣 ApprovalPolicy Gains allow_all_destructive Bypass Flag
+S6 Generate commit message for staged changes adding permission modes and hash-anchored workspace edits to teaagent (May 8 at 8:05 AM)
+32 8:08a 🟣 Run Store, CLI, and TUI Support Added to teaagent
+33 " 🟣 RunStore: Persistent JSONL-based Agent Run History
+34 8:32a 🟣 PermissionMode Enum and Granular Tool Access Control
+35 " 🟣 Hash-Anchored Line Editing Tools
+36 " 🟣 Shell Tool Split: workspace_run_shell_inspect vs workspace_run_shell_mutate
+37 " 🟣 --permission-mode CLI Flag and TUI permission Command
+S7 Generate commit message for staged changes — TeaAgent intent clarification layer (May 8 at 8:33 AM)
+38 8:39a 🟣 Deterministic task clarification system added to TeaAgent
+39 8:46a 🟣 Memory Catalog added to teaagent
+S8 Add workspace memory catalog to teaagent — new MemoryCatalog feature with CLI, TUI, and agent prompt injection (May 8 at 8:46 AM)
+40 8:57a 🟣 Deterministic task-based model routing added to teaagent
+41 2:07p 🟣 MCP HTTP Transport Layer Added to teaagent
+42 2:08p 🟣 Streamable HTTP Transport for MCP Server Implemented
+
+Access 185k tokens of past work via get_observations([IDs]) or mem-search skill.
+</claude-mem-context>

docs/acceptance.md

@@ -174,6 +174,128 @@ verifiable so that tampering is detectable.*
 
 ---
 
+#### Audit Hash Chain Integrity (new)
+
+**File:** `test_audit_chain.py` (integration)
+
+**Story (P1):** *As a security lead, I want each persisted audit event to carry
+a SHA-256 hash of the previous event so that any tampering is
+cryptographically detectable.*
+
+| Assertion | Details |
+|---|---|
+| Clean log verifies OK | `verify_audit_chain()` returns `valid=True` |
+| First event has `prev_hash="genesis"` | Chain anchor constant |
+| Second event's `prev_hash` equals first's `hash` | Sequential linkage |
+| Content tampering detected | Mutating `event_type` breaks the hash |
+| Event insertion detected | Foreign event with wrong `prev_hash` rejected |
+| Event deletion detected | Gap in chain detected on line 3 |
+| Multi-run log verifies OK | Two runs in one JSONL all pass |
+
+---
+
+#### Plugin Loader (new)
+
+**File:** `test_plugins.py` (integration)
+
+**Story (P1):** *As a third-party author, I want to register tools via
+`teaagent.tools` entry-points so that `pip install` adds tools with no manual
+wiring.*
+
+| Assertion | Details |
+|---|---|
+| No plugins → empty result | `loaded == []`, `failed == []` |
+| Single plugin registers tool | Tool appears in `ToolRegistry` |
+| Multiple plugins all loaded | 3 entry-points → 3 tools |
+| Failing plugin isolated | Bad plugin in `failed`, others unaffected |
+| `ep.load()` error isolated | `ImportError` quarantined |
+| Custom group respected | `group=` parameter forwarded to `entry_points()` |
+| `PLUGIN_GROUP == 'teaagent.tools'` | Canonical group constant |
+
+---
+
+#### A2A Circuit Breaker (new)
+
+**File:** `test_a2a_circuit_breaker.py` (integration)
+
+**Story (P1):** *As a platform engineer, I want unhealthy remote agents to be
+skipped automatically so that one bad endpoint does not block the entire
+federation refresh.*
+
+| Assertion | Details |
+|---|---|
+| Circuit opens after `failure_threshold` | `circuit_state()` returns `'open'` |
+| Open circuit skips endpoint | Second refresh URL not in call log |
+| Success resets failure count | `circuit_state()` returns `'closed'` |
+| Circuit resets after `reset_timeout_seconds` | Half-open → retry → closed |
+| No `circuit_breaker` → retries every time | Backward-compatible default |
+| Unknown endpoint is `'closed'` | `circuit_state('http://unknown')` = `'closed'` |
+| Healthy endpoints still return cards | Even when one is open |
+
+---
+
+#### Config Layering + Workspace Profile (new)
+
+**File:** `test_config_loader.py` (integration)
+
+**Story (P2 — AC-NEW-3):** *As a developer, I want my workspace
+`.teaagent/config.json` to set default permission-mode and iteration limits so
+that I don't have to repeat CLI flags on every run.*
+
+| Assertion | Details |
+|---|---|
+| `ResolvedConfig.get()` returns value | By key name |
+| `ResolvedConfig.source()` returns layer | `ConfigLayer.WORKSPACE` etc. |
+| `show()` lists key=value [layer] lines | Human-readable |
+| Workspace config loaded | `.teaagent/config.json` values in `ResolvedConfig` |
+| User config loaded | `~/.teaagent/config.json` values in `ResolvedConfig` |
+| Workspace overrides user | Same key → workspace wins |
+| Env overrides workspace | `TEAAGENT_PERMISSION_MODE` beats file |
+| `ChatAgentConfig.from_root()` applies profile | `permission_mode`, `max_iterations` set from config |
+| Explicit kwargs override profile | Caller wins over workspace config |
+
+---
+
+#### Run Undo Journal (new)
+
+**File:** `test_run_undo.py` (integration)
+
+**Story (P2 — AC-NEW-6):** *As a developer, I want `UndoJournal` to track
+pre-write file state so that I can revert all workspace writes from a run.*
+
+| Assertion | Details |
+|---|---|
+| Newly created file deleted on `restore()` | Path in `UndoResult.deleted` |
+| Overwritten file restored | Original content re-written; path in `restored` |
+| Multiple writes all undone | Two files → two deletions |
+| Idempotent when no writes | Empty `restore()` with no errors |
+| `UndoResult.ok` false on errors | Error list non-empty → `ok=False` |
+| Read-only tools not captured | No journal entry for `workspace_read_file` |
+| Path traversal attempts ignored | `../` outside root silently dropped |
+
+---
+
+#### Run Export / Import (new)
+
+**File:** `test_run_export.py` (integration)
+
+**Story (P2 — AC-NEW-19):** *As a user, I want to export a run to a portable
+archive and import it on another machine so that runs are reproducible and
+shareable.*
+
+| Assertion | Details |
+|---|---|
+| `export_run()` creates `.tar.gz` | Archive exists at `output_path` |
+| `import_run()` restores run | Events appear in destination `RunStore` |
+| Round-trip preserves all event fields | `src_events == dst_events` |
+| Import does not clobber other runs | Pre-existing run survives import |
+| `ExportManifest` fields correct | `run_id`, `event_count`, `archive_path` |
+| Import missing archive → `FileNotFoundError` | Clear error |
+| Export missing run → `FileNotFoundError` | Clear error |
+| Hash chain valid after import | `verify_audit_chain()` passes on imported log |
+
+---
+
 ## Integration Tests (tests/integration/)
 
 | File | Coverage |
@@ -193,6 +315,12 @@ verifiable so that tampering is detectable.*
 | `test_streaming_tool_calls.py` | `on_chunk` callbacks, audit events, token accumulation (IT-13) |
 | `test_schema_migration_live.py` | Migration ordering, idempotency, data survival, version tracking (IT-14) |
 | `test_dpop_replay_concurrency.py` | Concurrent JTI consume: exactly one success; expiry reset (IT-15) |
+| `test_audit_chain.py` | Hash-chain validity, tampering/insertion/deletion detection (new) |
+| `test_plugins.py` | Plugin discovery, isolation, custom group (new) |
+| `test_a2a_circuit_breaker.py` | Circuit open/close, skip, reset, backward compat (new) |
+| `test_config_loader.py` | Layer precedence, env override, workspace profile applied (new) |
+| `test_run_undo.py` | Pre-write capture, file deletion/restore, path traversal guard (new) |
+| `test_run_export.py` | Export/import round-trip, hash-chain survival, error cases (new) |
 
 ---
 
@@ -204,16 +332,13 @@ acceptance tests.  Each maps to a Review gap analysis recommendation.
 | ID | Story | Priority |
 |---|---|---|
 | AC-NEW-1 | `teaagent init` first-time wizard | P2 |
-| AC-NEW-3 | Workspace profile (`.teaagent/profile.toml`) | P2 |
 | AC-NEW-4 | Interactive diff preview + inline y/n approval | P0 |
-| AC-NEW-6 | `teaagent run undo <run_id>` workspace rollback | P2 |
 | AC-NEW-8 | Desktop/webhook notification on ultrawork completion | P2 |
 | AC-NEW-11 | A2A delegation carries `traceparent` header | P1 |
 | AC-NEW-15 | Configurable PII redaction categories | P2 |
 | AC-NEW-16 | HTTPS_PROXY / CA bundle / mTLS "just works" | P2 |
 | AC-NEW-17 | `teaagent upgrade` schema migration dry-run preview | P2 |
 | AC-NEW-18 | Graceful degradation when disk fills mid-run | P2 |
-| AC-NEW-19 | `teaagent run export / import` | P2 |
 | AC-NEW-20 | Local model (Ollama/vLLM) with full governance | P2 |
 | AC-NEW-21 | `teaagent eval run <suite>` with HTML report | P2 |
 | AC-NEW-22 | `teaagent benchmark` latency/cost regression tracking | P2 |

teaagent/__init__.py

@@ -7,8 +7,14 @@
 except PackageNotFoundError:
     __version__ = '0+local'
 
+from teaagent.agentcard import CircuitBreakerConfig
 from teaagent.aibom import AIBOMManifest, build_aibom
 from teaagent.audit import AuditLogger
+from teaagent.audit_chain import (
+    ChainVerificationResult,
+    compute_event_hash,
+    verify_audit_chain,
+)
 from teaagent.budget import RunBudget
 from teaagent.chat_agent import (
     ChatAgentConfig,
@@ -24,6 +30,13 @@
     UnsafeCodeError,
     execute_code_mode,
 )
+from teaagent.config_loader import (
+    CONFIG_KEYS,
+    ConfigLayer,
+    ConfigResolver,
+    ResolvedConfig,
+    load_workspace_config,
+)
 from teaagent.context import ContextCompactor
 from teaagent.errors import RunCancelledError
 from teaagent.eval import EvalCase, EvalReport, run_eval
@@ -96,6 +109,7 @@
     generate_code_verifier,
     verify_jwt,
 )
+from teaagent.plugins import PluginLoadResult, load_plugins
 from teaagent.policy import ApprovalPolicy, PermissionMode, parse_permission_mode
 from teaagent.portability import (
     PortabilityResult,
@@ -106,7 +120,9 @@
 from teaagent.prompt import PromptBundle, assemble_agent_prompt, parse_model_decision
 from teaagent.rag import Document, InMemoryRetriever, agentic_retrieve
 from teaagent.readiness import ReadinessReport, assess_managed_agent_readiness
+from teaagent.run_export import ExportManifest, export_run, import_run
 from teaagent.run_store import RunStore, RunSummary
+from teaagent.run_undo import UndoJournal, UndoResult
 from teaagent.runner import (
     AgentRunner,
     ApprovalRequest,
@@ -150,6 +166,15 @@
     'ApprovalPolicy',
     'ApprovalRequest',
     'AuditLogger',
+    'CircuitBreakerConfig',
+    'CONFIG_KEYS',
+    'ConfigLayer',
+    'ConfigResolver',
+    'ResolvedConfig',
+    'load_workspace_config',
+    'ChainVerificationResult',
+    'compute_event_hash',
+    'verify_audit_chain',
     'ChatAgentConfig',
     'ChildProcessCodeModeBackend',
     'ClarificationResult',
@@ -211,6 +236,13 @@
     'OAuthKeyRing',
     'OAuthStore',
     'PermissionMode',
+    'ExportManifest',
+    'PluginLoadResult',
+    'UndoJournal',
+    'UndoResult',
+    'export_run',
+    'import_run',
+    'load_plugins',
     'PortabilityResult',
     'PreflightReport',
     'PromptBundle',

teaagent/agentcard.py

@@ -13,6 +13,40 @@
 from typing import Any, Callable, Optional
 
 
+@dataclass(frozen=True)
+class CircuitBreakerConfig:
+    """Per-endpoint circuit-breaker parameters for :class:`FederatedAgentRegistry`.
+
+    After *failure_threshold* consecutive failures the circuit opens and the
+    endpoint is skipped on subsequent refreshes.  Once *reset_timeout_seconds*
+    have elapsed the circuit moves to half-open and the next refresh retries
+    the endpoint; a success closes the circuit, another failure re-opens it.
+    """
+
+    failure_threshold: int = 3
+    reset_timeout_seconds: float = 60.0
+
+
+@dataclass
+class _EndpointCircuit:
+    failures: int = 0
+    opened_at: Optional[float] = None  # monotonic timestamp when circuit opened
+
+    def is_open(self, reset_timeout: float) -> bool:
+        if self.opened_at is None:
+            return False
+        return (_time.monotonic() - self.opened_at) < reset_timeout
+
+    def record_failure(self, threshold: int) -> None:
+        self.failures += 1
+        if self.failures >= threshold:
+            self.opened_at = _time.monotonic()
+
+    def record_success(self) -> None:
+        self.failures = 0
+        self.opened_at = None
+
+
 @dataclass(frozen=True)
 class AgentCard:
     name: str
@@ -376,12 +410,15 @@ def __init__(
         *,
         ttl_seconds: int = 300,
         timeout: int = 10,
+        circuit_breaker: Optional[CircuitBreakerConfig] = None,
     ) -> None:
         self._endpoints = list(endpoints)
         self._ttl = ttl_seconds
         self._timeout = timeout
         self._cache: list[AgentCard] = []
         self._fetched_at: float = 0.0
+        self._cb_config = circuit_breaker
+        self._circuits: dict[str, _EndpointCircuit] = {}
 
     def _is_stale(self) -> bool:
         return _time.monotonic() - self._fetched_at > self._ttl
@@ -390,17 +427,38 @@ def refresh(self) -> list[str]:
         errors: list[str] = []
         cards: list[AgentCard] = []
         for base_url in self._endpoints:
+            circuit = self._circuits.setdefault(base_url, _EndpointCircuit())
+            if self._cb_config is not None and circuit.is_open(
+                self._cb_config.reset_timeout_seconds
+            ):
+                continue  # circuit open — skip this endpoint
             url = base_url.rstrip('/') + '/.well-known/agent.json'
             try:
                 with urllib.request.urlopen(url, timeout=self._timeout) as resp:
                     data = json.loads(resp.read().decode('utf-8'))
                 cards.append(AgentCard.from_dict(data))
+                circuit.record_success()
             except Exception as exc:
                 errors.append(f'{base_url}: {exc}')
+                if self._cb_config is not None:
+                    circuit.record_failure(self._cb_config.failure_threshold)
         self._cache = cards
         self._fetched_at = _time.monotonic()
         return errors
 
+    def circuit_state(self, base_url: str) -> str:
+        """Return ``'open'`` or ``'closed'`` for the given endpoint."""
+        circuit = self._circuits.get(base_url)
+        if circuit is None:
+            return 'closed'
+        if self._cb_config is None:
+            return 'closed'
+        return (
+            'open'
+            if circuit.is_open(self._cb_config.reset_timeout_seconds)
+            else 'closed'
+        )
+
     def _ensure_fresh(self) -> None:
         if self._is_stale():
             self.refresh()