agent-apprenticeship 0.2.0 → 0.3.0

package/src/agent_apprenticeship/atif_models/final_metrics.py

@@ -0,0 +1,43 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""Final metrics model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FinalMetrics(BaseModel):
+    """Aggregate statistics for the entire trajectory."""
+
+    total_prompt_tokens: int | None = Field(
+        default=None,
+        description="Sum of all prompt tokens across all steps, including cached tokens",
+    )
+    total_completion_tokens: int | None = Field(
+        default=None,
+        description="Sum of all completion tokens across all steps",
+    )
+    total_cached_tokens: int | None = Field(
+        default=None,
+        description="Sum of all cached tokens across all steps",
+    )
+    total_cost_usd: float | None = Field(
+        default=None,
+        description="Total real monetary cost for the entire trajectory, including cost for subagents, if any",
+    )
+    total_steps: int | None = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Total number of steps. If not equivalent to the number of steps in the "
+            "trajectory, must be documented in the root-level notes field."
+        ),
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom aggregate metrics",
+    )
+
+    model_config = {"extra": "forbid"}

package/src/agent_apprenticeship/atif_models/metrics.py

@@ -0,0 +1,47 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""Metrics model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Metrics(BaseModel):
+    """LLM operational and confidence data."""
+
+    prompt_tokens: int | None = Field(
+        default=None,
+        description="Total input tokens including cached and non-cached",
+    )
+    completion_tokens: int | None = Field(
+        default=None,
+        description="Total tokens generated by the LLM response",
+    )
+    cached_tokens: int | None = Field(
+        default=None,
+        description="Subset of prompt_tokens that were cache hits",
+    )
+    cost_usd: float | None = Field(
+        default=None,
+        description="Monetary cost of the API call in USD",
+    )
+    prompt_token_ids: list[int] | None = Field(
+        default=None,
+        description="Token IDs for prompt (input) tokens sent to the LLM, including chat history (if applicable)",
+    )
+    completion_token_ids: list[int] | None = Field(
+        default=None,
+        description="Token IDs for completion (response) tokens, enabling RL training without retokenization drift",
+    )
+    logprobs: list[float] | None = Field(
+        default=None,
+        description="Log probability assigned to each generated token",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Other metrics",
+    )
+
+    model_config = {"extra": "forbid"}

package/src/agent_apprenticeship/atif_models/observation.py

