For AI agents: the complete documentation index is available at https://wangyuxinwhy.github.io/agent-session-facts/llms.txt, the full documentation bundle is available at https://wangyuxinwhy.github.io/agent-session-facts/llms-full.txt, and this page is available as Markdown at https://wangyuxinwhy.github.io/agent-session-facts/reference/schema.md.

Output Schema

Every successful inspection emits one agent_session_facts.report JSON object for one logical Agent Session. This is the stable machine-readable contract for scripts and other consumers. The report has two independently versioned views:

  • uniform contains facts with the same meaning across Codex, Pi, and Claude Code.
  • runtime_specific preserves native topology and accounting details that cannot be normalized without losing meaning.

Terms used below:

  • A Session is one logical, runtime-owned Agent context, even when its evidence spans several files.
  • A Loop is one outer execution cycle inside that Session, such as a user request followed by Agent work and an ending boundary.
  • An Item is a counted program fact. The current uniform schema exposes tool calls as Items.
  • A Source is one physical JSONL file read to produce the report. JSONL means one JSON record per line.

Envelope

{
  "schema_version": 1,
  "type": "agent_session_facts.report",
  "runtime": "codex",
  "complete": true,
  "incomplete_reasons": [],
  "uniform": {
    "schema": "agent_session_facts.uniform@1",
    "session": {},
    "sources": []
  },
  "runtime_specific": {
    "schema": "agent_session_facts.codex@1",
    "facts": {}
  }
}
FieldMeaning
schema_versionVersion of the outer report envelope. Consumers should reject unsupported versions.
typeConstant discriminator: agent_session_facts.report.
runtimeArtifact format that was parsed: codex, pi, or claude.
completetrue only when no supported evidence gap was detected anywhere in the report.
incomplete_reasonsMachine-readable detected reasons why complete is false; empty when the report is complete. Some reasons include a native identity or Source path after a colon.
uniformCross-runtime fields whose meanings are shared by all supported runtimes.
runtime_specificNative fields that require the schema named by runtime_specific.schema.

complete: false is not a command failure. It means the supplied files were readable and the report contains every safely known fact, but at least one coverage, lifecycle, usage, or source-integrity gap remains.

Uniform Session

{
  "native_id": "runtime-owned-session-id",
  "source_count": 1,
  "runtime_versions": ["2.1.232"],
  "source_coverage": {
    "status": "complete",
    "basis": "single_native_pi_session_source",
    "supplied_sources": 1,
    "runtime_declared_child_sessions": 0,
    "missing_runtime_declared_child_sessions": []
  },
  "loops": {
    "total": 2,
    "completed": 1,
    "failed": 0,
    "interrupted": 1,
    "ended_without_outcome": 0,
    "open": 0
  },
  "usage": {
    "status": "available",
    "values": {
      "input": 801795,
      "cached": 706624,
      "cache_write": 0,
      "output": 11186,
      "reasoning": 5476
    },
    "known_values": null
  },
  "items": {
    "agent.tool_call": {
      "total": 29,
      "by_name": {
        "bash": 17,
        "read": 8
      }
    }
  },
  "model_cost": {
    "status": "available",
    "amount_usd": 0.6652902,
    "basis": "runtime_recorded",
    "reason": null
  }
}
FieldMeaning
native_idSession identifier written by the runtime. It is not generated by this tool.
source_countNumber of physical JSONL files inspected; equal to uniform.sources.length.
runtime_versionsDistinct runtime version strings observed in the supplied files, sorted and deduplicated. Empty means the artifacts did not record a version.
source_coverageWhether runtime-declared child or subagent Sources were supplied. This covers the Source set only; inspect top-level complete for all evidence gaps.
loopsCounts of outer execution cycles and their observed outcomes.
usageNormalized model-token accounting and its availability.
itemsCounts of supported program facts, currently agent.tool_call.
model_costCost recorded by the runtime, or an explicit unavailable/partial state.

Source coverage

FieldMeaning
statuscomplete when every child Session declared by the supplied artifacts was also supplied; otherwise incomplete.
basisMachine-readable rule used to assess coverage. Pi uses its single native Session file; Codex and Claude compare supplied Sources with runtime-declared children.
supplied_sourcesNumber of physical files supplied to this inspection.
runtime_declared_child_sessionsNumber of child Threads or subagents explicitly declared by the runtime artifacts. Pi reports 0 because its fork is a separately identified Session.
missing_runtime_declared_child_sessionsNative identities declared by the runtime but absent from the supplied files. Empty means none are known missing.

