Files
stack/packages/plugins/usage-source/transcript/README.md
T

2.3 KiB

Transcript usage source

REQ-LIMIT-4, interface version 1. Enable with "plugins": { "usage-source": ["transcript"] } in the organization file, keeping its other plug-in kinds. Human changes use mosaic plugins set and the current revision. No agent edits the live organization file.

readTurn({ harness, root }) returns {status:'known', entries} or {status:'unknown', code}. Entries map assistant message identities to {input, output, cacheWrite, cacheRead}. This is a snapshot; the bus stores a baseline and computes the turn's new entries. No known new entry means unknown, not zero. The bus attributes records to the bound run/instance/provider/model; the account is null. No token limit or enforcement ships here.

For Pi, root is the run's session directory, or a resumed thread's persistent session directory. JSONL message entries with message.role === 'assistant' have id and message.usage input/output/cacheWrite/cacheRead counters. For Claude Code, root is home/.claude/projects, or the thread's persistent claude-projects directory: one project-directory level, then session JSONL files. Assistant entries have message.id and message.usage input_tokens, output_tokens, cache_creation_input_tokens and cache_read_input_tokens. Claude's absent optional cache fields mean no reported cache usage; missing required input/output is unknown. Duplicate identical identities count once; conflicting counters refuse the snapshot.

The source follows no user symlink: root components and project directories are opened with directory descriptors and O_NOFOLLOW; final opens add O_NONBLOCK. Files must be regular and single-link. Both fstat size and bytes actually read are bounded, and edits during a read refuse the snapshot. Limits: 8 MiB total bytes, 1 MiB per line, 512 directory entries and 20,000 JSON records per snapshot. These are parser resource bounds, not policy token ceilings. Invalid UTF-8, malformed/cut JSONL or invalid counters return unknown, never zero. Reads/logs return no transcript text or parser exception text.

A session can edit its own transcript. Counts are the stack's best reading, not proof. Resumed history present before a run's next turn is excluded by its baseline. Rewriting that baseline makes the turn unknown. Missing data or a source disabled/failed at a restart leaves its pending turn visibly unknown.