@compaction/cli 0.1.0

package/dist/core/skill-injection-detector.js

@@ -0,0 +1,146 @@
+import { estimateTextTokens } from "./token-estimator.js";
+/**
+ * Report-only skill-injection repetition detector.
+ *
+ * SCOPE (per docs/design/skill-injection-compaction-policy.md, report-only rung):
+ * This module DETECTS and REPORTS repeated byte-identical, same-skill `role:user`
+ * skill injections. It compacts NOTHING. The `repeated_skill_injection` finding
+ * category it produces is intentionally excluded from `getCompactedMessageIds`
+ * (see waste-detector.ts) and from the apply path (policy-middleware.ts), so the
+ * policy is report-only by construction. No message is ever removed, replaced, or
+ * capsuled by this detector.
+ *
+ * The dedup map here is SEPARATE from the tool-output dedup map in `detectWaste`.
+ * An ordinary `role:user`/orchestrator message can never enter this candidate set
+ * because the identification gate requires the literal skill-injection prefix and a
+ * parseable skill name.
+ *
+ * Open questions resolved against a real --include-subagents capture
+ * (ae4dce14-e4ef-4d50-a852-f531fc53b490, 131 injection messages):
+ * - Q5 (threshold reuse): the smallest captured injection body is 1,267 chars / 317 est
+ *   tokens — every body is well above the existing 800-char / 200-token tool-output
+ *   thresholds, so those thresholds are effectively moot for this policy. This detector
+ *   therefore applies no size threshold (full exact-key dedup is the rule).
+ * - Q2 (owning-agent-id recoverability): capture prefixes SUBAGENT message ids
+ *   `agent-<agentId>-<uuid>`, so for the 108 subagent injections the owning agent id IS
+ *   recoverable from `messageId` alone. The 23 ROOT-agent injections (start-cycle,
+ *   complete-cycle, next-cycles) carry a bare UUID with NO agent prefix, so root-agent
+ *   identity is NOT encoded in `messageId`. Report-only does not act on this; at the later
+ *   apply rung a small additive provenance field would be needed to record root-agent
+ *   identity + replaced-position for the bare-UUID copies.
+ */
+const SKILL_INJECTION_PREFIX = "Base directory for this skill:";
+// Matches the skill name in the `.../.claude/skills/<NAME>` path on the first line.
+const SKILL_PATH_PATTERN = /\.claude\/skills\/([A-Za-z0-9._-]+)/;
+const ESTIMATE_LABEL = "estimated (chars/4) trace-token reduction — NOT billing-confirmed, NOT realized savings, NOT yet applied";
+const RECOMMENDATION = "Report-only: no message was compacted. The byte-identical, same-skill skill-injection " +
+    "repetition above is the addressable volume a future approval-required rung could compact. " +
+    "Near-identical (ARGUMENTS-divergent) injections are excluded by construction and are never addressable.";
+export function parseSkillName(content) {
+    const firstLine = content.split("\n", 1)[0] ?? "";
+    const match = firstLine.match(SKILL_PATH_PATTERN);
+    return match ? match[1] : null;
+}
+export function isSkillInjection(message) {
+    return (message.role === "user" &&
+        typeof message.content === "string" &&
+        message.content.startsWith(SKILL_INJECTION_PREFIX) &&
+        parseSkillName(message.content) !== null);
+}
+/**
+ * Normalize for the EXACT (byte-identical) dedup key. Trailing whitespace only is
+ * trimmed (per the design's `normalizeTrailingWhitespace`). Internal whitespace is
+ * preserved so near-identical bodies (divergent trailing `ARGUMENTS:` blocks)
+ * produce DIFFERENT keys and can never be grouped. This is the hard safety boundary.
+ */
+function normalizeExactContent(content) {
+    return content.replace(/\s+$/, "");
+}
+/**
+ * Detect repeated byte-identical, same-skill skill injections.
+ *
+ * Key = `${skillName}:${normalizeExactContent(content)}` — exact, NOT a prefix, NOT fuzzy.
+ * First occurrence of each key is retained; each later exact-key copy is a redundant
+ * byte-identical candidate (the reportable volume). Different normalized content (e.g.
+ * divergent ARGUMENTS) ⇒ different key ⇒ never grouped (near-identical excluded by
+ * construction). Two different skills can never share a key because the key is prefixed
+ * with the parsed skill name.
+ *
+ * REPORT-ONLY: returns findings; never mutates the trace.
+ */
+export function detectSkillInjectionRepetition(trace) {
+    const findings = [];
+    const firstBySkillExactContent = new Map();
+    for (const message of trace.messages) {
+        if (!isSkillInjection(message)) {
+            continue;
+        }
+        const skillName = parseSkillName(message.content);
+        if (skillName === null) {
+            continue;
+        }
+        const key = `${skillName}:${normalizeExactContent(message.content)}`;
+        const firstCopy = firstBySkillExactContent.get(key);
+        if (!firstCopy) {
+            firstBySkillExactContent.set(key, message);
+            continue;
+        }
+        findings.push({
+            category: "repeated_skill_injection",
+            messageIds: [firstCopy.id, message.id],
+            summary: `Repeated byte-identical ${skillName} skill injection. Retain ${firstCopy.id}; ${message.id} is a redundant byte-identical copy (report-only, not compacted).`,
+            estimatedTokens: estimateTextTokens(message.content),
+            skillName,
+            firstCopyMessageId: firstCopy.id,
+            redundantCopyMessageId: message.id
+        });
+    }
+    return findings;
+}
+function countUniqueFirstCopies(trace) {
+    const keys = new Set();
+    for (const message of trace.messages) {
+        if (!isSkillInjection(message)) {
+            continue;
+        }
+        const skillName = parseSkillName(message.content);
+        if (skillName === null) {
+            continue;
+        }
+        keys.add(`${skillName}:${normalizeExactContent(message.content)}`);
+    }
+    return keys.size;
+}
+/**
+ * Build the report-only advisory (per-skill spend attribution + total addressable est).
+ * Pure: derived from the detector findings; nothing is compacted.
+ */
+export function buildSkillInjectionAdvisory(trace) {
+    const findings = detectSkillInjectionRepetition(trace);
+    const bySkill = new Map();
+    let totalTokens = 0;
+    for (const finding of findings) {
+        const bucket = bySkill.get(finding.skillName) ?? {
+            skill_name: finding.skillName,
+            redundant_byte_identical_copies: 0,
+            estimated_tokens: 0,
+            redundant_copy_message_ids: []
+        };
+        bucket.redundant_byte_identical_copies += 1;
+        bucket.estimated_tokens += finding.estimatedTokens;
+        bucket.redundant_copy_message_ids.push(finding.redundantCopyMessageId);
+        bySkill.set(finding.skillName, bucket);
+        totalTokens += finding.estimatedTokens;
+    }
+    const skills = [...bySkill.values()].sort((a, b) => b.estimated_tokens - a.estimated_tokens);
+    return {
+        report_only: true,
+        skills,
+        total_redundant_byte_identical_copies: findings.length,
+        total_addressable_estimated_tokens: totalTokens,
+        first_copy_count: countUniqueFirstCopies(trace),
+        estimate_label: ESTIMATE_LABEL,
+        recommendation: RECOMMENDATION
+    };
+}
+//# sourceMappingURL=skill-injection-detector.js.map