@@ -0,0 +1,19 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""Observation model for ATIF trajectories."""
+
+from pydantic import BaseModel, Field
+
+from agent_apprenticeship.atif_models.observation_result import ObservationResult
+
+
+class Observation(BaseModel):
+    """Environment feedback/result after actions or system events."""
+
+    results: list[ObservationResult] = Field(
+        default=...,
+        description="Array of result objects from tool calls or actions",
+    )
+
+    model_config = {"extra": "forbid"}

package/src/agent_apprenticeship/atif_models/observation_result.py

@@ -0,0 +1,45 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""Observation result model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from agent_apprenticeship.atif_models.content import ContentPart
+from agent_apprenticeship.atif_models.subagent_trajectory_ref import SubagentTrajectoryRef
+
+
+class ObservationResult(BaseModel):
+    """A single result within an observation."""
+
+    source_call_id: str | None = Field(
+        default=None,
+        description=(
+            "The `tool_call_id` from the _tool_calls_ array in _StepObject_ that this "
+            "result corresponds to. If null or omitted, the result comes from an "
+            "action that doesn't use the standard tool calling format (e.g., agent "
+            "actions without tool calls or system-initiated operations)."
+        ),
+    )
+    content: str | list[ContentPart] | None = Field(
+        default=None,
+        description=(
+            "The output or result from the tool execution. String for text-only "
+            "content, or array of ContentPart for multimodal content (added in ATIF-v1.6)."
+        ),
+    )
+    subagent_trajectory_ref: list[SubagentTrajectoryRef] | None = Field(
+        default=None,
+        description="Array of references to delegated subagent trajectories",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Custom observation-result-level metadata (e.g., confidence score, "
+            "retrieval score, source document ID). Added in ATIF-v1.7."
+        ),
+    )
+
+    model_config = {"extra": "forbid"}

package/src/agent_apprenticeship/atif_models/step.py

@@ -0,0 +1,142 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""Step model for ATIF trajectories."""
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from agent_apprenticeship.atif_models.content import ContentPart
+from agent_apprenticeship.atif_models.metrics import Metrics
+from agent_apprenticeship.atif_models.observation import Observation
+from agent_apprenticeship.atif_models.tool_call import ToolCall
+
+
+class Step(BaseModel):
+    """A single step in the trajectory."""
+
+    step_id: int = Field(
+        default=...,
+        ge=1,
+        description="Ordinal index of the turn (starting from 1)",
+    )
+    timestamp: str | None = Field(
+        default=None,
+        description="ISO 8601 timestamp indicating when this step occurred",
+    )
+    source: Literal["system", "user", "agent"] = Field(
+        default=...,
+        description="The originator of this step",
+    )
+    model_name: str | None = Field(
+        default=None,
+        description=(
+            "The specific LLM model used for this turn. Omission implies the model "
+            "defined in the root-level agent config."
+        ),
+    )
+    reasoning_effort: str | float | None = Field(
+        default=None,
+        description="Qualitative or quantitative measure of effort",
+    )
+    message: str | list[ContentPart] = Field(
+        default=...,
+        description=(
+            "The dialogue message. String for text-only content, or array of "
+            "ContentPart for multimodal content (added in ATIF-v1.6)."
+        ),
+    )
+    reasoning_content: str | None = Field(
+        default=None,
+        description="The agent's explicit internal reasoning",
+    )
+    tool_calls: list[ToolCall] | None = Field(
+        default=None,
+        description="Array of structured objects for the agent's actions",
+    )
+    observation: Observation | None = Field(
+        default=None,
+        description="Environment feedback/result after actions or system events",
+    )
+    metrics: Metrics | None = Field(
+        default=None,
+        description="LLM operational and confidence data for this step",
+    )
+    is_copied_context: bool | None = Field(
+        default=None,
+        description=(
+            "Indicates whether this step was copied from a previous trajectory "
+            "for context (e.g., during continuation after summarization). "
+            "Steps marked as copied context should not be included in training data "
+            "as they represent previously-trained interactions. "
+            "Added in ATIF-v1.5."
+        ),
+    )
+    llm_call_count: int | None = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Number of LLM inferences this step represents. When >1, metrics are "
+            "aggregated across multiple LLM calls. When 1, the step represents exactly "
+            "one inference. When 0 on a `source: 'agent'` step, the step represents a "
+            "deterministic (non-LLM) dispatch; `metrics` and `reasoning_content` MUST "
+            "be absent in that case. When null, the producer did not track this "
+            "(backward-compatible default). Added in ATIF-v1.7."
+        ),
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom step-level metadata",
+    )
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("timestamp")
+    @classmethod
+    def validate_timestamp(cls, v: str | None) -> str | None:
+        """Validate that timestamp is a valid ISO 8601 string."""
+        if v is not None:
+            try:
+                datetime.fromisoformat(v.replace("Z", "+00:00"))
+            except ValueError as e:
+                raise ValueError(f"Invalid ISO 8601 timestamp: {e}")
+        return v
+
+    @model_validator(mode="after")
+    def validate_agent_only_fields(self) -> "Step":
+        """Validate that certain fields are only present for agent steps."""
+        if self.source != "agent":
+            agent_only_fields = [
+                "model_name",
+                "reasoning_effort",
+                "reasoning_content",
+                "tool_calls",
+                "metrics",
+            ]
+            for field in agent_only_fields:
+                if getattr(self, field) is not None:
+                    raise ValueError(
+                        f"Field '{field}' is only applicable when source is 'agent', "
+                        f"but source is '{self.source}'"
+                    )
+        return self
+
+    @model_validator(mode="after")
+    def validate_llm_call_count_zero_fields(self) -> "Step":
+        """Enforce ATIF v1.7 no-LLM orchestration rule.
+
+        When ``llm_call_count == 0`` on a ``source: "agent"`` step, the step
+        represents a deterministic (non-LLM) dispatch. LLM-specific fields
+        (``metrics``, ``reasoning_content``) MUST be absent on such steps.
+        """
+        if self.llm_call_count == 0 and self.source == "agent":
+            llm_only_fields = ["metrics", "reasoning_content"]
+            for field in llm_only_fields:
+                if getattr(self, field) is not None:
+                    raise ValueError(
+                        f"Field '{field}' must be absent when llm_call_count is 0 "
+                        f"(deterministic dispatch on a 'source: agent' step)"
+                    )
+        return self

package/src/agent_apprenticeship/atif_models/subagent_trajectory_ref.py

