Skip to content

Latest commit

 

History

History
110 lines (68 loc) · 5.27 KB

SPEC.md

File metadata and controls

110 lines (68 loc) · 5.27 KB

CAUR v0.1 Draft Specification

1. Scope

The Coding Agent Usage Record (CAUR) is a JSON document describing the usage, timing, outcome, and optional monetary cost of one coding-agent run.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in BCP 14 when they appear in capitals.

2. Record lifecycle

A producer SHOULD emit a record when a run reaches a terminal state. Records are immutable after publication. A corrected record MUST have a new record_id and MUST set supersedes to the replaced record's ID.

Duplicate delivery is allowed. Consumers MUST use record_id for deduplication.

3. Privacy boundary

A CAUR document MUST NOT contain prompts, responses, source code, patches, tool arguments, tool output, environment variables, or credentials.

Identifiers MAY be pseudonymous. Producers SHOULD minimize user and tenant identifiers to what the intended accounting process requires.

4. Core fields

The JSON Schema is normative for field types and required properties. The requirements below define their meaning.

4.1 Record identity

  • schema_version: MUST be 0.1-draft for this draft.
  • record_id: globally unique immutable record identifier.
  • created_at: time the record was created, in RFC 3339 format.
  • supersedes: optional record_id replaced by this record.
  • producer: name and optional version of the component producing CAUR.

4.2 Run identity and relationships

  • run.id: identifier for this run within the producer's domain.
  • run.session_id: optional identifier grouping multiple runs.
  • run.parent_run_id: optional immediate parent for a subagent run.
  • run.trace_id: optional reference to an external trace. CAUR does not embed trace data.
  • run.harness: harness name and optional version.

Each nested agent MAY have its own CAUR document connected with parent_run_id. A parent MUST NOT add child model usage to its own model_usage unless it is intentionally publishing a roll-up and declares the extension that describes that aggregation.

4.3 Outcome

outcome.status is one of succeeded, failed, cancelled, or timed_out. outcome.error_class MAY contain a low-cardinality error category but MUST NOT contain an error message or stack trace.

4.4 Timing

timing.started_at and timing.ended_at define the run's wall-clock interval. wall_ms MUST equal the elapsed wall-clock time within the producer's clock precision.

Optional durations have these meanings:

  • active_ms: union of intervals in which this agent actively performed model or tool work;
  • model_ms: union of this run's model-call intervals;
  • tool_ms: union of this run's tool-call intervals;
  • approval_wait_ms: time waiting for a human decision;
  • queue_ms: time waiting for scheduled work to begin.

Intervals that overlap MUST be unioned before calculating each duration. Consequently, durations are not necessarily additive. Child-run time MUST NOT be added blindly to parent-run time.

4.5 Model usage

model_usage contains one item per model request known to the producer. An item identifies the provider, the model reported to the producer, token quantities, and measurement source. requested_model MAY additionally preserve the originally requested alias when it differs from the reported model.

source has the following precedence when reconciling equivalent measurements:

  1. provider_authoritative
  2. harness_reported
  3. gateway_measured
  4. estimated

A value marked estimated MUST remain identifiable as estimated in downstream processing. Missing quantities mean unknown and MUST NOT be treated as zero.

The standard token fields are input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, and reasoning_tokens. Provider-specific quantities MAY be carried in extensions.

4.6 Tool usage

tool_usage contains aggregated usage for a tool within this run. Tool names SHOULD be stable, low-cardinality identifiers. A record MUST NOT include tool arguments or output.

4.7 Costs

costs is optional. Each item represents one cost interpretation (list, contract, or effective) and uses a decimal string plus an ISO 4217 currency code. Binary floating-point JSON numbers are deliberately not used for money.

A cost SHOULD include a stable pricing_reference or pricing_version sufficient to reproduce the calculation. Cost is not authoritative merely because it appears in CAUR; source records where it came from.

5. Extensions

Objects that define extensions accept additional fields there. Extension names MUST use a collision-resistant prefix, such as a reverse-domain name:

{
  "extensions": {
    "org.example.energy_wh": 0.42
  }
}

Consumers MUST ignore extensions they do not understand. New generally useful fields should be proposed for the common schema only after evidence from implementations.

6. Conformance

A conforming CAUR v0.1 draft producer:

  1. emits JSON that validates against schema/caur-v0.1.schema.json;
  2. follows the privacy boundary;
  3. labels the measurement source for every model-usage item;
  4. does not silently mutate published records; and
  5. calculates parallel durations as interval unions.

A conforming consumer MUST deduplicate by record_id, preserve measurement provenance, and ignore unknown extensions.