package/dist/core/spend-attribution.d.ts

@@ -0,0 +1,169 @@
+import type { MetadataStatus } from "./openai-agents-capture.js";
+import type { RecommendationMode, RecommendationRiskLevel, RecommendationSafetyStatus } from "../engine/recommendation.js";
+import type { IntegrationWorkflowMetadata } from "../engine/openai-agents-optimization.js";
+import { type UsageMetadata } from "./usage-metadata.js";
+import type { AgentTrace, WasteFinding } from "./types.js";
+/**
+ * Engine-derived optimization-delta inputs for a trace. The PROPRIETARY part of a spend summary:
+ * what a compaction policy would do (policy candidate, post-compaction tokens/cost, the recommendation
+ * verdict, and safety/risk). The FREE local attribution (where spend comes from — by role, tool output,
+ * waste pattern, skill-injection) does NOT depend on any of this and is always computed.
+ *
+ * In the in-repo / API build an engine-backed provider supplies this (see `engineOptimizationDeltaProvider`).
+ * In a public install with the engine excluded, no provider is available and the optimization-delta fields
+ * degrade honestly: `available: false`, no policy candidate, `safety_status: "missing"`, and ZERO synthetic
+ * saving is shown — the formatters print the boundary clause instead of a misleading `$0.000000` saving.
+ */
+export interface TraceOptimizationDelta {
+    available: boolean;
+    policy_candidate: string | null;
+    tokens_after: number;
+    cost_after: number;
+    tokens_saved: number;
+    saving_per_run: number;
+    safety_status: RecommendationSafetyStatus;
+    risk_level: RecommendationRiskLevel;
+    recommendation_mode: RecommendationMode;
+    next_step: string;
+}
+/**
+ * Optional provider that computes the engine-derived {@link TraceOptimizationDelta} for a trace.
+ * Supplied by engine/API callers via lazy import; absent on the free path.
+ */
+export type OptimizationDeltaProvider = (trace: AgentTrace, before: {
+    inputTokens: number;
+    outputTokens: number;
+}, costBefore: number, generatedAt: string) => Promise<TraceOptimizationDelta> | TraceOptimizationDelta;
+/**
+ * Lazily load the proprietary engine and build an OptimizationDeltaProvider from it. Used by the
+ * `spend` CLI command so a real engine build produces the full optimization delta, while a public
+ * install (engine excluded) falls back to {@link unavailableOptimizationDelta} WITHOUT crashing.
+ * Returns `null` when the engine build is absent.
+ */
+export declare function loadEngineOptimizationDeltaProvider(): Promise<OptimizationDeltaProvider | null>;
+export declare const SPEND_ARTIFACT_ROOT = ".compaction/spend";
+export declare const SPEND_LIMITATIONS: readonly ["local estimates only when billing data is unavailable", "token/cost metadata may be partial", "not provider billing data unless explicitly captured", "no auto mode", "no model routing", "no hosted dashboard"];
+type InputKind = "trace" | "optimization_summary" | "recommendation";
+export interface SpendBucket {
+    name: string;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    estimated_cost: number;
+    message_count?: number;
+}
+export interface ToolSpendBucket extends SpendBucket {
+    tool_name: string;
+    repeated_count: number;
+    message_ids: string[];
+}
+export interface WastePatternSpendBucket {
+    pattern: WasteFinding["category"];
+    estimated_tokens: number;
+    estimated_cost: number;
+    finding_count: number;
+    message_ids: string[];
+    summaries: string[];
+}
+export interface PolicyCandidateSpendBucket {
+    policy_name: string;
+    estimated_tokens_saved: number;
+    estimated_saving_per_run: number;
+    percent_reduction: number;
+    safety_status: RecommendationSafetyStatus;
+    risk_level: RecommendationRiskLevel;
+    recommendation_mode: RecommendationMode;
+}
+/**
+ * Per-skill skill-injection spend bucket (report-only). Attributes redundant
+ * byte-identical role:user skill-injection volume by skill. Detection/reporting only —
+ * nothing is compacted. `estimated_tokens` is chars/4, NOT realized savings.
+ */
+export interface SkillInjectionSpendBucket extends SpendBucket {
+    skill_name: string;
+    redundant_byte_identical_copies: number;
+    redundant_copy_message_ids: string[];
+}
+export interface RepeatedContextSegmentSpend {
+    segment_id: string;
+    category: WasteFinding["category"];
+    estimated_tokens: number;
+    estimated_cost: number;
+    message_ids: string[];
+    summary: string;
+}
+export interface SpendSummary {
+    trace_id: string;
+    generated_at: string;
+    integration: string | null;
+    integration_workflow?: IntegrationWorkflowMetadata;
+    token_metadata_status: MetadataStatus;
+    cost_metadata_status: MetadataStatus;
+    usage_metadata: UsageMetadata;
+    spend_confidence: UsageMetadata["cost_confidence"];
+    pricing_assumptions: string[];
+    input_tokens_before: number;
+    input_tokens_after: number;
+    output_tokens_before?: number;
+    output_tokens_after?: number;
+    tokens_saved: number;
+    percent_reduction: number;
+    savings_scope: "policy_level";
+    estimated_cost_before: number;
+    estimated_cost_after: number;
+    estimated_saving_per_run: number;
+    spend_by_role: SpendBucket[];
+    spend_by_tool_output: ToolSpendBucket[];
+    spend_by_repeated_context_segment: RepeatedContextSegmentSpend[];
+    spend_by_waste_pattern: WastePatternSpendBucket[];
+    spend_by_policy_candidate: PolicyCandidateSpendBucket[];
+    /** Report-only: per-skill redundant byte-identical skill-injection spend. Nothing compacted. */
+    spend_by_skill_injection: SkillInjectionSpendBucket[];
+    /** Report-only: total addressable est trace-token volume across skill injections (chars/4). */
+    skill_injection_addressable_estimated_tokens: number;
+    top_waste_patterns: WastePatternSpendBucket[];
+    top_role_category: SpendBucket | null;
+    top_repeated_tool_output: ToolSpendBucket | null;
+    top_waste_pattern: WastePatternSpendBucket | null;
+    top_policy_candidate: PolicyCandidateSpendBucket | null;
+    policy_candidate: string | null;
+    /**
+     * Whether the proprietary optimization-delta engine was available for this summary. When false
+     * (public install, engine excluded) the optimization-delta fields below are NOT engine-computed:
+     * `policy_candidate` is null, `tokens_saved`/`estimated_saving_per_run` are 0 (NOT a real $0 saving
+     * — the formatters print the boundary clause instead), and `safety_status` is `missing`. The FREE
+     * local attribution (spend_by_role / _tool_output / _waste_pattern / _skill_injection) is unaffected.
+     */
+    optimization_delta_available: boolean;
+    safety_status: RecommendationSafetyStatus;
+    risk_level: RecommendationRiskLevel;
+    recommendation_mode: RecommendationMode;
+    approval_status?: string;
+    next_step: string;
+    limitations: string[];
+    source_path: string;
+    input_kind: InputKind;
+}
+export interface SpendArtifacts {
+    summary: SpendSummary;
+    outputDirectory: string;
+    terminalSummary: string;
+    paths: {
+        spendSummaryJsonPath: string;
+        spendSummaryMarkdownPath: string;
+    };
+}
+/**
+ * Build a SpendSummary directly from an in-memory trace, reusing the exact same
+ * attribution computation used by the `spend` CLI command (buildTraceSpendSummary).
+ * Exposed so the compaction report can surface a concise spend-by-source summary
+ * WITHOUT reimplementing attribution logic. Numbers are local estimates (chars/4 /
+ * price-table), NOT billing-confirmed and NOT realized savings.
+ */
+export declare function buildSpendSummaryFromTrace(trace: AgentTrace, generatedAt?: string, integration?: string | null, optimizationDeltaProvider?: OptimizationDeltaProvider): Promise<SpendSummary>;
+export declare function createSpendSummaryFromPath(sourcePath: string, generatedAt?: string, optimizationDeltaProvider?: OptimizationDeltaProvider): Promise<SpendSummary>;
+export declare function formatSpendConsoleSummary(summary: SpendSummary): string;
+export declare function formatSpendMarkdown(summary: SpendSummary): string;
+export declare function writeSpendArtifacts(inputPath: string, outRoot?: string, generatedAt?: string, optimizationDeltaProvider?: OptimizationDeltaProvider): Promise<SpendArtifacts>;
+export declare function defaultSpendPolicyName(): string;
+export {};