@@ -0,0 +1,88 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""Subagent trajectory reference model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class SubagentTrajectoryRef(BaseModel):
+    """Reference to a delegated subagent trajectory.
+
+    A subagent reference is resolved by one of two mechanisms:
+
+    1. **Embedded form** — set `trajectory_id` to match the
+       `Trajectory.trajectory_id` of an entry in the parent's
+       `subagent_trajectories` array.
+    2. **File-ref form** — set `trajectory_path` to the location
+       (file path, S3 URL, etc.) of an external trajectory file.
+
+    These two mechanisms are the only resolution keys. `session_id`, when
+    present on the ref, is **informational only**: it records the run
+    identity of the delegated subagent for debug / correlation / cross-
+    trajectory search purposes, and MUST NOT be used as a matching key
+    (it is run-scoped and MAY collide across siblings — see
+    `Trajectory.session_id`). A ref therefore MUST set at least one of
+    `trajectory_id` or `trajectory_path`; `session_id` alone is not a
+    resolvable reference.
+    """
+
+    trajectory_id: str | None = Field(
+        default=None,
+        description=(
+            "Canonical identifier of the delegated subagent trajectory. "
+            "Matches `Trajectory.trajectory_id` of an entry in the parent's "
+            "`subagent_trajectories` array and is the resolution key for "
+            "embedded references. Added in ATIF-v1.7 to provide a document-"
+            "unique matching key without overloading `session_id`."
+        ),
+    )
+    session_id: str | None = Field(
+        default=None,
+        description=(
+            "Run identity of the delegated subagent trajectory. Informational "
+            "only: recorded so consumers can correlate this ref back to the "
+            "subagent's run for debug / search / display purposes. Run-scoped "
+            "(see `Trajectory.session_id`) and therefore NOT a valid "
+            "resolution key — consumers MUST resolve via `trajectory_id` "
+            "(embedded) or `trajectory_path` (external file)."
+        ),
+    )
+    trajectory_path: str | None = Field(
+        default=None,
+        description=(
+            "Location of the complete subagent trajectory as an external "
+            "file (file path, S3 URL, database reference, etc.). Resolution "
+            "key for file-ref references. When both `trajectory_id` and "
+            "`trajectory_path` are set, consumers MAY choose either; "
+            "typically `trajectory_id` is preferred when the embedded "
+            "trajectory is available in-memory."
+        ),
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom metadata about the subagent execution",
+    )
+
+    model_config = {"extra": "forbid"}
+
+    @model_validator(mode="after")
+    def validate_is_resolvable(self) -> "SubagentTrajectoryRef":
+        """A ref must be resolvable: set `trajectory_id` or `trajectory_path`.
+
+        `session_id` alone is not sufficient because it is run-scoped and
+        MAY collide across siblings (see `Trajectory.session_id`), so it
+        cannot unambiguously identify which subagent trajectory a ref
+        points at.
+        """
+        if self.trajectory_id is None and self.trajectory_path is None:
+            raise ValueError(
+                "SubagentTrajectoryRef must be resolvable: set either "
+                "`trajectory_id` (for embedded references) or "
+                "`trajectory_path` (for external-file references). "
+                "`session_id` alone is not a resolution key — it is "
+                "run-scoped and may collide across siblings."
+            )
+        return self

package/src/agent_apprenticeship/atif_models/tool_call.py

@@ -0,0 +1,34 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""Tool call model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ToolCall(BaseModel):
+    """A tool call within a step."""
+
+    tool_call_id: str = Field(
+        default=...,
+        description="Unique identifier for this specific tool call",
+    )
+    function_name: str = Field(
+        default=...,
+        description="The name of the function or tool being invoked",
+    )
+    arguments: dict[str, Any] = Field(
+        default=...,
+        description="Arguments passed to the function (can be empty dict)",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Custom tool-call-level metadata (e.g., timeout, retry count, tool version). "
+            "Added in ATIF-v1.7."
+        ),
+    )
+
+    model_config = {"extra": "forbid"}

package/src/agent_apprenticeship/atif_models/trajectory.py

