Harbor ATIF import¶
AgentLoop 0.1.0 imports ATIF v1.7/v1.8 and a v1.6 compatibility
subset without Harbor, Docker, a provider SDK or network access. Import reads
data; it does not execute an agent or verifier. These commands are included in
agentloop-profiler==0.1.0.
This implements the trajectory boundary of workstream #273. Job/trial inventory, verifier outcomes, JSONL and paired studies remain separate work.
Offline workflow¶
uv run --frozen agentloop harbor import-atif tests/fixtures/external/harbor/atif_embedded_subagents.json --out runs/harbor-import --synthetic
uv run --frozen agentloop harbor inspect-atif tests/fixtures/external/harbor/atif_embedded_subagents.json --json-out runs/harbor-inventory.json
uv run --frozen python examples/harbor_atif.py --out runs/harbor-example
The example writes three native traces, source receipts, inventory, analysis JSON and self-contained HTML. The source documents share a session but keep distinct run IDs. Token counts and optional source intervals are synthetic contract data, not an observed provider execution or an optimization benefit.
Analyze any generated traces/run_*.json using the existing command:
report, diagnose and optimize use the same qualified metrics and canonical
finding rules. Omit --synthetic for actual source data. --root selects the
allowed reference root, defaulting to the input directory. Local trajectory
references require .json and resolve relative to the source document; absolute,
remote, parent-traversal and symlink/junction/reparse paths are unsupported.
Media references are never opened. Use a stable artifact snapshot.
--continue-on-error preserves invalid primary documents as error receipts.
Malformed child documents remain error receipts in partial imports. Missing,
unsafe, mismatched and cyclic references stay unresolved. Bounds are terminal;
continue mode does not bypass them.
Python API and identity¶
from agentloop.integrations.harbor.atif import AtifOptions, import_atif
result = import_atif(
"jobs/trial/agent/trajectory.json",
root="jobs/trial",
identity={"job_id": "recorded-job", "trial_id": "recorded-trial"},
options=AtifOptions(),
)
result.write("runs/imported-trial")
print(result.inventory())
The internal result contains traces and immutable source_receipts tuples;
warnings returns detached source notices. Caller context is an explicit
declaration, not authentication. Missing document IDs use deterministic hashes
with calculated provenance. Seeds, attempts and task identities are not invented.
Repeated unchanged export preserves bytes. Conflicting existing output or mutation after receipt capture raises an error. Receipt hashes bind the native bytes that result exports. An inventory is not a native study manifest.
Preserved semantics¶
| ATIF signal | Behavior |
|---|---|
| User/system/agent | Original role/order/IDs; not every step is inference |
llm_call_count=0 |
Deterministic dispatch with no model call |
llm_call_count=1 |
One attributed block |
llm_call_count>1 |
One aggregate block plus multiplicity, no fake per-call spans |
| Missing count with model metrics | Evidence block with unknown physical call count |
| Agent text without inference evidence | Agent source record; model coverage unknown |
| Copied context | Sidecar history, no new execution or observation |
| Tools/observations | Call IDs and source-step association; missing results explicit |
| Cache usage | Subset of prompt count, never added twice |
| Final/root/child totals | Separate source aggregates, never added to step usage |
| Embedded children | Resolve by document ID, not shared session ID |
| Delegation/continuation | Relationships, not fabricated causal edges |
| Image/audio | Metadata and safe reference/hash markers, no binary reads |
Imported usage is external_reported, a non-exact, non-evaluable native grade.
Source cost stays in receipts; counts are not multiplied by a price table.
Qualified reports use null for missing input/output counts and separately
retain known partial sums. Native model-call counts count recorded blocks;
reported multiplicity is separate. Provider input context and generic retries
are not present in ATIF, so their metrics remain unavailable.
Timing and reader compatibility¶
ATIF timestamps normally lack end times/durations. Native events require numeric
duration and ok/error, so incomplete projections carry compatibility
placeholders, timing_available=false, source_status_available=false and explicit
unknown timestamps. These are not zero-time measurements or successful runs.
The reserved trace namespace agentloop.external, version 1.0, contains exactly
schema_version, source, receipt_id, runtime_ms, event_timing_complete,
execution_status, usage_complete, reported_model_call_count and
comparison_eligible. Events carry external_evidence_schema: "1.0" and
per-field availability. Missing/malformed qualifications fail closed.
The current reader applies qualifications before reporting. Unavailable latency,
status, usage, critical path and savings stay unavailable. Count-based findings
remain source-qualified; unsupported estimates/inputs are null. JSON, Markdown,
HTML and existing nullable storage preserve these values. Raw trajectories cannot
pass replay/study/value comparisons without a complete trial/quality adapter.
Use this checkout or a future release documenting qualification support. Older readers can structurally accept native schema 1.1 while ignoring the namespace and must not analyze these projections. Native serialization stays compatible; semantic support requires the new reader.
Optional source intervals¶
The adapter recognizes the explicitly documented AgentLoop convention inside
ATIF extra:
{"agentloop": {"timing": {"started_at": "2026-01-01T00:00:00Z", "ended_at": "2026-01-01T00:00:01Z", "duration_ms": 1000}, "execution_status": "completed"}}
Root bounds describe that trajectory, model-step bounds that model block, and tool-call bounds that tool operation. Supply them only when those exact intervals were recorded. Standard Harbor ATIF is not assumed to emit this convention. Timezone-free/incomplete intervals stay unknown; reversed/contradictory ones fail. Retained intervals/status are externally reported, not proof of correctness.
Privacy and limits¶
Messages, arguments, reasoning, token IDs, attachments and exception text are omitted by default. Structural identities are bounded and can still be private. Remote/absolute media paths are hashed. Unknown extensions are bounded/minimized; omissions carry reasons. Known sensitive fields remain omitted.
Python-only opt-ins are separate: capture_content, capture_reasoning and
capture_token_ids. Content capture does not automatically enable the latter
two. Capture is bounded by the metadata limit; review opted-in data before sharing.
ATIF v1.0–v1.5, archives/remote artifacts, vendor restoration, provider-accounting reconciliation, live/paid execution, ATIF export, runtime enforcement and task verification are unsupported here. Hashes identify supplied bytes, not authenticity of agent-writable trajectories. No source/verifier script executes.
Provenance and checks¶
The adapter follows Harbor
07ad34000e4c481451b1a0ea30a4a09548d6de8b.
This is the inspected contract revision, not an inferred producer revision.
The fixture matrix records owned
synthetic data, exact hashes and source versions. No upstream implementation code
was copied. Producer versions remain unknown unless recorded separately.
uv run --frozen python -m pytest tests/test_harbor_atif.py tests/test_interoperability_contracts.py tests/test_token_provenance.py -q -ra
uv run --frozen python examples/harbor_atif.py --out runs/harbor-example
These offline checks cover formats, legacy IDs, intervals, aggregates, copied history, privacy, unsafe/cyclic references, missing data and installed-wheel CLI/HTML. They do not establish live interoperability or empirical improvements.