Add immutable turn-level training export v1

.github/workflows/ci.yml

@@ -59,6 +59,18 @@ jobs:
       - name: Run Python import API checks
         run: python tests/test_python_api_tools.py
 
+      - name: Run OpenAI-compatible API checks
+        run: python tests/test_openai_api_checks.py
+
+      - name: Run turn-level training export contract checks
+        run: python tests/test_turn_training_export.py
+
+      - name: Run turn-level training export API checks
+        run: python tests/test_turn_training_export_api.py
+
+      - name: Run turn-level training export entrypoint checks
+        run: python tests/test_turn_training_export_entrypoints.py
+
   main-agent-api:
     name: Main agent API smoke
     runs-on: ubuntu-latest

README.md

@@ -257,6 +257,7 @@ Start here if you are reading the codebase for the first time.
 
 - [docs/tutorial_en.md](docs/tutorial_en.md): detailed English tutorial
 - [docs/tutorial_zh.md](docs/tutorial_zh.md): detailed Chinese tutorial
+- [docs/turn-training-export-v1.md](docs/turn-training-export-v1.md): immutable per-provider-call training export contract and usage
 - [tests/](tests): tool checks and end-to-end agent tests
 - [tests/example_files/](tests/example_files): fixed local fixtures
 

agent_base/context_compact.py

@@ -133,11 +133,31 @@ def compact_messages(
             ),
         },
     ]
-    summary_reply = llm_caller(
-        summary_request,
-        runtime_deadline=runtime_deadline,
-        max_output_tokens=model_profile.compact_summary_max_tokens,
-    )
+    try:
+        summary_reply = llm_caller(
+            summary_request,
+            runtime_deadline=runtime_deadline,
+            max_output_tokens=model_profile.compact_summary_max_tokens,
+        )
+    except KeyboardInterrupt:
+        return CompactionOutcome(
+            status="error",
+            compacted_messages=safe_messages,
+            prior_token_estimate=prior_token_estimate,
+            existing_memory_text=existing_memory_text,
+            summary_request=summary_request,
+            summary_response={
+                "status": "error",
+                "error": "context compaction provider call interrupted",
+                "interrupted": True,
+                "tool_calls": [],
+            },
+            pre_messages=safe_messages,
+            post_messages=safe_messages,
+            error="context compaction provider call interrupted",
+            compacted_group_count=len(compacted_groups),
+            kept_group_count=len(recent_groups),
+        )
     if not isinstance(summary_reply, dict) or summary_reply.get("status") != "ok":
         error = summary_reply.get("error", "context compaction summary call failed") if isinstance(summary_reply, dict) else str(summary_reply)
         return CompactionOutcome(

agent_base/trace_utils.py

@@ -1,6 +1,7 @@
 import argparse
 import datetime
 from pathlib import Path
+import re
 from typing import Any, Callable, Optional
 from uuid import uuid4
 
@@ -28,6 +29,9 @@
 ]
 
 
+_RUN_ID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
+
+
 class FlatTraceWriter:
     def __init__(
         self,
@@ -36,11 +40,19 @@ def __init__(
         model_name: str,
         workspace_root: str | Path,
         on_event: Optional[Callable[[dict[str, Any]], None]] = None,
+        run_id: Optional[str] = None,
     ):
         self.model_name = model_name
         self.workspace_root = str(workspace_root)
         self.on_event = on_event
-        self.run_id = uuid4().hex
+        if run_id is not None and not isinstance(run_id, str):
+            raise ValueError("run_id must be a string")
+        resolved_run_id = run_id if run_id is not None else uuid4().hex
+        if _RUN_ID_RE.fullmatch(resolved_run_id) is None:
+            raise ValueError(
+                "run_id must be 1-128 characters using only letters, digits, '.', '_', or '-'"
+            )
+        self.run_id = resolved_run_id
         self.path = resolve_trace_path(trace_dir, run_id=self.run_id) if trace_dir else None
         self.event_index = 0