@@ -0,0 +1,196 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""Trajectory model for ATIF (Agent Trajectory Interchange Format)."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from agent_apprenticeship.atif_models.agent import Agent
+from agent_apprenticeship.atif_models.final_metrics import FinalMetrics
+from agent_apprenticeship.atif_models.step import Step
+
+
+class Trajectory(BaseModel):
+    """Agent Trajectory in ATIF (Agent Trajectory Interchange Format)."""
+
+    schema_version: Literal["ATIF-v1.8"] = "ATIF-v1.8"
+    session_id: str | None = Field(
+        default=None,
+        description=(
+            "Identifier for the agent run this trajectory belongs to. Scoped "
+            "to the run, NOT to an individual trajectory document: multiple "
+            "Trajectory objects MAY share the same `session_id` when they "
+            "represent the same logical run (e.g., a parent trajectory and "
+            "its embedded subagents, or a trajectory and its continuation "
+            "segments linked via `continued_trajectory_ref`). Therefore "
+            "`session_id`s within a parent's `subagent_trajectories` array "
+            "are NOT required to be unique. Use `trajectory_id` when a "
+            "per-trajectory-document unique identifier is required (e.g., "
+            "for `SubagentTrajectoryRef` resolution). Optional since "
+            "ATIF-v1.7; producers SHOULD set this on root trajectories for "
+            "run-level traceability, and MAY omit it on embedded subagents "
+            "that inherit the parent's run identity."
+        ),
+    )
+    trajectory_id: str | None = Field(
+        default=None,
+        description=(
+            "Canonical per-trajectory-document identifier, distinct from "
+            "`session_id`. Unlike `session_id` (which is run-scoped and MAY "
+            "be shared), `trajectory_id` uniquely identifies THIS trajectory "
+            "object. Used to resolve `SubagentTrajectoryRef` entries against "
+            "the root's `subagent_trajectories` array without overloading "
+            "`session_id`'s run-scoped semantics. Optional on standalone "
+            "trajectories, but REQUIRED on any trajectory embedded in a "
+            "parent's `subagent_trajectories` array. `trajectory_id`s within "
+            "a single parent's `subagent_trajectories` array MUST be unique. "
+            "Added in ATIF-v1.7."
+        ),
+    )
+    agent: Agent = Field(
+        default=...,
+        description="Object specifying the agent configuration",
+    )
+    steps: list[Step] = Field(
+        default=...,
+        min_length=1,
+        description="Array of step objects representing the complete interaction history",
+    )
+    notes: str | None = Field(
+        default=None,
+        description="Custom information, design notes, or explanations",
+    )
+    final_metrics: FinalMetrics | None = Field(
+        default=None,
+        description="Summary metrics for the entire trajectory",
+    )
+    continued_trajectory_ref: str | None = Field(
+        default=None,
+        description="Reference to the continuation trajectory file if this trajectory is continued in another file",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom root-level metadata",
+    )
+    subagent_trajectories: list["Trajectory"] | None = Field(
+        default=None,
+        description=(
+            "Array of embedded subagent trajectories. Each element is a complete, "
+            "independently-valid ATIF Trajectory with its own schema_version, "
+            "agent, and step_id sequence starting at 1. Enables single-file "
+            "storage of multi-agent workflows: when a "
+            "SubagentTrajectoryRef.trajectory_path is null, consumers resolve "
+            "the reference by matching SubagentTrajectoryRef.trajectory_id "
+            "against Trajectory.trajectory_id of entries in this array. "
+            "Uniqueness rules: every embedded subagent MUST set `trajectory_id`, "
+            "and `trajectory_id`s within this array MUST be unique. "
+            "`session_id`, by contrast, is run-scoped and MAY collide across "
+            "siblings (or match the parent) when all trajectories belong to "
+            "the same logical run; embedded subagents MAY also omit "
+            "`session_id` entirely to inherit the parent's run identity. "
+            "Added in ATIF-v1.7."
+        ),
+    )
+
+    model_config = {"extra": "forbid"}
+
+    def to_json_dict(self, exclude_none: bool = True) -> dict[str, Any]:
+        """Export trajectory to a dictionary suitable for JSON serialization.
+
+        Args:
+            exclude_none: If True, exclude fields with None values from output.
+
+        Returns:
+            Dictionary representation of the trajectory.
+        """
+        return self.model_dump(exclude_none=exclude_none, mode="json")
+
+    @model_validator(mode="after")
+    def validate_step_ids(self) -> "Trajectory":
+        """Validate that step_ids are sequential starting from 1."""
+        for i, step in enumerate(self.steps):
+            expected_step_id = i + 1
+            if step.step_id != expected_step_id:
+                raise ValueError(
+                    f"steps[{i}].step_id: expected {expected_step_id} "
+                    f"(sequential from 1), got {step.step_id}"
+                )
+        return self
+
+    @model_validator(mode="after")
+    def validate_embedded_subagent_trajectory_ids(self) -> "Trajectory":
+        """Every embedded subagent must carry a unique, non-null `trajectory_id`.
+
+        Embedded subagents are resolved by matching
+        `SubagentTrajectoryRef.trajectory_id` against
+        `Trajectory.trajectory_id`, so the identifier must be present and
+        unique within a parent's `subagent_trajectories` array. Note that
+        no such constraint is placed on `session_id` — siblings MAY share
+        a `session_id` (or omit it entirely to inherit the parent's) when
+        they represent the same logical agent run.
+        """
+        if not self.subagent_trajectories:
+            return self
+        seen: set[str] = set()
+        for i, sub in enumerate(self.subagent_trajectories):
+            if sub.trajectory_id is None:
+                raise ValueError(
+                    f"subagent_trajectories[{i}].trajectory_id is required "
+                    f"for embedded subagents "
+                    f"(agent.name={sub.agent.name!r}, "
+                    f"session_id={sub.session_id!r})"
+                )
+            if sub.trajectory_id in seen:
+                raise ValueError(
+                    f"subagent_trajectories[{i}].trajectory_id "
+                    f"{sub.trajectory_id!r} is not unique within "
+                    f"subagent_trajectories"
+                )
+            seen.add(sub.trajectory_id)
+        return self
+
+    @model_validator(mode="after")
+    def validate_tool_call_references(self) -> "Trajectory":
+        """Validate that observation source_call_ids reference valid tool_call_ids."""
+        for step in self.steps:
+            if step.observation is None:
+                continue
+
+            # Collect all tool_call_ids from this step
+            tool_call_ids = set()
+            if step.tool_calls:
+                tool_call_ids = {tc.tool_call_id for tc in step.tool_calls}
+
+            # Check that source_call_ids reference valid tool_call_ids
+            for result in step.observation.results:
+                if result.source_call_id is not None:
+                    if result.source_call_id not in tool_call_ids:
+                        raise ValueError(
+                            f"Observation result references source_call_id "
+                            f"'{result.source_call_id}' which is not found in "
+                            f"step {step.step_id}'s tool_calls"
+                        )
+        return self
+
+    def has_multimodal_content(self) -> bool:
+        """Check if any step contains multimodal content (images or audio).
+
+        Returns:
+            True if any step message or observation contains a media content
+            part. Audio counts since ATIF-v1.8.
+        """
+        media_types = {"image", "audio"}
+        for step in self.steps:
+            if isinstance(step.message, list):
+                for part in step.message:
+                    if part.type in media_types:
+                        return True
+            if step.observation:
+                for result in step.observation.results:
+                    if isinstance(result.content, list):
+                        for part in result.content:
+                            if part.type in media_types:
+                                return True
+        return False

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