Source coverage can be complete while the overall report is incomplete—for example, when every file was supplied but a Loop is still open or a usage record is missing.

Loop outcomes

FieldMeaning
totalNumber of observed Loops. It equals the sum of the five outcome fields below.
completedThe runtime stated successful completion.
failedThe runtime stated failure.
interruptedThe runtime stated interruption or abort.
ended_without_outcomeAn ending boundary exists, but the runtime did not state an outcome.
openNo ending boundary was observed.

The outcome counts sum to total.

Usage

Usage uses inclusive totals: the more specific counters below are already contained in their parent total.

FieldMeaning
inputTotal model input. It already includes ordinary uncached input, cache reads, and cache writes.
cachedInput tokens served from an existing prompt cache during this request. This is the cache-read portion of input.
cache_writeInput tokens newly stored in the prompt cache for later requests. This is the cache-write portion of input.
outputTotal model output, including reasoning.
reasoningThe reasoning portion of output.

When both cache fields are known:

input = ordinary_uncached_input + cached + cache_write

For example, input: 1000, cached: 600, and cache_write: 200 means:

  • 600 input tokens were read from an existing cache.
  • 200 input tokens were written to cache for future requests.
  • 200 input tokens were ordinary uncached input.
  • Total input remains 1000. Do not calculate input + cached + cache_write.

The same rule applies to output: reasoning is already included in output. For example, output: 100 and reasoning: 40 still means 100 total output tokens, not 140.

Total model tokens are derived as input + output; no redundant total is stored. Every uniform field is always serialized. Nullable usage fields use null when the adapter cannot establish a value from the supported artifacts; null is unknown, while 0 means the adapter established that the count was zero.

status is:

  • available: complete values are in values; known_values is null.
  • partial: safely known values are in known_values; values is null.
  • unavailable: both value fields are null.

known_values is the subtotal supported by the records that did expose usage. It is safe to treat it as known evidence, but not as the complete Session total.

Tool calls

FieldMeaning
agent.tool_call.totalNumber of native tool invocations observed across the Session after that runtime's inherited-history and repeated-snapshot handling. This counts invocations, not distinct tool names.
agent.tool_call.by_nameTool name to invocation count. Keys are runtime-recorded tool names, and the counts sum to total.

Model cost

FieldMeaning
statusavailable when amount_usd covers all relevant recorded costs, partial when it is only a known subtotal, or unavailable when no supported amount was found.
amount_usdUSD amount recorded in the runtime artifacts. null when no amount is safely known.
basisHow the amount was obtained. runtime_recorded is complete recorded cost; runtime_recorded_known_values is a partial subtotal.
reasonMachine-readable explanation when cost is unavailable; otherwise null.

The tool never calculates cost from a pricing table. Pi can expose runtime-recorded cost; Codex and Claude Code currently report it as unavailable because their supported Session artifacts do not record it.

Sources

Each source fixes the inspected physical snapshot:

{
  "path": "/canonical/path/to/session.jsonl",
  "sha256": "0123456789abcdef...",
  "bytes": 12345,
  "records": 42,
  "terminal_newline": true
}
FieldMeaning
pathCanonical absolute path of the file that was read.
sha256Lowercase SHA-256 digest of the exact bytes inspected.
bytesFile size in bytes for the inspected snapshot.
recordsNumber of complete JSONL records parsed from the file.
terminal_newlineWhether the file ended with a newline. false is retained as an incompleteness signal because the runtime may still have been writing the last record.

Runtime-specific facts

Runtime-specific fields are intentionally not forced into one common body:

SchemaPreserved facts
agent_session_facts.codex@1Thread lineage, inherited-history ordinals, native tool kinds, cumulative usage samples, duplicate snapshots, and counter resets.
agent_session_facts.pi@1Entry tree, Session format version, message roles, stop reasons, tokens written to Pi's one-hour cache tier, known reasoning, and runtime-recorded cost coverage.
agent_session_facts.claude@1Root/subagent contexts, UUID record trees, native tool kinds, and physical/progressive/duplicate assistant usage snapshots.

Follow the runtime_specific.schema identifier before interpreting facts. New incompatible uniform meanings require agent_session_facts.uniform@2; incompatible CLI contracts require an appropriate crate version change.