@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/_lib/cc_transcript.ts

@@ -0,0 +1,316 @@
+/**
+ * Claude Code transcript reader — replay-dedup, main/subagent classification,
+ * and token-usage aggregation.
+ *
+ * Metric definition (load-bearing — every consumer of this module computes
+ * cost/weight against this, not against `usage.input_tokens` alone):
+ *
+ *     billable_input = input_tokens + cache_read_input_tokens
+ *                       + cache_creation_input_tokens
+ *
+ * Anthropic's `usage.input_tokens` field EXCLUDES cache tokens — it is only
+ * the uncached portion of the prompt. A cost or volume figure built from
+ * `input_tokens` alone silently drops the cache-read and cache-write legs.
+ *
+ * Replay dedup: Claude Code can write the same assistant turn into more than
+ * one transcript file (a resumed/checkpointed session re-persists prior
+ * turns into a new session file; a subagent's own transcript can duplicate
+ * turns also visible from its parent). On this repo's real
+ * `~/.claude/projects/` tree, 50.8% of `type: "assistant"` records with a
+ * `usage` block are such replays — an un-deduped sum overstates real spend
+ * by roughly 2x. `message.id` + `requestId` together are the closest thing
+ * to a stable identity for one real API call.
+ *
+ * Subagent classification: a record is a subagent leg iff its top-level
+ * `agentId` is present, or `isSidechain === true`. Both signals are checked
+ * because subagent transcripts observed under
+ * `<project>/<sessionId>/subagents/agent-*.jsonl` carry both, but a future
+ * or differently-configured transcript could carry only one.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { homedir } from 'node:os';
+
+/** Default base directory holding one subdirectory per Claude Code project. */
+export const DEFAULT_PROJECTS_ROOT = path.join(homedir(), '.claude', 'projects');
+
+export type TranscriptBucket = 'main' | 'subagent';
+
+/** The six token counters every downstream metric (cost, weight, share) is built from. */
+export interface TokenCounts {
+    input_tokens: number;
+    cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
+    output_tokens: number;
+    /** Subset of `cache_creation_input_tokens` written under the 5-minute TTL. */
+    ephemeral_5m_input_tokens: number;
+    /** Subset of `cache_creation_input_tokens` written under the 1-hour TTL. */
+    ephemeral_1h_input_tokens: number;
+}
+
+/** One deduped assistant turn. */
+export interface TranscriptRecord {
+    bucket: TranscriptBucket;
+    agentId: string | null;
+    model: string;
+    /** Raw `timestamp` field from the record, or null when absent. */
+    timestamp: string | null;
+    usage: TokenCounts;
+}
+
+export interface ScanOptions {
+    /** Base directory to walk (default {@link DEFAULT_PROJECTS_ROOT}). Injectable for tests. */
+    root?: string;
+    /**
+     * Restrict the walk to one subdirectory of `root` — either an absolute
+     * path or a name relative to `root` (e.g. the encoded-cwd project dir
+     * `findProjectDir()` style callers already compute). Omit to scan every
+     * project under `root`.
+     */
+    projectDir?: string;
+    /** Skip `.jsonl` files whose mtime is older than this many days. */
+    maxAgeDays?: number;
+    /** Clock used to evaluate `maxAgeDays` — injectable for tests. */
+    now?: Date;
+}
+
+export interface ScanResult {
+    records: TranscriptRecord[];
+    /** Count of `type: "assistant"` + `usage`-bearing lines seen, before dedup. */
+    totalSeen: number;
+    /** `records.length` — the count after dedup. */
+    dedupedCount: number;
+    /** Fraction of seen records that were replays: `(totalSeen - dedupedCount) / totalSeen`. */
+    dedup_ratio: number;
+}
+
+/** Per-bucket rollup: call count, the four raw token sums, the TTL write split, and two derived metrics. */
+export interface BucketAggregate extends TokenCounts {
+    bucket: TranscriptBucket;
+    calls: number;
+    /** `cache_read_input_tokens / billable_input` — 0 when billable_input is 0. */
+    read_share: number;
+    /** Cost-shaped weight: uncached input 1.0x, cache read 0.1x, 5m write 1.25x, 1h write 2.0x. */
+    weighted_input_units: number;
+}
+
+/** `input_tokens + cache_read_input_tokens + cache_creation_input_tokens` — see module doc comment. */
+export function billableInputTokens(u: Pick<TokenCounts, 'input_tokens' | 'cache_read_input_tokens' | 'cache_creation_input_tokens'>): number {
+    return u.input_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens;
+}
+
+/**
+ * Cost-shaped weight across the four input classes. `cache_creation_input_tokens`
+ * that exceeds the known 5m/1h split (older records predating the TTL
+ * breakdown, or a partial breakdown) is treated as a 5m write — Anthropic's
+ * default cache TTL — rather than silently dropped.
+ */
+export function weightedInputUnits(u: TokenCounts): number {
+    const knownSplit = u.ephemeral_5m_input_tokens + u.ephemeral_1h_input_tokens;
+    const unaccounted = Math.max(0, u.cache_creation_input_tokens - knownSplit);
+    return (
+        u.input_tokens * 1.0 +
+        u.cache_read_input_tokens * 0.1 +
+        (u.ephemeral_5m_input_tokens + unaccounted) * 1.25 +
+        u.ephemeral_1h_input_tokens * 2.0
+    );
+}
+
+function numOr0(value: unknown): number {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+interface RawCacheCreation {
+    ephemeral_5m_input_tokens?: unknown;
+    ephemeral_1h_input_tokens?: unknown;
+}
+
+interface RawUsage {
+    input_tokens?: unknown;
+    cache_read_input_tokens?: unknown;
+    cache_creation_input_tokens?: unknown;
+    output_tokens?: unknown;
+    cache_creation?: RawCacheCreation;
+}
+
+interface RawAssistantRecord {
+    type?: unknown;
+    message?: { id?: unknown; model?: unknown; usage?: RawUsage };
+    requestId?: unknown;
+    agentId?: unknown;
+    isSidechain?: unknown;
+    timestamp?: unknown;
+}
+
+function toTokenCounts(raw: RawUsage | undefined): TokenCounts {
+    const cc = raw?.cache_creation ?? {};
+    return {
+        input_tokens: numOr0(raw?.input_tokens),
+        cache_read_input_tokens: numOr0(raw?.cache_read_input_tokens),
+        cache_creation_input_tokens: numOr0(raw?.cache_creation_input_tokens),
+        output_tokens: numOr0(raw?.output_tokens),
+        ephemeral_5m_input_tokens: numOr0(cc.ephemeral_5m_input_tokens),
+        ephemeral_1h_input_tokens: numOr0(cc.ephemeral_1h_input_tokens),
+    };
+}
+
+/** Subagent iff a non-empty top-level `agentId` OR `isSidechain === true` — see module doc comment. */
+function classifyBucket(raw: RawAssistantRecord): TranscriptBucket {
+    const hasAgentId = typeof raw.agentId === 'string' && raw.agentId.length > 0;
+    return hasAgentId || raw.isSidechain === true ? 'subagent' : 'main';
+}
+
+/** `message.id` + `requestId`, NUL-joined so no string content can forge a collision. */
+function dedupKey(raw: RawAssistantRecord): string {
+    const id = typeof raw.message?.id === 'string' ? raw.message.id : '';
+    const reqId = typeof raw.requestId === 'string' ? raw.requestId : '';
+    return `${id}\u0000${reqId}`;
+}
+
+function parseLine(line: string): RawAssistantRecord | null {
+    if (line.trim().length === 0) return null;
+    try {
+        return JSON.parse(line) as RawAssistantRecord;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * List every `*.jsonl` file under `opts.root` (or `opts.root/opts.projectDir`
+ * when given), recursively — this is what makes `<project>/<sessionId>/
+ * subagents/agent-*.jsonl` visible alongside the flat `<project>/*.jsonl`
+ * session files without a second code path.
+ */
+export function listTranscriptFiles(opts: ScanOptions = {}): string[] {
+    const root = opts.root ?? DEFAULT_PROJECTS_ROOT;
+    const base = opts.projectDir
+        ? (path.isAbsolute(opts.projectDir) ? opts.projectDir : path.join(root, opts.projectDir))
+        : root;
+    if (!fs.existsSync(base)) return [];
+
+    const cutoffMs = opts.maxAgeDays !== undefined
+        ? (opts.now ?? new Date()).getTime() - opts.maxAgeDays * 24 * 60 * 60 * 1000
+        : null;
+
+    const out: string[] = [];
+    const stack: string[] = [base];
+    while (stack.length > 0) {
+        const dir = stack.pop() as string;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+            if (cutoffMs !== null) {
+                let mtimeMs: number;
+                try {
+                    mtimeMs = fs.statSync(full).mtimeMs;
+                } catch {
+                    continue;
+                }
+                if (mtimeMs < cutoffMs) continue;
+            }
+            out.push(full);
+        }
+    }
+    return out.sort();
+}
+
+/**
+ * Read every listed transcript file, keep only `type: "assistant"` records
+ * carrying a `usage` block, and dedup by {@link dedupKey}. First occurrence
+ * of a dedup key wins — replays carry the same usage, so occurrence order
+ * has no effect on the aggregated totals.
+ */
+export function scanTranscripts(opts: ScanOptions = {}): ScanResult {
+    const files = listTranscriptFiles(opts);
+    const seen = new Set<string>();
+    const records: TranscriptRecord[] = [];
+    let totalSeen = 0;
+
+    for (const file of files) {
+        let text: string;
+        try {
+            text = fs.readFileSync(file, 'utf-8');
+        } catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const raw = parseLine(line);
+            if (!raw || raw.type !== 'assistant' || !raw.message?.usage) continue;
+
+            totalSeen += 1;
+            const key = dedupKey(raw);
+            if (seen.has(key)) continue;
+            seen.add(key);
+
+            records.push({
+                bucket: classifyBucket(raw),
+                agentId: typeof raw.agentId === 'string' ? raw.agentId : null,
+                model: typeof raw.message.model === 'string' ? raw.message.model : 'unknown',
+                timestamp: typeof raw.timestamp === 'string' ? raw.timestamp : null,
+                usage: toTokenCounts(raw.message.usage),
+            });
+        }
+    }
+
+    const dedupedCount = records.length;
+    return {
+        records,
+        totalSeen,
+        dedupedCount,
+        dedup_ratio: totalSeen > 0 ? (totalSeen - dedupedCount) / totalSeen : 0,
+    };
+}
+
+function emptyAggregate(bucket: TranscriptBucket): BucketAggregate {
+    return {
+        bucket,
+        calls: 0,
+        input_tokens: 0,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+        output_tokens: 0,
+        ephemeral_5m_input_tokens: 0,
+        ephemeral_1h_input_tokens: 0,
+        read_share: 0,
+        weighted_input_units: 0,
+    };
+}
+
+/** Roll deduped records up into a `main` / `subagent` pair of {@link BucketAggregate}. */
+export function aggregateByBucket(records: readonly TranscriptRecord[]): Record<TranscriptBucket, BucketAggregate> {
+    const buckets: Record<TranscriptBucket, BucketAggregate> = {
+        main: emptyAggregate('main'),
+        subagent: emptyAggregate('subagent'),
+    };
+
+    for (const rec of records) {
+        const agg = buckets[rec.bucket];
+        agg.calls += 1;
+        agg.input_tokens += rec.usage.input_tokens;
+        agg.cache_read_input_tokens += rec.usage.cache_read_input_tokens;
+        agg.cache_creation_input_tokens += rec.usage.cache_creation_input_tokens;
+        agg.output_tokens += rec.usage.output_tokens;
+        agg.ephemeral_5m_input_tokens += rec.usage.ephemeral_5m_input_tokens;
+        agg.ephemeral_1h_input_tokens += rec.usage.ephemeral_1h_input_tokens;
+    }
+
+    for (const bucket of Object.values(buckets)) {
+        const billable = billableInputTokens(bucket);
+        bucket.read_share = billable > 0 ? bucket.cache_read_input_tokens / billable : 0;
+        bucket.weighted_input_units = weightedInputUnits(bucket);
+    }
+
+    return buckets;
+}

package/src/scripts/_lib/compile_time_toggles.ts

@@ -0,0 +1,79 @@
+/**
+ * Compile-time rule toggles — the single definition, shared by the router compiler
+ * and the projector.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The map used to live only in `compile_router.ts`, which meant a disabled rule was
+ * dropped from `dist/router.json` while its **body still shipped** as a file in
+ * `dist/agent-src/rules/` (and through the `.claude/rules/` symlink). ADR
+ * `telegraph/0002` originally claimed that flipping the toggle gave "zero-cost
+ * dormancy". That was measured and found half wrong on 2026-07-29: the router entry
+ * governs *trigger-routing*; **file existence governs always-loaded injection**, and
+ * the host reads the file — a maintainer session's context listed the body verbatim
+ * as "project instructions", never having consulted the router.
+ *
+ * Two surfaces, one switch. Sharing the definition is what lets the projector honour
+ * it, so `speak: false` means what the ADR assumed instead of the ADR being weakened
+ * to match a partial implementation.
+ */
+
+/**
+ * HOW A RULE GETS HERE — the dormancy routing (road-to-cache-economy Phase 3)
+ * --------------------------------------------------------------------------
+ * A rule body is re-written on EVERY subagent spawn, so an always-loaded rule
+ * that is not earning its keep is paid per spawn, not once. That makes "should
+ * this rule be dormant?" a real question — and this map is the ONLY place the
+ * answer may land. The route, in order:
+ *
+ *   1. **Candidate** — `preamble_byte_census` ranks always-loaded rules by
+ *      per-spawn token cost (`--top`). A candidate is a number, never an
+ *      impression: telegraph-speak was ~982 tokens.
+ *   2. **Evidence** — the same bar telegraph-speak had to clear: an output-side
+ *      bench showing the rule does not pay for itself, judged against the
+ *      kill-criterion, BEFORE dormancy. A preference is not evidence, and
+ *      "it looks verbose" is not a measurement.
+ *   3. **Landing** — a new entry in the map below, keyed on a real setting the
+ *      consumer can flip back. Never a fifth toggle axis: this predicate already
+ *      has four consumers (the router compiler, the dist writer, `check_sync`,
+ *      and the per-tool symlink generator), and a rule wired into three of four
+ *      is how the last attempt blocked its own push.
+ *
+ * What is explicitly NOT this route: dropping a rule from the router while its
+ * body still ships (that was the measured half-truth this file exists to fix),
+ * and gating bodies behind triggers wholesale — that is thin projection, which
+ * failed a 48% quality floor at 36.2% and stays disabled.
+ */
+
+/** Loose settings shape — the toggles only ever read nested plain objects. */
+export type ToggleSettings = Record<string, unknown>;
+
+/** rule-id → predicate. A rule is emitted (router AND projection) only when its
+ * predicate returns true. A rule absent from this map is always emitted. */
+export const COMPILE_TIME_TOGGLES: Record<string, (s: ToggleSettings) => boolean> = {
+    // `speak` defaults FALSE (dormant) per docs/adrs/telegraph/0002 — the absent-key
+    // fallback used to be `true`, which silently contradicted ADR 0001 (accepted,
+    // "default off until bench"). Measured basis: median vs_terse −9.27% (API) /
+    // −5.47% (exact cl100k_base) — telegraph emits MORE than a plain "be terse".
+    // Opt back in with an explicit `telegraph.speak: true` once an output-side bench
+    // clears the kill-criterion bar. `enabled` keeps its true default: it is the
+    // family master switch, and flipping it would silence sibling telegraph settings
+    // that were never measured negative.
+    //
+    // This predicate deliberately does NOT read `speak_scope`. That key disables the
+    // rule's *behaviour* and never removed its token cost — the trap the measurement
+    // exposed.
+    'telegraph-speak': (s: ToggleSettings): boolean => {
+        const tg = (s['telegraph'] as ToggleSettings | undefined) ?? {};
+        const enabled = tg['enabled'] === undefined ? true : tg['enabled'];
+        const speak = tg['speak'] === undefined ? false : tg['speak'];
+        return Boolean(enabled) && Boolean(speak);
+    },
+};
+
+/** True when the rule may be emitted. Unknown ids are always emitted — the map is an
+ * opt-in list of gated rules, never an allowlist of permitted ones. */
+export function rule_is_compile_enabled(rule_id: string, settings: ToggleSettings): boolean {
+    const predicate = COMPILE_TIME_TOGGLES[rule_id];
+    return predicate === undefined ? true : predicate(settings);
+}

package/src/scripts/_lib/confusables.ts

@@ -0,0 +1,101 @@
+/**
+ * Visible mixed-script confusable signature — the ONE definition in the tree.
+ *
+ * Extracted from `lint_confusables.ts` so the authoring-time linter and the
+ * runtime encoding scanner share one table and one decision rule
+ * (road-to-runtime-encoding-hardening Phase 3). Two copies of a confusable set
+ * is exactly the drift this extraction prevents: a codepoint added to one and
+ * not the other means the two surfaces disagree about what a homoglyph is.
+ *
+ * The dependency direction matters. This module imports NOTHING — no `fs`, no
+ * lint framework — so the runtime retrieval path can use it without pulling the
+ * authoring-time lint infrastructure into a request.
+ */
+
+/** A token needs this many letters before the signature can fire. */
+export const MIN_LETTERS = 3;
+
+// Unicode-script classifiers via property escapes (requires the `u` flag).
+const _LATIN = /\p{Script=Latin}/u;
+const _CYRILLIC = /\p{Script=Cyrillic}/u;
+const _GREEK = /\p{Script=Greek}/u;
+const _LETTER = /\p{L}/u;
+
+/** A "token" is a maximal run of letters / combining marks / decimal digits. */
+export const TOKEN_RE = /[\p{L}\p{M}\p{Nd}]+/gu;
+
+/**
+ * Cyrillic + Greek codepoints that have a basic-Latin lookalike (Unicode TR39
+ * confusables, common subset). A foreign letter only counts toward the
+ * confusable signal when it is in this set — Greek math operators with no Latin
+ * twin (Δ Σ Π Ω Φ Θ Λ Ξ Ψ Γ δ π ω …) are deliberately excluded so legit
+ * notation does not false-positive.
+ */
+export const CONFUSABLE_FOREIGN: ReadonlySet<number> = new Set([
+    // Cyrillic lowercase ↔ Latin
+    0x0430 /*а→a*/, 0x0435 /*е→e*/, 0x043e /*о→o*/, 0x0440 /*р→p*/, 0x0441 /*с→c*/,
+    0x0443 /*у→y*/, 0x0445 /*х→x*/, 0x0455 /*ѕ→s*/, 0x0456 /*і→i*/, 0x0458 /*ј→j*/,
+    0x04bb /*һ→h*/, 0x0501 /*ԁ→d*/, 0x051b /*ԛ→q*/, 0x0577 /*no*/,
+    // Cyrillic uppercase ↔ Latin
+    0x0410 /*А→A*/, 0x0412 /*В→B*/, 0x0415 /*Е→E*/, 0x041a /*К→K*/, 0x041c /*М→M*/,
+    0x041d /*Н→H*/, 0x041e /*О→O*/, 0x0420 /*Р→P*/, 0x0421 /*С→C*/, 0x0422 /*Т→T*/,
+    0x0423 /*У→Y*/, 0x0425 /*Х→X*/, 0x0405 /*Ѕ→S*/, 0x0406 /*І→I*/, 0x0408 /*Ј→J*/,
+    // Greek lowercase ↔ Latin
+    0x03b1 /*α→a*/, 0x03b5 /*ε→e*/, 0x03bf /*ο→o*/, 0x03bd /*ν→v*/, 0x03c1 /*ρ→p*/,
+    0x03c5 /*υ→u*/, 0x03c7 /*χ→x*/, 0x03ba /*κ→k*/,
+    // Greek uppercase ↔ Latin (only those with a real Latin twin)
+    0x0391 /*Α→A*/, 0x0392 /*Β→B*/, 0x0395 /*Ε→E*/, 0x0396 /*Ζ→Z*/, 0x0397 /*Η→H*/,
+    0x0399 /*Ι→I*/, 0x039a /*Κ→K*/, 0x039c /*Μ→M*/, 0x039d /*Ν→N*/, 0x039f /*Ο→O*/,
+    0x03a1 /*Ρ→P*/, 0x03a4 /*Τ→T*/, 0x03a5 /*Υ→Y*/, 0x03a7 /*Χ→X*/, 0x0392 /*Β→B*/,
+]);
+
+type ScriptName = 'latin' | 'cyrillic' | 'greek' | 'other';
+
+function _script_of(ch: string): ScriptName {
+    if (_LATIN.test(ch)) return 'latin';
+    if (_CYRILLIC.test(ch)) return 'cyrillic';
+    if (_GREEK.test(ch)) return 'greek';
+    return 'other';
+}
+
+/**
+ * Classify a single token. Returns the offending mixed-script descriptor when
+ * the token matches the homoglyph signature, else null.
+ *
+ * The containment rules are the load-bearing part, and they are why this is one
+ * shared function rather than two similar ones: a Latin-majority token with at
+ * least one TR39-confusable foreign letter is the signal; a single-script token
+ * (a genuine Cyrillic or Greek word) is not; and a token whose foreign letters
+ * outnumber its Latin ones is a foreign word, not an attack.
+ */
+export function classifyToken(token: string): string | null {
+    let latin = 0;
+    let cyrillic = 0;
+    let greek = 0;
+    let letters = 0;
+    for (const ch of token) {
+        if (!_LETTER.test(ch)) continue; // skip combining marks / digits for script vote
+        letters += 1;
+        const script = _script_of(ch);
+        if (script === 'latin') {
+            latin += 1;
+        } else if (script === 'cyrillic' || script === 'greek') {
+            // Only confusable foreign letters (TR39) count — math operators with
+            // no Latin twin are ignored, so legit notation never trips.
+            if (CONFUSABLE_FOREIGN.has(ch.codePointAt(0) as number)) {
+                if (script === 'cyrillic') cyrillic += 1;
+                else greek += 1;
+            }
+        }
+    }
+    if (letters < MIN_LETTERS) return null;
+    const foreign = cyrillic + greek;
+    if (latin === 0 || foreign === 0) return null; // single-script (or no Latin) → legit
+    if (latin <= foreign) return null; // majority must be Latin (foreign word ≠ attack)
+    const which = cyrillic > 0 && greek > 0
+        ? 'cyrillic+greek'
+        : cyrillic > 0
+            ? 'cyrillic'
+            : 'greek';
+    return `latin+${which} (${latin} latin / ${foreign} foreign-confusable)`;
+}