@@ -3,7 +3,7 @@ import time, traceback, json
 from datetime import datetime, timezone
 from pathlib import Path
 from .schemas import RawTaskRecord
-from .io import read_jsonl, append_jsonl, write_json
+from .io import read_workflow_jsonl as read_jsonl, append_jsonl, write_json
 from .loop import run_task
 from .release_exporter import create_release
 from .public_sanitizer import classify_provider_failure

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

@@ -1,4 +1,6 @@
 from __future__ import annotations
+from .io import validate_trace_tree
+from .agent_env_exporter import export_agent_env
 
 import shutil
 import tempfile
@@ -8,7 +10,7 @@ from pathlib import Path
 from typing import Any
 
 from .config import Settings, apprenticeship_mode_display, get_settings, normalize_apprenticeship_mode, normalize_mentor_mode
-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, sanitize_public_text
 from .release_exporter import create_release
 from .tdo import tdo_manifest_fields_from_report
@@ -461,11 +463,14 @@ def create_contribution_bundle(
         shutil.rmtree(bundle_root)
     bundle_root.mkdir(parents=True, exist_ok=True)
 
+    validate_trace_tree(run_root)
     if release_style:
         create_release(run_root, bundle_root)
         _copy_session_files(run_root, bundle_root, settings)
         _write_manifest(bundle_root, bundle_root, settings, include_internal_schema=True)
         _write_card(bundle_root)
+        validate_trace_tree(bundle_root)
+        export_agent_env(bundle_root)
         return bundle_root
 
     with tempfile.TemporaryDirectory(prefix="aa-release-for-bundle-") as tmp:
@@ -476,4 +481,6 @@ def create_contribution_bundle(
         _write_manifest(bundle_root, release_root, settings, include_internal_schema=include_debug)
         _write_card(bundle_root)
 
+    validate_trace_tree(bundle_root)
+    export_agent_env(bundle_root)
     return bundle_root

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

@@ -13,7 +13,7 @@ from .config import get_settings, init_settings, update_settings
 from .command_discovery import resolve_command, resolve_agent_command, gui_app_hint
 from .env import redact_secrets
 from .integration_status import record_certification_result
-from .io import read_json
+from .io import read_workflow_json as read_json
 from .openai_structured import run_llm_smoke
 from .public_run import run_prompt_task
 from .recipes import MODEL_PROVIDER_RECIPES, WORKER_AGENT_RECIPES