Skip to content

usage-tracking.md

Latest commit

 

History

History
147 lines (114 loc) · 6.06 KB

usage-tracking.md

File metadata and controls

147 lines (114 loc) · 6.06 KB
Raw

Local Usage Tracking

Status: v1.3 reserved schema with manual import Roadmap source: docs/plans/2026-05-23-platform-roadmap-v1.1-v2.0.md Scope: local usage records under .conductor/

This document defines vendor-neutral usage records for local token and optional cost accounting. The first implementation is manual import only: Conductor does not call provider APIs, collect provider credentials, store API keys, or run live usage adapters.

1. Storage Model

Usage records are JSON Lines stored locally. The default path is:

Path Format Purpose Git default
.conductor/usage/usage.jsonl JSON Lines Imported usage records. Ignored

The path can be changed with usage_tracking.records_file in .conductor/config.yaml. Runtime usage files should stay untracked unless a human explicitly promotes a redacted summary into a tracked document.

2. Privacy Rules

Usage records must not store:

  • provider API keys, auth tokens, cookies, passwords, credential paths, or secret names;
  • full prompts, private conversation transcripts, or hidden prompts;
  • raw provider billing payloads or raw tool output.

Usage records may store compact accounting metadata: provider, model, token counts, optional cost fields, local task/run ids, timestamps, and the source of the usage data.

3. Usage Record JSONL Format

Each line in .conductor/usage/usage.jsonl is one JSON object.

Field Required Type Notes
schema_version required integer 1 for this schema. Import defaults missing values to 1.
usage_id required string Stable id from the import source.
occurred_at required string UTC ISO-8601 timestamp with Z when known.
provider required string Vendor or local provider label, such as openai, anthropic, or local.
model required string Model or engine label.
source required enum manual_import, agent_reported, adapter_reported, estimated, or unavailable.
task_id optional string or null BACKLOG/Orbit/task-source id, such as TASK-0021.
run_id optional string or null Local run id when known.
input_tokens optional integer or null Prompt/input tokens when reported.
output_tokens optional integer or null Completion/output tokens when reported.
cached_input_tokens optional integer or null Cached input tokens when separately reported.
total_tokens optional integer or null Total tokens. Import computes input_tokens + output_tokens when omitted.
cost_usd optional number or null USD cost when available. Cost is optional because providers differ.
currency optional string Defaults to USD; future imports may preserve other currencies.

Unknown non-sensitive fields may be preserved by future tooling, but credential fields are rejected by import.

Example record:

{"schema_version":1,"usage_id":"use_20260523_001","occurred_at":"2026-05-23T10:00:00Z","provider":"openai","model":"gpt-4.1-mini","source":"manual_import","task_id":"TASK-0021","run_id":"run_TASK-0021","input_tokens":1000,"output_tokens":250,"cached_input_tokens":100,"total_tokens":1250,"cost_usd":0.0125,"currency":"USD"}

4. Manual Import

conductor usage import <file> [--project PATH] imports local JSON or CSV files. It validates every record before writing any output, then appends normalized records to the configured JSONL file.

Accepted JSON shapes:

[
  {
    "usage_id": "use_001",
    "occurred_at": "2026-05-23T10:00:00Z",
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "source": "manual_import",
    "input_tokens": 100,
    "output_tokens": 25
  }
]
{"records":[{"usage_id":"use_001","occurred_at":"2026-05-23T10:00:00Z","provider":"openai","model":"gpt-4.1-mini","source":"manual_import","input_tokens":100,"output_tokens":25}]}

CSV imports use the same field names as headers. Empty optional numeric cells are stored as null.

5. Summary

conductor usage summary [--task TASK-ID] [--project PATH] reads the configured local JSONL file and prints:

  • imported record count;
  • input, output, cached input, and total token sums;
  • optional USD cost sum when present;
  • grouped provider/model totals.

Missing usage files are treated as an empty local state. Malformed JSONL remains an error because the operator needs the filename and line number before trusting the accounting data.

6. Reserved Config Block

Projects may reserve usage-tracking settings in .conductor/config.yaml:

usage_tracking:
  enabled: false
  mode: reserved
  currency: USD
  records_file: .conductor/usage/usage.jsonl
  local_by_default: true
  promotion: explicit_only
  allowed_sources: [manual_import, agent_reported, adapter_reported, estimated, unavailable]
  fields: [input_tokens, output_tokens, cached_input_tokens, total_tokens, cost_usd]
  privacy:
    store_credentials: false
    store_full_prompts: false
    store_raw_provider_payloads: false

enabled: false and mode: reserved mean Conductor does not infer permission to call provider APIs, collect credentials, start adapters, launch agents, or run background services. Manual import is an explicit local file operation.

7. Model Gateway Boundary

Tools such as 9router already own the model-gateway layer: provider routing, OpenAI-compatible proxying, fallback, OAuth/API-key handling, quota tracking, token-saving transforms, request logs, and live usage analytics.

Conductor may later integrate with those tools only at the accounting boundary: import redacted usage summaries, associate them with local task_id or run_id values, and display compact totals. Conductor Core must not store gateway credentials, OAuth tokens, cookies, API keys, request bodies, response bodies, raw prompts, raw tool outputs, or raw provider payloads. It must not become a model router, /v1 proxy, token compressor, provider fallback engine, quota broker, or live billing collector without a later ADR and permission model.