agent-apprenticeship 0.2.1 → 0.3.0

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/cli.py

@@ -16,8 +16,8 @@ from contextlib import contextmanager
 from datetime import datetime, timezone
 from pathlib import Path
 import typer
-from .schemas import RawTaskRecord, AgentTrace
-from .io import read_json, read_jsonl, write_json
+from .schemas import RawTaskRecord, WorkflowTrace
+from .io import read_workflow_json as read_json, read_workflow_jsonl as read_jsonl, write_json
 from .loop import run_task as run_one
 from .batch_runner import run_batch as run_batch_impl
 from .bundle_exporter import create_contribution_bundle
@@ -2357,6 +2357,8 @@ def _safe_bundle_path(path: Path) -> Path:
     manifest = bundle / "contribution_manifest.json"
     if not manifest.exists():
         raise FileNotFoundError(f"Experience Compilation manifest not found: {manifest}")
+    from .io import validate_trace_tree
+    validate_trace_tree(bundle)
     return bundle
 
 
@@ -3519,6 +3521,9 @@ def _locate_package_root(path: Path) -> Path:
 
 def _copy_or_zip_package(src: Path, output: Path, *, item_id: str, source: str) -> Path:
     src = _locate_package_root(src)
+    from .agent_env_exporter import export_agent_env
+    from .io import validate_trace_tree
+    validate_trace_tree(src)
     output = output.expanduser()
     manifest = {
         "export_type": "full_experience_compilation",
@@ -3547,6 +3552,7 @@ def _copy_or_zip_package(src: Path, output: Path, *, item_id: str, source: str)
             shutil.rmtree(staging)
         (staging / "package").mkdir(parents=True)
         shutil.copytree(src, staging / "package", dirs_exist_ok=True)
+        export_agent_env(staging / "package")
         write_json(staging / "export_manifest.json", manifest)
         _zip_dir(staging, output)
         shutil.rmtree(staging)
@@ -3555,6 +3561,7 @@ def _copy_or_zip_package(src: Path, output: Path, *, item_id: str, source: str)
         shutil.rmtree(output)
     output.mkdir(parents=True)
     shutil.copytree(src, output / "package", dirs_exist_ok=True)
+    export_agent_env(output / "package")
     write_json(output / "export_manifest.json", manifest)
     return output
 
@@ -3602,6 +3609,8 @@ def ecosystem_pull(
             typer.echo(f"Could not pull ecosystem item from R2: {redact_secrets(str(exc))}")
             typer.echo("Fallback: apprentice ecosystem pull " + bundle_id + " --storage github")
             raise typer.Exit(1)
+        from .io import validate_trace_tree
+        validate_trace_tree(dest)
         typer.echo(f'pulled_bundle={dest}')
         if full or mode == "full":
             export_path = _copy_or_zip_package(dest, get_settings().app_home / "ecosystem" / "exports" / (_row_id(row) or bundle_id), item_id=_row_id(row) or bundle_id, source="r2_pull")
@@ -3660,6 +3669,8 @@ def ecosystem_pull(
             typer.echo(f'Reason: {exc}')
             typer.echo('Next action: set AA_HOME to a writable directory and try again.')
             raise typer.Exit(1)
+        from .io import validate_trace_tree
+        validate_trace_tree(dest)
         typer.echo(f'pulled_bundle={dest}')
         return
     source=Path(src).expanduser()
@@ -3677,6 +3688,8 @@ def ecosystem_pull(
         typer.echo(f'Reason: {exc}')
         typer.echo('Next action: set AA_HOME to a writable directory and try again.')
         raise typer.Exit(1)
+    from .io import validate_trace_tree
+    validate_trace_tree(dest)
     typer.echo(f'pulled_bundle={dest}')
     if full or mode == "full":
         export_path = _copy_or_zip_package(dest, get_settings().app_home / "ecosystem" / "exports" / bundle_id, item_id=bundle_id, source="local_pull")
@@ -3948,6 +3961,11 @@ def bundle_check(path: Path=typer.Argument(..., help='Experience Compilation fol
 
     issues: list[str] = []
     bundle = Path(path).expanduser()
+    from .io import validate_trace_tree
+    try:
+        validate_trace_tree(bundle)
+    except ValueError as exc:
+        issues.append(str(exc))
     manifest_candidates = [
         bundle / "contribution_manifest.json",
         bundle / "task_manifest.json",
@@ -4204,11 +4222,11 @@ def validate_public_release(release_root: Path=typer.Option(...)):
 @app.command('repair-roles', hidden=True)
 def repair_roles(run_root: Path=typer.Option(...), task_id: str=typer.Option(...), roles: str=typer.Option('evaluator_agent,grader_agent,verifier_agent'), attempts: str=typer.Option('baseline,revised'), rebuild_release: Path|None=typer.Option(None)):
     """Re-run model evaluation roles from existing task package artifacts/traces."""
-    from .schemas import RubricSpec, ActualOutputs, AgentTrace, GraderResult, VerifierResult
+    from .schemas import RubricSpec, ActualOutputs, WorkflowTrace, GraderResult, VerifierResult
     from .grader import grade_attempt, apply_score_reliability
     from .verifier import verify_attempt
     from .evaluator import evaluate_attempt
-    from .io import read_json, write_json
+    from .io import read_workflow_json as read_json, write_json
     from datetime import datetime, timezone
     import shutil
     pkg=run_root/'packages'/task_id
@@ -4224,7 +4242,7 @@ def repair_roles(run_root: Path=typer.Option(...), task_id: str=typer.Option(...
             typer.echo(f'skipping {attempt}: missing existing attempt outputs')
             continue
         actual=ActualOutputs.model_validate(read_json(actual_path))
-        trace=AgentTrace.model_validate(read_json(trace_path))
+        trace=WorkflowTrace.model_validate(read_json(trace_path))
         grade_path=pkg/'grading'/f'{attempt}_grader_result.json'
         ver_path=pkg/'grading'/f'{attempt}_verifier_result.json'
         grader=GraderResult.model_validate(read_json(grade_path)) if grade_path.exists() else None
@@ -4296,9 +4314,10 @@ def summarize_releases(release_root: Path=typer.Option(Path('outputs/releases'))
     typer.echo('task_ids_publishable_with_warnings=' + ','.join(warnings))
     typer.echo('task_ids_clean_publishable=' + ','.join(clean))
 
-@app.command('inspect-trace', hidden=True)
+@app.command('inspect-trace')
 def inspect_trace(trace_path: Path):
-    t=AgentTrace.model_validate_json(trace_path.read_text()); typer.echo(f'trace_id={t.trace_id}\ntask_id={t.task_id}\nsteps={len(t.steps)}')
+    from .atif import load_trace
+    t=WorkflowTrace.model_validate(load_trace(trace_path)); typer.echo(f'trace_id={t.trace_id}\ntask_id={t.task_id}\nsteps={len(t.steps)}')
 
 @app.command('codex-smoke', hidden=True)
 def codex_smoke():

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/codex_runner.py

@@ -4,7 +4,7 @@ import signal
 import shutil, subprocess
 from pathlib import Path
 import re
-from .schemas import AgentTrace, AgentTraceStep, ActualOutputs, RawTaskRecord, TaskIntakeSpec
+from .schemas import WorkflowTrace, WorkflowTraceStep, ActualOutputs, RawTaskRecord, TaskIntakeSpec
 from .trace_prompt import build_worker_prompt
 from .io import write_json
 from .config import get_settings
@@ -35,14 +35,14 @@ def _safe_agent_config(settings, runner_kind: str, attempt_kind: str) -> dict:
 
 
 def _enrich_runtime_trace(
-    trace: AgentTrace,
+    trace: WorkflowTrace,
     actual: ActualOutputs,
     package_root: Path,
     attempt_kind: str,
     runner_kind: str,
     started_at: str | None,
     ended_at: str | None,
-) -> AgentTrace:
+) -> WorkflowTrace:
     settings = get_settings()
     trace.run_id = package_root.parent.parent.name if package_root.parent.parent.name else None
     trace.package_id = package_root.name
@@ -243,24 +243,24 @@ def codex_exec_help(command: str = "codex") -> str:
 def _codex_exec_supports(flag: str, command: str = "codex") -> bool:
     return flag in codex_exec_help(command)
 
-def _fallback_trace(spec: TaskIntakeSpec, attempt_kind: str, prompt: str, actual: ActualOutputs, error_type: str, error_message: str, codex_sandbox: str) -> AgentTrace:
+def _fallback_trace(spec: TaskIntakeSpec, attempt_kind: str, prompt: str, actual: ActualOutputs, error_type: str, error_message: str, codex_sandbox: str) -> WorkflowTrace:
     cls=classify_provider_failure(error_message)
     attempt_id=f'{spec.task_id}_{attempt_kind}'
     actor=f'agent:{"reviser" if attempt_kind=="revised" else "worker"}'
     safe=(public_error_summary(error_message) if cls else redact_secrets(error_message)[-3000:])
     error_type=cls.get('error_type') or error_type
     steps=[
-        AgentTraceStep(step=1, turn=1, actor='user', action='user_message', input=spec.normalized_instruction, message_role='direct_request'),
-        AgentTraceStep(step=2, turn=1, actor=actor, action='error', operation='other', tool='codex_cli', environment_domain='terminal', execution_mode='serial', observation='Codex attempt ended without a valid agent_trace.json or actual_outputs.json.', input='Validate required output contract for ./agent_trace.json and ./actual_outputs.json.', input_source={'source':'runtime_contract_check'}, output=safe, state_change='A minimal failure trace and failed actual_outputs.json were written by the runner.', reasoning='The package must preserve failure evidence without fabricating a successful detailed trace.', caused_by=[1], causal_type='dependency_on_tool_result', success=False, step_outcome='failed', error_type=error_type, error_message=safe, artifact_refs=[f'attempts/{attempt_kind}/prompt.md', f'attempts/{attempt_kind}/stdout.txt', f'attempts/{attempt_kind}/stderr.txt', f'attempts/{attempt_kind}/final_message.txt']),
+        WorkflowTraceStep(step=1, turn=1, actor='user', action='user_message', input=spec.normalized_instruction, message_role='direct_request'),
+        WorkflowTraceStep(step=2, turn=1, actor=actor, action='error', operation='other', tool='codex_cli', environment_domain='terminal', execution_mode='serial', observation='Codex attempt ended without a valid agent_trace.json or actual_outputs.json.', input='Validate required output contract for ./agent_trace.json and ./actual_outputs.json.', input_source={'source':'runtime_contract_check'}, output=safe, state_change='A minimal failure trace and failed actual_outputs.json were written by the runner.', reasoning='The package must preserve failure evidence without fabricating a successful detailed trace.', caused_by=[1], causal_type='dependency_on_tool_result', success=False, step_outcome='failed', error_type=error_type, error_message=safe, artifact_refs=[f'attempts/{attempt_kind}/prompt.md', f'attempts/{attempt_kind}/stdout.txt', f'attempts/{attempt_kind}/stderr.txt', f'attempts/{attempt_kind}/final_message.txt']),
     ]
-    return AgentTrace(trace_id=f'trace_{attempt_id}_fallback', collection_id=None, trace_mode='live', task=spec.normalized_instruction, task_id=spec.task_id, attempt_id=attempt_id, attempt_kind=attempt_kind if attempt_kind in ['baseline','revised'] else 'other', agent_tools=['codex_cli','Bash','python','file_read','file_write'], system_prompt=prompt, system_prompt_hash=None, skills=['agent_trace_skill'], learning='When a live agent cannot write outputs, preserve logs and create a minimal failure trace.', termination_reason='agent_blocked', steps=steps, actual_outputs=actual, artifacts=[], metadata_json={'trace_valid':False,'fallback_trace_created':True,'codex_sandbox':codex_sandbox, **cls})
+    return WorkflowTrace(trace_id=f'trace_{attempt_id}_fallback', collection_id=None, trace_mode='live', task=spec.normalized_instruction, task_id=spec.task_id, attempt_id=attempt_id, attempt_kind=attempt_kind if attempt_kind in ['baseline','revised'] else 'other', agent_tools=['codex_cli','Bash','python','file_read','file_write'], system_prompt=prompt, system_prompt_hash=None, skills=['agent_trace_skill'], learning='When a live agent cannot write outputs, preserve logs and create a minimal failure trace.', termination_reason='agent_blocked', steps=steps, actual_outputs=actual, artifacts=[], metadata_json={'trace_valid':False,'fallback_trace_created':True,'codex_sandbox':codex_sandbox, **cls})
 
 def _write_fallback_report(d: Path, spec: TaskIntakeSpec, attempt_kind: str, reason: str, raw_parse_error: bool=False) -> None:
     report=TraceNormalizationReport(task_id=spec.task_id, attempt_id=f'{spec.task_id}_{attempt_kind}', attempt_kind=attempt_kind, raw_trace_ref='agent_trace.raw.json' if (d/'agent_trace.raw.json').exists() else None, normalized_trace_ref=None, canonical_trace_ref='agent_trace.json', trace_schema_valid=True, trace_normalized=False, trace_lossless=True, fallback_trace=True, raw_step_count=0, normalized_step_count=2, discarded_step_count=0, raw_trace_parse_error=raw_parse_error, validation_errors=[reason], metadata_json={'fallback_reason': reason})
     write_json(d/'trace_normalization_report.json', report)
 
 
-def ensure_attempt_outputs(package_root: Path, spec: TaskIntakeSpec, attempt_kind: str, prompt: str, codex_sandbox: str, validation_error: Exception | None=None) -> tuple[AgentTrace, ActualOutputs, bool]:
+def ensure_attempt_outputs(package_root: Path, spec: TaskIntakeSpec, attempt_kind: str, prompt: str, codex_sandbox: str, validation_error: Exception | None=None) -> tuple[WorkflowTrace, ActualOutputs, bool]:
     d=_attempt_dir(package_root, attempt_kind)
     recovered_contract_files = _recover_misplaced_contract_files(d)
     actual_path=d/'actual_outputs.json'; trace_path=d/'agent_trace.json'; raw_path=d/'agent_trace.raw.json'
@@ -279,14 +279,10 @@ def ensure_attempt_outputs(package_root: Path, spec: TaskIntakeSpec, attempt_kin
         context=TraceNormalizationContext(task_id=spec.task_id, attempt_id=f'{spec.task_id}_{attempt_kind}', attempt_kind=attempt_kind, task=spec.normalized_instruction, actual_outputs=actual)
         result=repair_agent_trace_file(raw_path, context)
         if result.normalized_trace and (result.report.raw_step_count or result.normalized_trace.get('steps')):
-            try:
-                AgentTrace.model_validate_json(raw_path.read_text())
-            except Exception:
-                (d/'agent_trace.invalid.json').write_text(raw_path.read_text())
             write_json(d/'agent_trace.normalized.json', result.normalized_trace)
             write_json(d/'agent_trace.json', result.normalized_trace)
             write_json(d/'trace_normalization_report.json', result.report)
-            trace = AgentTrace.model_validate(result.normalized_trace)
+            trace = WorkflowTrace.model_validate(result.normalized_trace)
             if recovered_contract_files:
                 trace.metadata_json["contract_files_recovered_from"] = recovered_contract_files
                 actual.metadata_json.setdefault("contract_files_recovered_from", recovered_contract_files)
@@ -297,6 +293,10 @@ def ensure_attempt_outputs(package_root: Path, spec: TaskIntakeSpec, attempt_kin
         msg=f'{reason}\n\nfinal_message:\n{final}\n\nstderr:\n{stderr}'
         trace=_fallback_trace(spec, attempt_kind, prompt, actual, 'TraceNormalizationError', msg, codex_sandbox)
         trace.metadata_json['fallback_reason']=classify_provider_failure(msg).get('fallback_reason') or ('unparseable_trace' if result.fallback_required else 'missing_steps')
+        if raw_path.exists():
+            raw_path.replace(d/'rejected_agent_response.txt')
+        write_json(d/'agent_trace.raw.json', trace)
+        write_json(d/'agent_trace.normalized.json', trace)
         write_json(trace_path, trace); _write_fallback_report(d, spec, attempt_kind, trace.metadata_json['fallback_reason'], result.fallback_required)
         return trace, actual, False
     final=(d/'final_message.txt').read_text(errors='ignore') if (d/'final_message.txt').exists() else ''
@@ -326,12 +326,12 @@ def deterministic_attempt(package_root: Path, raw: RawTaskRecord, spec: TaskInta
         files.append(f'attempts/{attempt_kind}/artifacts/{fname}')
     actual=ActualOutputs(task_id=spec.task_id, attempt_id=attempt_id, attempt_kind=attempt_kind, status='success', output_summary=f'Deterministic {attempt_kind} outputs for {spec.normalized_title}', primary_output_ref=files[0] if files else None, input_artifact_refs=[f'input/{name}' for name in input_files], deliverable_refs=files, final_message_ref=f'attempts/{attempt_kind}/final_message.txt', artifact_refs=files, files_created=files, files_modified=[], files_deleted=[], stdout_ref=f'attempts/{attempt_kind}/stdout.txt', stderr_ref=f'attempts/{attempt_kind}/stderr.txt', raw_log_refs=[f'attempts/{attempt_kind}/stdout.txt', f'attempts/{attempt_kind}/stderr.txt'], error_type=None, error_message=None, metadata_json={'runner':'deterministic','expected_deliverable_items':deliverables,'produced_deliverable_items':[Path(f).name for f in files]})
     steps=[
-        AgentTraceStep(step=1, turn=1, actor='user', action='user_message', input=spec.normalized_instruction, message_role='direct_request'),
-        AgentTraceStep(step=2, turn=1, actor=f'agent:{"reviser" if attempt_kind=="revised" else "worker"}', action='agent_step', operation='plan', tool=None, environment_domain='file', execution_mode='serial', observation='Task instructions, ./input files, and worker-visible rubric are available.', input='Review task and required deliverables.', input_source={'source':'task_packet'}, output='Plan created.', state_change='The attempt plan identified required artifacts.', reasoning='A short plan reduces missed deliverables.', caused_by=[1], causal_type='user_request', success=True, step_outcome='progress', artifact_refs=[f'input/{name}' for name in input_files]),
-        AgentTraceStep(step=3, turn=1, actor=f'agent:{"reviser" if attempt_kind=="revised" else "worker"}', action='agent_step', operation='write', tool='file_write', environment_domain='file', execution_mode='serial', observation='Deliverable names are known.', input=', '.join(files), input_source={'source':'planned_deliverables'}, output='Artifacts written.', state_change='Required deterministic artifacts were created under ./artifacts.', reasoning='Writing explicit files satisfies the artifact contract.', caused_by=[2], causal_type='execution_of_plan', success=True, step_outcome='completed', artifact_refs=files),
+        WorkflowTraceStep(step=1, turn=1, actor='user', action='user_message', input=spec.normalized_instruction, message_role='direct_request'),
+        WorkflowTraceStep(step=2, turn=1, actor=f'agent:{"reviser" if attempt_kind=="revised" else "worker"}', action='agent_step', operation='plan', tool=None, environment_domain='file', execution_mode='serial', observation='Task instructions, ./input files, and worker-visible rubric are available.', input='Review task and required deliverables.', input_source={'source':'task_packet'}, output='Plan created.', state_change='The attempt plan identified required artifacts.', reasoning='A short plan reduces missed deliverables.', caused_by=[1], causal_type='user_request', success=True, step_outcome='progress', artifact_refs=[f'input/{name}' for name in input_files]),
+        WorkflowTraceStep(step=3, turn=1, actor=f'agent:{"reviser" if attempt_kind=="revised" else "worker"}', action='agent_step', operation='write', tool='file_write', environment_domain='file', execution_mode='serial', observation='Deliverable names are known.', input=', '.join(files), input_source={'source':'planned_deliverables'}, output='Artifacts written.', state_change='Required deterministic artifacts were created under ./artifacts.', reasoning='Writing explicit files satisfies the artifact contract.', caused_by=[2], causal_type='execution_of_plan', success=True, step_outcome='completed', artifact_refs=files),
     ]
     ended_at = utc_now()
-    trace=AgentTrace(trace_id=f'trace_{attempt_id}', collection_id=None, trace_mode='live', task=spec.normalized_instruction, task_id=spec.task_id, attempt_id=attempt_id, attempt_kind=attempt_kind if attempt_kind in ['baseline','revised'] else 'other', agent_tools=['deterministic_runner','file_write'], system_prompt=prompt, system_prompt_hash=None, skills=['agent_trace_skill'], learning='Materialize required artifacts and keep evaluation outside the trace.', termination_reason='task_complete', steps=steps, actual_outputs=actual, artifacts=[], metadata_json={'trace_valid': True})
+    trace=WorkflowTrace(trace_id=f'trace_{attempt_id}', collection_id=None, trace_mode='live', task=spec.normalized_instruction, task_id=spec.task_id, attempt_id=attempt_id, attempt_kind=attempt_kind if attempt_kind in ['baseline','revised'] else 'other', agent_tools=['deterministic_runner','file_write'], system_prompt=prompt, system_prompt_hash=None, skills=['agent_trace_skill'], learning='Materialize required artifacts and keep evaluation outside the trace.', termination_reason='task_complete', steps=steps, actual_outputs=actual, artifacts=[], metadata_json={'trace_valid': True})
     trace = _enrich_runtime_trace(trace, actual, package_root, attempt_kind, 'deterministic', started_at, ended_at)
     write_json(d/'actual_outputs.json', actual)
     actual_ctx=ActualOutputsNormalizationContext(task_id=spec.task_id, attempt_id=attempt_id, attempt_kind=attempt_kind, package_root=package_root, required_artifacts=deliverables)

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/config.py

@@ -12,7 +12,7 @@ from pydantic import BaseModel, Field
 
 from .env import load_local_env
 from .command_discovery import resolve_command, resolve_agent_command, gui_app_hint
-from .io import read_json, write_json
+from .io import read_workflow_json as read_json, write_json
 from .recipes import MODEL_PROVIDER_RECIPES, WORKER_AGENT_RECIPES
 
 

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/ecosystem_r2.py

@@ -22,7 +22,7 @@ from .config import (
     get_settings,
 )
 from .env import redact_secrets
-from .io import append_jsonl, read_json, read_jsonl, write_json
+from .io import append_jsonl, read_workflow_json as read_json, read_workflow_jsonl as read_jsonl, write_json
 from .public_sanitizer import sanitize_public_obj
 from .version import get_package_version
 
@@ -485,6 +485,8 @@ def download_r2_package(item_id: str, dest: Path, settings: Settings | None = No
             if not target.resolve().is_relative_to(dest.resolve()):
                 raise RuntimeError("R2 package contains an unsafe path.")
         zf.extractall(dest)
+    from .io import validate_trace_tree
+    validate_trace_tree(dest)
     return dest
 
 

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/evaluator.py

@@ -2,9 +2,9 @@ from __future__ import annotations
 import json
 from pathlib import Path
 from pydantic import BaseModel
-from .schemas import EvaluatorFeedback, GraderResult, VerifierResult, AgentTrace, ActualOutputs, RevisionPlan
+from .schemas import EvaluatorFeedback, GraderResult, VerifierResult, WorkflowTrace, ActualOutputs, RevisionPlan
 from .config import get_settings
-from .io import read_json
+from .io import read_workflow_json as read_json
 from .openai_structured import get_model_provider_status, run_structured_role
 from .public_sanitizer import sha256_text
 from .artifact_previews import build_artifact_previews
@@ -60,30 +60,11 @@ def _latest_review_packet(package_root: Path | None, attempt_kind: str) -> dict:
     return packet
 
 
-def _compact_trace_summary(trace: AgentTrace | None) -> dict:
+def _compact_trace_summary(trace: WorkflowTrace | None) -> dict:
     if trace is None:
         return {}
-    data = trace.model_dump()
-    steps = data.get("steps") or []
-    return {
-        "trace_id": data.get("trace_id"),
-        "attempt_id": data.get("attempt_id"),
-        "attempt_kind": data.get("attempt_kind"),
-        "step_count": len(steps),
-        "key_steps": [
-            {
-                "step": step.get("step"),
-                "operation": step.get("operation"),
-                "interaction_surface": step.get("interaction_surface"),
-                "environment_domain": step.get("environment_domain"),
-                "step_outcome": step.get("step_outcome"),
-                "artifact_refs": (step.get("artifact_refs") or [])[:5],
-                "state_change": str(step.get("state_change") or "")[:240],
-            }
-            for step in steps[:10]
-            if isinstance(step, dict) and step.get("action") != "user_message"
-        ],
-    }
+    from .atif import from_workflow
+    return from_workflow(trace.model_dump())
 
 
 def _compact_grader(grader: GraderResult) -> dict:
@@ -142,13 +123,13 @@ def _compact_artifact_previews(bundle: dict | None) -> dict:
     }
 
 
-def _evaluator_prompt(grader: GraderResult, verifier: VerifierResult, outputs: ActualOutputs, trace: AgentTrace | None, target_attempt_id: str, artifact_preview_bundle: dict | None=None, review_packet: dict | None=None) -> str:
+def _evaluator_prompt(grader: GraderResult, verifier: VerifierResult, outputs: ActualOutputs, trace: WorkflowTrace | None, target_attempt_id: str, artifact_preview_bundle: dict | None=None, review_packet: dict | None=None) -> str:
     return """Return only valid JSON. Do not include markdown. Do not add extra top-level fields; place extras under metadata_json.extra_model_fields.
 Required skeleton: {"evaluator_feedback":{"feedback_id":"feedback_<task_id>_<attempt_kind>","task_id":"...","attempt_id":"...","target_actor":"apprentice","feedback_type":"other","failed_rubric_items":[],"evidence_refs":[],"artifact_refs":[],"feedback_summary":"...","actionable_feedback":[],"suggested_revision":"...","revision_priority":"medium","confidence":0.7,"hidden_reference_used":false,"hidden_reference_leaked":false,"failed_or_weak_rubric_items":[],"artifact_specific_comments":[],"trace_specific_comments":[],"metadata_json":{}},"revision_plan":{"revision_plan_id":"revision_plan_<task_id>","task_id":"...","source_attempt_id":"...","target_attempt_id":"...","revision_kind":"local_fix","revision_reason":"...","failed_rubric_items":[],"planned_changes":[],"risk_of_regression":"medium","uses_evaluator_feedback":true,"metadata_json":{}}}.
 Evaluate the attempt by first reading the loop review packet when provided, then checking compact Mentor grader/verifier outputs, actual_outputs.json, artifact refs, artifact content previews, and trace evidence. Treat the review packet as the current iteration dossier: it summarizes outputs, artifacts, trace refs, rubric/verifier status, known failures, diff evidence, and recommended review focus. Produce grounded actionable feedback and a concrete revision plan whose revision guidance can be mapped to feedback_type/feedback_content in future traces. Keep the response concise. Do not rely on Apprentice Agent self-assessment or self evaluation as outcome evidence. Do not use deterministic fallback judgement; structural guardrails are integrity checks only and are not outcome judgments.
-Target revised attempt id: """ + target_attempt_id + "\nLoop Review Packet JSON:\n" + json.dumps(review_packet or {}, sort_keys=True)[:5000] + "\nCompact GraderResult JSON:\n" + json.dumps(_compact_grader(grader), sort_keys=True) + "\nCompact VerifierResult JSON:\n" + json.dumps(_compact_verifier(verifier), sort_keys=True) + "\nCompact ActualOutputs JSON:\n" + json.dumps(_compact_actual(outputs), sort_keys=True) + "\nArtifact content previews JSON:\n" + json.dumps(_compact_artifact_previews(artifact_preview_bundle), sort_keys=True)[:5000] + "\nCompact Trace summary JSON:\n" + json.dumps(_compact_trace_summary(trace), sort_keys=True)[:3000]
+Target revised attempt id: """ + target_attempt_id + "\nLoop Review Packet JSON:\n" + json.dumps(review_packet or {}, sort_keys=True)[:5000] + "\nCompact GraderResult JSON:\n" + json.dumps(_compact_grader(grader), sort_keys=True) + "\nCompact VerifierResult JSON:\n" + json.dumps(_compact_verifier(verifier), sort_keys=True) + "\nCompact ActualOutputs JSON:\n" + json.dumps(_compact_actual(outputs), sort_keys=True) + "\nArtifact content previews JSON:\n" + json.dumps(_compact_artifact_previews(artifact_preview_bundle), sort_keys=True)[:5000] + "\nCompact Trace summary JSON:\n" + json.dumps(_compact_trace_summary(trace), sort_keys=True)
 
-def evaluate_attempt(grader: GraderResult, verifier: VerifierResult, outputs: ActualOutputs, trace: AgentTrace | None, target_attempt_id: str, role_root: Path | None=None, package_root: Path | None=None) -> tuple[EvaluatorFeedback, RevisionPlan]:
+def evaluate_attempt(grader: GraderResult, verifier: VerifierResult, outputs: ActualOutputs, trace: WorkflowTrace | None, target_attempt_id: str, role_root: Path | None=None, package_root: Path | None=None) -> tuple[EvaluatorFeedback, RevisionPlan]:
     settings=get_settings(); role_root=role_root or Path('outputs/roles')
     artifact_preview_bundle=build_artifact_previews(package_root, grader.evidence_refs or outputs.deliverable_refs or outputs.artifact_refs or outputs.files_created)
     review_packet=_latest_review_packet(package_root, outputs.attempt_kind)

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/grader.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
+from .atif import from_workflow
 from pathlib import Path
 import json, re
 from .schemas import GraderResult, RubricSpec, ActualOutputs, RubricItemScore
 from .config import get_settings
-from .schemas import AgentTrace
-from .io import read_json, write_json
+from .schemas import WorkflowTrace
+from .io import read_workflow_json as read_json, write_json
 from .openai_structured import get_model_provider_status, run_structured_role
 from .public_sanitizer import sha256_text
 from .artifact_previews import build_artifact_previews
@@ -128,13 +129,13 @@ def deterministic_grade(rubric: RubricSpec, outputs: ActualOutputs, attempt_kind
     score=artifact_contract_score
     return GraderResult(grader_result_id=f'grader_{outputs.attempt_id}', task_id=outputs.task_id, attempt_id=outputs.attempt_id, attempt_kind=attempt_kind, rubric_id=rubric.rubric_id, grader_kind='structural_guardrail', score_source='structural_guardrail', score=score, max_score=1.0, passed=artifact_contract_passed, rubric_item_scores=item_scores, failed_criteria=[s.rubric_item_id for s in item_scores if not s.passed], passed_criteria=[s.rubric_item_id for s in item_scores if s.passed], evidence_refs=evidence, confidence=0.8, reasoning_summary='Structural guardrail checked artifact presence/readiness only; Mentor grading is unavailable unless a Mentor Model or human grader runs.', limitations=['semantic_quality_not_judged','mentor_grade_unavailable'], hidden_reference_used=False, hidden_reference_leaked=False, artifact_contract_score=artifact_contract_score, semantic_score=None, final_score=score, model=None, provider=None, deterministic_precheck_ref=None, public_response_summary='Structural artifact-contract guardrail completed.', score_reliability='needs_review', metadata_json={'structural_guardrail': True, 'role_status': 'mentor_grader_unavailable', 'artifact_contract_passed': artifact_contract_passed, 'semantic_quality_not_judged': True, 'missing_artifacts': missing, **match})
 
-def _grader_prompt(rubric: RubricSpec, outputs: ActualOutputs, trace: AgentTrace | None, precheck: GraderResult, artifact_preview_bundle: dict | None=None) -> str:
+def _grader_prompt(rubric: RubricSpec, outputs: ActualOutputs, trace: WorkflowTrace | None, precheck: GraderResult, artifact_preview_bundle: dict | None=None) -> str:
     return """Return only valid JSON matching GraderResult. Do not include markdown.
 You are the Mentor Model grader. Score each rubric item using the Apprentice-generated plus Mentor-audited task rubric, attempt trace, actual_outputs.json, artifact refs, and artifact content previews when available. Return a JSON object with exactly these required top-level fields: grader_result_id, task_id, attempt_id, attempt_kind, rubric_id, grader_kind, score_source, artifact_contract_score, model_score, semantic_score, final_score, score, max_score, passed, confidence, evidence_refs, rubric_item_scores, limitations, hidden_reference_used, hidden_reference_leaked, metadata_json. Each rubric_item_scores entry must include artifact_presence_ok, semantic_correctness_score, evidence_refs, reasoning_summary, confidence, failure_mode, and improvement_suggestion. Cite evidence_refs from actual_outputs/artifacts/trace, distinguish artifact presence from Mentor-judged correctness, and set score_source=model_judged and grader_kind=model. Do not rely on Apprentice Agent self-assessment or self evaluation. Do not use deterministic fallback judgement; structural artifact-contract guardrails are auxiliary only and are not grader judgments.
 Rubric JSON:
-""" + json.dumps(rubric.model_dump(), sort_keys=True) + "\nActualOutputs JSON:\n" + json.dumps(outputs.model_dump(), sort_keys=True) + "\nArtifact content previews JSON:\n" + json.dumps(artifact_preview_bundle or {}, sort_keys=True)[:16000] + "\nTrace summary JSON:\n" + json.dumps((trace.model_dump() if trace else {}), sort_keys=True)[:12000] + "\nStructural guardrail JSON:\n" + json.dumps(precheck.model_dump(), sort_keys=True)
+""" + json.dumps(rubric.model_dump(), sort_keys=True) + "\nActualOutputs JSON:\n" + json.dumps(outputs.model_dump(), sort_keys=True) + "\nArtifact content previews JSON:\n" + json.dumps(artifact_preview_bundle or {}, sort_keys=True)[:16000] + "\nTrace summary JSON:\n" + json.dumps((from_workflow(trace.model_dump()) if trace else {}), sort_keys=True) + "\nStructural guardrail JSON:\n" + json.dumps(precheck.model_dump(), sort_keys=True)
 
-def grade_attempt(rubric: RubricSpec, outputs: ActualOutputs, attempt_kind: str, trace: AgentTrace | None=None, role_root: Path | None=None, package_root: Path | None=None) -> GraderResult:
+def grade_attempt(rubric: RubricSpec, outputs: ActualOutputs, attempt_kind: str, trace: WorkflowTrace | None=None, role_root: Path | None=None, package_root: Path | None=None) -> GraderResult:
     settings=get_settings()
     pre=deterministic_grade(rubric, outputs, attempt_kind, package_root)
     role_root=role_root or Path('outputs/roles')

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/integration_status.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from typing import Any
 
 from .config import get_settings, mentor_model_provider_readiness, apprentice_agent_readiness_status
-from .io import append_jsonl, read_jsonl
+from .io import append_jsonl, read_workflow_jsonl as read_jsonl
 from .recipes import MODEL_PROVIDER_RECIPES, WORKER_AGENT_RECIPES
 
 

package/src/agent_apprenticeship/io.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+import json, hashlib
+from pathlib import Path
+from pydantic import BaseModel
+from .atif import encode_traces, decode_traces, validate_trace, event_trace, NAMESPACE
+
+TRACE_FILES = {'agent_trace.json', 'agent_trace.raw.json', 'agent_trace.normalized.json', 'trajectory.json', 'trace.json', 'trace.jsonl', 'agent_traces.jsonl', 'raw_agent_traces.jsonl'}
+EVENT_FILES = {'tdo_trace.jsonl', 'compiler_trace.jsonl', 'session_events.jsonl'}
+
+
+def _encode(path: Path, obj):
+    data = obj.model_dump(mode='json') if isinstance(obj, BaseModel) else obj
+    data = encode_traces(data)
+    if path.name in EVENT_FILES and isinstance(data, dict) and 'agent' not in data:
+        data = event_trace(data, 'experience-compiler' if path.name != 'session_events.jsonl' else 'agent-apprenticeship')
+    if path.name in TRACE_FILES | EVENT_FILES:
+        data = validate_trace(data)
+    return data
+
+
+def write_json(path: Path, obj):
+    data = _encode(path, obj)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True, ensure_ascii=False)+'\n', encoding='utf-8')
+
+
+def read_json(path: Path):
+    data = json.loads(path.read_text(encoding='utf-8'))
+    if path.name in TRACE_FILES | EVENT_FILES:
+        return validate_trace(data)
+    return data
+
+
+def append_jsonl(path: Path, obj):
+    data = _encode(path, obj)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open('a', encoding='utf-8') as f:
+        f.write(json.dumps(data, sort_keys=True, ensure_ascii=False)+'\n')
+
+
+def read_jsonl(path: Path):
+    if not path.exists(): return []
+    rows = [json.loads(line) for line in path.read_text(encoding='utf-8').splitlines() if line.strip()]
+    if path.name in TRACE_FILES | EVENT_FILES:
+        return [validate_trace(row) for row in rows]
+    return rows
+
+
+def _workflow(data, path):
+    if path.name in EVENT_FILES:
+        return data['extra'][NAMESPACE]['event']
+    return decode_traces(data)
+
+
+def read_workflow_json(path: Path):
+    return _workflow(read_json(path), path)
+
+
+def read_workflow_jsonl(path: Path):
+    return [_workflow(row, path) for row in read_jsonl(path)]
+
+
+def sha256_file(path: Path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def validate_trace_tree(root: Path) -> int:
+    """Validate trace documents and embedded trajectories before package exchange."""
+    count = 0
+
+    def check(value):
+        nonlocal count
+        if isinstance(value, list):
+            for item in value:
+                check(item)
+        elif isinstance(value, dict):
+            if isinstance(value.get('steps'), list) and ('agent' in value or 'trace_id' in value):
+                validate_trace(value)
+                count += 1
+            else:
+                for item in value.values():
+                    check(item)
+
+    for path in root.rglob('*'):
+        if not path.is_file() or path.suffix not in {'.json', '.jsonl'}:
+            continue
+        try:
+            if path.suffix == '.jsonl':
+                for row in read_jsonl(path):
+                    check(row)
+            else:
+                check(read_json(path))
+        except (ValueError, TypeError) as exc:
+            if path.name in TRACE_FILES | EVENT_FILES:
+                raise ValueError(f'{path}: invalid ATIF v1.8 trace: {exc}') from exc
+            # Non-trace artifacts can contain arbitrary or partial JSON. A parsed
+            # envelope containing a recognizable invalid trace must still fail.
+            try:
+                rows = [json.loads(line) for line in path.read_text().splitlines() if line.strip()] if path.suffix == '.jsonl' else [json.loads(path.read_text())]
+            except ValueError:
+                continue
+            for row in rows:
+                check(row)
+    return count

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/learning.py

@@ -11,7 +11,7 @@ from typing import Any
 
 from .config import Settings, get_settings
 from .env import contains_secret
-from .io import append_jsonl, read_json, read_jsonl, write_json
+from .io import append_jsonl, read_workflow_json as read_json, read_workflow_jsonl as read_jsonl, write_json
 from .version import get_package_version
 
 
@@ -169,6 +169,8 @@ def _source_id(row: dict[str, Any]) -> str:
 
 
 def _bundle_source(path: Path) -> dict[str, Any]:
+    from .io import validate_trace_tree
+    validate_trace_tree(path)
     manifest_path = path / "contribution_manifest.json"
     manifest = read_json(manifest_path) if manifest_path.exists() else {}
     bundle_id = str(manifest.get("bundle_id") or path.name)
@@ -424,6 +426,8 @@ def compile_experience_pack(
     write_json(pack_path / "source_refs.json", {"sources": source_refs})
     (pack_path / "skill.md").write_text(skill)
     (pack_path / "SUMMARY.md").write_text(summary)
+    from .agent_env_exporter import export_agent_env
+    export_agent_env(pack_path)
     return pack_path
 
 
@@ -692,6 +696,8 @@ def install_runtime_training_from_bundle(
     """Install runtime-useful Experience Compiler outputs into the local registry."""
     s = settings or get_settings()
     bundle = _find_bundle_root(bundle_path)
+    from .io import validate_trace_tree
+    validate_trace_tree(bundle)
     compiler = bundle / "experience_compiler"
     skill_dir = compiler / "skill_pack"
     runtime_dir = compiler / "runtime_learning_package"

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/loop.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 from pathlib import Path
 from typing import Callable
-from .schemas import RawTaskRecord, ActualOutputs, AgentTrace
+from .schemas import RawTaskRecord, ActualOutputs, WorkflowTrace
 from .config import get_settings
 from .task_intake import task_intake
 from .rubric_generation import generate_rubric
@@ -15,7 +15,7 @@ from .loop_review import reviewer_feedback_from_evaluator, write_loop_review_ite
 from .lesson_extractor import extract_lesson
 from .training_signals import process_supervision_from_trace, reward_modeling, training_signals
 from .revision import compute_hillclimb, preference_pair
-from .io import write_json, append_jsonl, read_json
+from .io import write_json, append_jsonl, read_workflow_json as read_json
 
 
 def _attempt(package_root, raw, spec, kind, runner, feedback=None):
@@ -37,7 +37,7 @@ def _is_apprentice_operational_failure(actual: ActualOutputs) -> bool:
     )
 
 
-def _write_baseline_only_signals(pkg: Path, b_actual: ActualOutputs, b_grade, b_ver, b_trace: AgentTrace, fb) -> None:
+def _write_baseline_only_signals(pkg: Path, b_actual: ActualOutputs, b_grade, b_ver, b_trace: WorkflowTrace, fb) -> None:
     lesson=extract_lesson(compute_hillclimb(b_grade, b_grade)); write_json(pkg/'signals/lesson_pack.json', lesson)
     for ex in process_supervision_from_trace(b_trace, b_grade, b_ver, fb): append_jsonl(pkg/'signals/process_supervision.jsonl', ex)
     append_jsonl(pkg/'signals/reward_modeling.jsonl', reward_modeling(b_actual,b_grade))
@@ -76,7 +76,7 @@ def run_task(
     actual_iterations=1
     baseline = _attempt(pkg, raw, spec, 'baseline', runner)
     b_actual=ActualOutputs.model_validate(read_json(pkg/'attempts/baseline/actual_outputs.json'))
-    b_trace=AgentTrace.model_validate(read_json(pkg/'attempts/baseline/agent_trace.json'))
+    b_trace=WorkflowTrace.model_validate(read_json(pkg/'attempts/baseline/agent_trace.json'))
     if attempt_complete_callback:
         attempt_complete_callback(pkg, 'baseline')
     revised_attempt_ids=[]; selected_attempt_id=b_actual.attempt_id
@@ -165,7 +165,7 @@ def run_task(
     revised = _attempt(pkg, raw, spec, 'revised', runner, fb.feedback_summary)
     actual_iterations=2
     r_actual=ActualOutputs.model_validate(read_json(pkg/'attempts/revised/actual_outputs.json'))
-    r_trace=AgentTrace.model_validate(read_json(pkg/'attempts/revised/agent_trace.json'))
+    r_trace=WorkflowTrace.model_validate(read_json(pkg/'attempts/revised/agent_trace.json'))
     r_grade=grade_attempt(rubric, r_actual, 'revised', r_trace, role_root, pkg)
     r_ver=verify_attempt(r_grade, r_actual, r_trace, role_root, pkg)
     r_grade=apply_score_reliability(r_grade, r_ver)

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/loop_review.py

@@ -5,7 +5,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-from .io import read_json, write_json
+from .io import read_workflow_json as read_json, write_json
 from .public_sanitizer import sanitize_public_obj, sanitize_public_text
 
 

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/mentor_checkpoints.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from typing import Any, Iterable
 
 from .config import Settings
-from .io import read_json, write_json
+from .io import read_workflow_json as read_json, write_json
 
 
 def _now() -> str:

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/package_exporter.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 from pathlib import Path
 import hashlib, mimetypes, json, shutil
 from .schemas import *
-from .io import write_json, append_jsonl
+from .io import write_json, append_jsonl, read_workflow_json as read_json
 from .rubric_generation import worker_visible_markdown
 from .artifact_resolver import artifact_ref_candidates, normalize_artifact_ref
 
@@ -220,7 +220,7 @@ def _trace_artifact_links(package_root: Path) -> dict[str, list[dict]]:
     links: dict[str, list[dict]] = {}
     for trace_path in package_root.glob('attempts/*/agent_trace.json'):
         try:
-            trace=json.loads(trace_path.read_text())
+            trace=read_json(trace_path)
         except Exception:
             continue
         attempt_id=trace.get('attempt_id')
@@ -250,7 +250,7 @@ def write_artifacts_index(package_root: Path):
     trace_links=_trace_artifact_links(package_root)
     for f in package_root.rglob('*'):
         rel=f.relative_to(package_root)
-        if is_ignored_release_path(rel):
+        if 'agent_env' in rel.parts or is_ignored_release_path(rel):
             continue
         if f.is_file() and f.name != 'artifacts_index.json':
             mime=mimetypes.guess_type(f.name)[0]
@@ -300,4 +300,6 @@ def write_artifacts_index(package_root: Path):
     manifest['trace_counters']=counters
     write_json(manifest_path, manifest)
     write_json(package_root/'artifacts_index.json', paths)
+    from .agent_env_exporter import export_agent_env
+    export_agent_env(package_root)
     return paths

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/progress.py

@@ -6,7 +6,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Callable, Literal
 
-from .io import append_jsonl, read_json, read_jsonl, write_json
+from .io import append_jsonl, read_workflow_json as read_json, read_workflow_jsonl as read_jsonl, write_json
 
 RUN_TERMINAL_STATUSES = {"completed", "partial", "failed"}
 

package/src/{agent_apprenticeship_trace → agent_apprenticeship}/public_run.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from .bundle_exporter import create_contribution_bundle
 from .config import Settings, apprentice_agent_display_name, apprentice_agent_readiness_status, get_settings, settings_override
 from .env import redact_secrets
-from .io import read_json, write_json
+from .io import read_workflow_json as read_json, write_json
 from .loop import run_task
 from .loop_review import record_followup_review_update, record_human_loop_feedback
 from .mentor_checkpoints import write_mentor_checkpoints