@agent-finops/core 0.9.6 → 0.9.8

package/dist/localAgentLogs.js

@@ -228,6 +228,20 @@ function parseClaudeFinancialUsage(value, onDiagnostic) {
     const write1hField = cacheCreation
         ? optionalTokenComponent(cacheCreation, "ephemeral_1h_input_tokens")
         : { present: false };
+    const writeTotal = writeTotalField.value;
+    let write5m = write5mField.value;
+    let write1h = write1hField.value;
+    const writeSplitConsistent = writeTotal === undefined || ((write5m === undefined || write5m <= writeTotal) &&
+        (write1h === undefined || write1h <= writeTotal) &&
+        (write5m === undefined || write1h === undefined || write5m + write1h === writeTotal));
+    // A total plus one disjoint duration determines the other duration. Never
+    // add the entire total to the supplied duration or invent a negative split.
+    if (writeTotal !== undefined && writeSplitConsistent) {
+        if (write5m === undefined && write1h !== undefined)
+            write5m = writeTotal - write1h;
+        else if (write1h === undefined && write5m !== undefined)
+            write1h = writeTotal - write5m;
+    }
     const componentsSupported = inputTokens !== undefined &&
         outputTokens !== undefined &&
         (!cacheReadField.present || cacheReadField.value !== undefined) &&
@@ -235,16 +249,18 @@ function parseClaudeFinancialUsage(value, onDiagnostic) {
         (!reportedTotalField.present || reportedTotalField.value !== undefined) &&
         (!cacheCreationPresent || Boolean(cacheCreation)) &&
         (!write5mField.present || write5mField.value !== undefined) &&
-        (!write1hField.present || write1hField.value !== undefined);
+        (!write1hField.present || write1hField.value !== undefined) &&
+        writeSplitConsistent;
     const usage = {
         // Retain every valid component for partial evidence, but never let a
         // missing/invalid required field become a priceable zero-dollar call.
         inputTokens: inputTokens ?? 0,
         outputTokens: outputTokens ?? 0,
         cacheReadTokens: cacheReadField.value ?? 0,
-        // Prefer the 5m/1h breakdown; fall back to the total as 5m (cheaper bound).
-        cacheWrite5mTokens: write5mField.value ?? writeTotalField.value ?? 0,
-        cacheWrite1hTokens: write1hField.value ?? 0
+        // With no duration split at all, keep the existing cheaper-bound estimate.
+        // Partial evidence without a total remains partial, never a complete sum.
+        cacheWrite5mTokens: write5m ?? (write1h === undefined ? writeTotal : undefined) ?? 0,
+        cacheWrite1hTokens: write1h ?? 0
     };
     if (componentsSupported) {
         const cacheWriteEvidence = writeTotalField.value !== undefined ||
@@ -1327,6 +1343,11 @@ export async function loadLocalAgentFinancialUsage(options = {}) {
 /** Registry-driven financial-only engine; package-root exports stay unchanged. */
 export async function loadLocalAgentFinancialUsageWithFormats(registry, options = {}) {
     validateLocalAgentFormatDescriptors(registry.map((entry) => entry.descriptor));
+    // Cumulative financial caches cannot supply event-day deltas. Keep their semantics unchanged.
+    if (options.workspaceDailyFacts) {
+        options = { ...options, financialIndex: undefined };
+        registry = registry.filter(runtime => runtime.descriptor.id === "claude-code" || runtime.descriptor.id === "codex");
+    }
     const home = homedir();
     const since = options.sinceIso ? Date.parse(options.sinceIso) : undefined;
     const sinceMs = typeof since === "number" && Number.isFinite(since) ? since : undefined;
@@ -1401,12 +1422,12 @@ export async function loadLocalAgentFinancialUsageWithFormats(registry, options
             const diagnosticsBefore = diagnostics.length;
             const unreadableBefore = scan.unreadableFiles;
             const filesParsedBefore = scan.filesParsed;
-            const parsedCalls = await runtime.parseFinancialFile({
-                filePath: file,
-                sinceMs,
-                scan,
-                diagnostics
-            });
+            const context = { filePath: file, sinceMs, scan, diagnostics };
+            const parsedCalls = options.workspaceDailyFacts && descriptor.id === "codex"
+                ? await readCodexDailyFinancialFile(context)
+                : options.workspaceDailyFacts && descriptor.id === "claude-code"
+                    ? await readClaudeCodeFinancialFileForRegistry(context, true)
+                    : await runtime.parseFinancialFile(context);
             assertFormatCallOwnership(descriptor, parsedCalls);
             assertFinancialSourceOwnership(descriptor, scan, diagnostics);
             calls.push(...parsedCalls);
@@ -1588,7 +1609,7 @@ function codexHeaderAttribution(header) {
     };
 }
 /** @internal Runtime hook owned by the Claude Code registry entry. */
-export async function readClaudeCodeFinancialFileForRegistry(context) {
+export async function readClaudeCodeFinancialFileForRegistry(context, workspaceDailyFacts = false) {
     const { filePath, sinceMs, scan, diagnostics } = context;
     if (!await shouldStreamFile(filePath, sinceMs, "claude-code", scan, diagnostics)) {
         return [];
@@ -1604,8 +1625,16 @@ export async function readClaudeCodeFinancialFileForRegistry(context) {
             // file so a narrow-window run can never truncate a wider one. The
             // loader's final timestamp filter performs all narrowing.
             undefined, seen, (diagnostic) => fileDiagnostics.push(diagnostic));
-            if (call)
+            if (call) {
+                if (workspaceDailyFacts) {
+                    const nativeAgent = stringOf(entry.agentId);
+                    const pathAgent = filePath.split(sep).includes("subagents")
+                        ? basename(filePath).match(/^agent-([A-Za-z0-9_-]+)\.jsonl$/)?.[1] : undefined;
+                    if (nativeAgent || pathAgent)
+                        call.subagentId = nativeAgent ?? pathAgent;
+                }
                 calls.push(call);
+            }
         });
     }
     catch (error) {
@@ -1668,6 +1697,77 @@ export async function readCodexFinancialFileForRegistry(context) {
     });
     return call ? [call] : [];
 }
+/** Workspace-only event deltas. The existing snapshot reader remains cumulative. */
+async function readCodexDailyFinancialFile(context) {
+    const { filePath, sinceMs, scan, diagnostics } = context;
+    if (!await shouldStreamFile(filePath, sinceMs, "codex", scan, diagnostics))
+        return [];
+    const state = createCodexFinancialStreamState(), calls = [];
+    const report = () => recordParseDiagnostic("codex", scan, diagnostics, { code: "unsupported_token_shape", count: 1 });
+    let priorEventAt;
+    try {
+        const streamed = await streamJsonlRecords(filePath, entry => {
+            const payload = isRecord(entry.payload) ? entry.payload : undefined;
+            const previousTotal = state.lastTotal ?? state.inheritedUsageBaseline;
+            consumeCodexFinancialEntry(state, entry);
+            if (entry.type !== "event_msg" || payload?.type !== "token_count"
+                || state.hasInheritedHistory && !state.rootTaskStarted)
+                return;
+            const info = isRecord(payload.info) ? payload.info : undefined;
+            const total = info && isRecord(info.total_token_usage) ? info.total_token_usage : undefined;
+            if (!total) {
+                // A usage-bearing event without its cumulative endpoint cannot be
+                // placed safely: a later counter may span this event's UTC day.
+                if (info && isRecord(info.last_token_usage))
+                    report();
+                return;
+            }
+            const timestamp = toIso(stringOf(entry.timestamp));
+            if (!timestamp || !state.sessionId) {
+                report();
+                return;
+            }
+            const parsed = parseCodexCumulativeUsage(total, previousTotal);
+            // Missing initial history cannot be assigned to a later day. A changed or
+            // decreasing counter remains unknown at that event; the next exact pair
+            // can establish a delta without pretending the reset was a zero.
+            const firstDayKnown = !!previousTotal || !!state.startedAt && state.startedAt.slice(0, 10) === timestamp.slice(0, 10);
+            const chronological = !priorEventAt || timestamp >= priorEventAt;
+            const cachedShapeStable = !previousTotal ||
+                Object.hasOwn(total, "cached_input_tokens") === Object.hasOwn(previousTotal, "cached_input_tokens");
+            const supported = parsed.supported && firstDayKnown && chronological && cachedShapeStable;
+            priorEventAt = timestamp;
+            if (supported && previousTotal && parsed.usage.inputTokens === 0 && parsed.usage.outputTokens === 0
+                && (parsed.usage.cacheReadTokens ?? 0) === 0 && (parsed.reportedTotalTokens ?? 0) === 0)
+                return;
+            if (!supported)
+                report();
+            const workingDirectory = absoluteWorkingDirectory(state.rootCwd);
+            // The cumulative endpoint fingerprint is stable across copies of a
+            // rollout. Different deltas for that same endpoint become a conflict in
+            // dedupeCumulativeSessionCalls rather than two financial contributions.
+            const callId = `callref_${createHash("sha256").update("codex-workspace-counter-event-v1\0")
+                .update(JSON.stringify([state.sessionId, timestamp, total.input_tokens ?? null,
+                total.output_tokens ?? null, total.cached_input_tokens ?? null, total.total_tokens ?? null])).digest("hex")}`;
+            calls.push({ agent: "codex", sessionId: state.sessionId, callId,
+                model: state.model ?? "codex", timestamp, startedAt: timestamp,
+                project: projectFromCwd(workingDirectory), workingDirectory,
+                usageScope: "turn", usageSupport: supported ? "complete" : "unsupported_token_shape",
+                usage: parsed.usage,
+                ...(supported && parsed.tokenComponentEvidence ? { tokenComponentEvidence: parsed.tokenComponentEvidence } : {}),
+                ...(parsed.reportedTotalTokens !== undefined ? { reportedTotalTokens: parsed.reportedTotalTokens } : {}) });
+        });
+        if (streamed.hadContent)
+            scan.filesParsed++;
+        if (streamed.malformedLines)
+            recordParseDiagnostic("codex", scan, diagnostics, { code: "malformed_jsonl", count: streamed.malformedLines });
+        return calls;
+    }
+    catch (error) {
+        recordUnreadableFile("codex", scan, diagnostics, error);
+        return [];
+    }
+}
 /** @internal Runtime hook owned by the Gemini CLI registry entry. */
 export async function readGeminiFinancialFileForRegistry(context) {
     const { filePath, sinceMs, scan, diagnostics } = context;

package/dist/modelPricing.js

@@ -10,6 +10,9 @@
 export const PRICING_TABLE_AS_OF = "2026-08-25";
 const pricingRules = [
     // Anthropic
+    // Reviewed 2026-09-20: platform.claude.com/docs/en/about-claude/pricing.
+    // Fable/Mythos 5.1 keep base/write rates; cache reads are $0.25 per MTok.
+    { match: /^claude-(?:fable|mythos)-5-1$/i, inputPerM: 10, outputPerM: 50, cacheReadPerM: 0.25 },
     { match: /^claude-fable-5/i, inputPerM: 10, outputPerM: 50 },
     { match: /^claude-mythos-5/i, inputPerM: 10, outputPerM: 50 },
     { match: /^claude-opus-5/i, inputPerM: 5, outputPerM: 25 },

package/dist/planMath.js

@@ -1,3 +1,15 @@
+import { safeUntrustedLabel, WITHHELD_ENTITY_LABEL, WITHHELD_PLAN_LABEL } from "./untrustedLabel.js";
+/**
+ * The plan label and the limit signal are read out of the agent's own local
+ * config files, so both are untrusted text that lands mid-sentence in a
+ * headline the readout, the report and `doctor` all print verbatim.
+ */
+function safePlanLabel(value) {
+    return safeUntrustedLabel(value, WITHHELD_PLAN_LABEL);
+}
+function safeLimitSignal(value) {
+    return safeUntrustedLabel(value, WITHHELD_ENTITY_LABEL);
+}
 export const subscriptionPlans = [
     { id: "claude-pro", provider: "anthropic", agent: "claude-code", name: "Claude Pro", monthlyUsd: 20, coversUpToUsd: 50 },
     { id: "claude-max-5x", provider: "anthropic", agent: "claude-code", name: "Claude Max 5x", monthlyUsd: 100, coversUpToUsd: 250 },
@@ -61,21 +73,21 @@ export function computePlanChecks(records, detectedPlans = []) {
                 const nextTier = subscriptionPlans.find((plan) => plan.agent === agent && plan.coversUpToUsd > detectedKnown.coversUpToUsd);
                 // A local limit signal upgrades "might hit limits" to hard evidence.
                 const evidence = detected?.limitSignal
-                    ? `local metadata reports ${detected.limitSignal}`
+                    ? `local metadata reports ${safeLimitSignal(detected.limitSignal)}`
                     : `if the provider reports active rate limits`;
                 upgradeHint = nextTier
                     ? `API-equivalent projection exceeds the rough ${detectedKnown.name} comparison threshold (~$${detectedKnown.coversUpToUsd}/mo); ${evidence}. ${nextTier.name} ($${nextTier.monthlyUsd}/mo) is the next listed tier, but verify account limits before changing plans; trimming context (below) may buy headroom.`
                     : `API-equivalent projection exceeds the rough ${detectedKnown.name} comparison threshold (~$${detectedKnown.coversUpToUsd}/mo); verify account limits before changing plans. Trimming context (below) may buy headroom.`;
             }
             else if (detected?.limitSignal) {
-                upgradeHint = `local metadata reports ${detected.limitSignal}; verify the live provider window. Trimming context (below) may buy headroom.`;
+                upgradeHint = `local metadata reports ${safeLimitSignal(detected.limitSignal)}; verify the live provider window. Trimming context (below) may buy headroom.`;
             }
         }
         else if (detected) {
             // Detected a plan we can't price (e.g. an unrecognized tier): state the
             // fact, then fall back to suggestion math without pretending certainty.
             headline =
-                `${agent}: ~${formatUsd(monthly)}/mo at API rates (${basis}) — compared with ${detected.planLabel} ` +
+                `${agent}: ~${formatUsd(monthly)}/mo at API rates (${basis}) — compared with ${safePlanLabel(detected.planLabel)} ` +
                     `(label detected locally; price not in our table)` +
                     (suggested ? `; reference listed plan: ${suggested.name} ($${suggested.monthlyUsd}/mo).` : `.`);
         }
@@ -100,7 +112,16 @@ export function computePlanChecks(records, detectedPlans = []) {
             suggestedPlan: detectedKnown ?? suggested,
             monthlySavingsVsApiUsd: effectiveSavings,
             valueMultiple,
-            detectedPlan: detected,
+            // The STRUCTURED sibling of the headline. Neutralizing the sentence and
+            // shipping the raw label beside it in the same object is the inversion
+            // that let a hostile name reach an agent while the human saw a redaction.
+            detectedPlan: detected === undefined ? undefined : {
+                ...detected,
+                planLabel: safePlanLabel(detected.planLabel),
+                ...(detected.limitSignal === undefined
+                    ? {}
+                    : { limitSignal: safeLimitSignal(detected.limitSignal) })
+            },
             upgradeHint,
             headline
         });

package/dist/projectIndexStore.d.ts

@@ -112,9 +112,9 @@ declare const documentSchema: z.ZodObject<{
                         not_separately_reported: "not_separately_reported";
                     }>;
                     cacheWriteTokens: z.ZodEnum<{
-                        partial: "partial";
                         observed: "observed";
                         not_separately_reported: "not_separately_reported";
+                        partial: "partial";
                     }>;
                     thoughtTokens: z.ZodEnum<{
                         observed: "observed";
@@ -129,8 +129,8 @@ declare const documentSchema: z.ZodObject<{
                         calculated_partial: "calculated_partial";
                     }>;
                     reportedTotalTokens: z.ZodEnum<{
-                        not_reported: "not_reported";
                         provider_reported: "provider_reported";
+                        not_reported: "not_reported";
                     }>;
                 }, z.core.$strict>>;
                 sourceVersion: z.ZodOptional<z.ZodString>;
@@ -189,9 +189,9 @@ declare const documentSchema: z.ZodObject<{
                 activity: z.ZodOptional<z.ZodObject<{
                     summary: z.ZodString;
                     kind: z.ZodEnum<{
-                        file: "file";
-                        agent: "agent";
                         project: "project";
+                        agent: "agent";
+                        file: "file";
                         task: "task";
                         automation: "automation";
                     }>;
@@ -331,9 +331,9 @@ declare const documentSchema: z.ZodObject<{
                         not_separately_reported: "not_separately_reported";
                     }>;
                     cacheWriteTokens: z.ZodEnum<{
-                        partial: "partial";
                         observed: "observed";
                         not_separately_reported: "not_separately_reported";
+                        partial: "partial";
                     }>;
                     thoughtTokens: z.ZodEnum<{
                         observed: "observed";
@@ -348,8 +348,8 @@ declare const documentSchema: z.ZodObject<{
                         calculated_partial: "calculated_partial";
                     }>;
                     reportedTotalTokens: z.ZodEnum<{
-                        not_reported: "not_reported";
                         provider_reported: "provider_reported";
+                        not_reported: "not_reported";
                     }>;
                 }, z.core.$strict>>;
                 sourceVersion: z.ZodOptional<z.ZodString>;
@@ -408,9 +408,9 @@ declare const documentSchema: z.ZodObject<{
                 activity: z.ZodOptional<z.ZodObject<{
                     summary: z.ZodString;
                     kind: z.ZodEnum<{
-                        file: "file";
-                        agent: "agent";
                         project: "project";
+                        agent: "agent";
+                        file: "file";
                         task: "task";
                         automation: "automation";
                     }>;

package/dist/qualitativeIndexCache.d.ts

@@ -83,9 +83,9 @@ declare const valueSchema: z.ZodObject<{
                 not_separately_reported: "not_separately_reported";
             }>;
             cacheWriteTokens: z.ZodEnum<{
-                partial: "partial";
                 observed: "observed";
                 not_separately_reported: "not_separately_reported";
+                partial: "partial";
             }>;
             thoughtTokens: z.ZodEnum<{
                 observed: "observed";
@@ -100,8 +100,8 @@ declare const valueSchema: z.ZodObject<{
                 calculated_partial: "calculated_partial";
             }>;
             reportedTotalTokens: z.ZodEnum<{
-                not_reported: "not_reported";
                 provider_reported: "provider_reported";
+                not_reported: "not_reported";
             }>;
         }, z.core.$strict>>;
         sourceVersion: z.ZodOptional<z.ZodString>;
@@ -160,9 +160,9 @@ declare const valueSchema: z.ZodObject<{
         activity: z.ZodOptional<z.ZodObject<{
             summary: z.ZodString;
             kind: z.ZodEnum<{
-                file: "file";
-                agent: "agent";
                 project: "project";
+                agent: "agent";
+                file: "file";
                 task: "task";
                 automation: "automation";
             }>;
@@ -309,9 +309,9 @@ export declare const qualitativeEntryValueSchema: z.ZodObject<{
                 not_separately_reported: "not_separately_reported";
             }>;
             cacheWriteTokens: z.ZodEnum<{
-                partial: "partial";
                 observed: "observed";
                 not_separately_reported: "not_separately_reported";
+                partial: "partial";
             }>;
             thoughtTokens: z.ZodEnum<{
                 observed: "observed";
@@ -326,8 +326,8 @@ export declare const qualitativeEntryValueSchema: z.ZodObject<{
                 calculated_partial: "calculated_partial";
             }>;
             reportedTotalTokens: z.ZodEnum<{
-                not_reported: "not_reported";
                 provider_reported: "provider_reported";
+                not_reported: "not_reported";
             }>;
         }, z.core.$strict>>;
         sourceVersion: z.ZodOptional<z.ZodString>;
@@ -386,9 +386,9 @@ export declare const qualitativeEntryValueSchema: z.ZodObject<{
         activity: z.ZodOptional<z.ZodObject<{
             summary: z.ZodString;
             kind: z.ZodEnum<{
-                file: "file";
-                agent: "agent";
                 project: "project";
+                agent: "agent";
+                file: "file";
                 task: "task";
                 automation: "automation";
             }>;

package/dist/toolInvocations.js

@@ -1,6 +1,7 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { homedir } from "node:os";
+import { safeUntrustedLabel, WITHHELD_FILE_LABEL } from "./untrustedLabel.js";
 /** Parse ONE transcript's content. Exported for tests. Returns the per-file pieces the aggregator needs. */
 export function parseClaudeCodeInvocations(content, sinceMs) {
     const counts = new Map();
@@ -605,8 +606,15 @@ function explicitReadFile(toolName, input) {
     return name && name !== "." && name !== "/" ? name : undefined;
 }
 function buildSessionContextSignal(input) {
+    // File names come off transcript tool-call metadata, so they are untrusted,
+    // and they travel as DATA rather than prose: {name, count} objects that the
+    // MCP tools hand to an agent verbatim. Neutralizing the sentence built from
+    // this array while the array itself stayed raw gave the human the redaction
+    // and the agent the payload — backwards, on the one surface where injected
+    // text can actually steer a coding agent. Neutralize at the source, so every
+    // consumer (Glance, MCP, CLI, the action planner) gets the same safe name.
     const fileReads = [...input.fileReads.entries()]
-        .map(([name, count]) => ({ name, count }))
+        .map(([name, count]) => ({ name: safeUntrustedLabel(name, WITHHELD_FILE_LABEL), count }))
         .sort((left, right) => right.count - left.count || left.name.localeCompare(right.name));
     return {
         agent: input.agent,

package/dist/untrustedLabel.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ONE place that decides what an untrusted NAME is allowed to become before it
+ * is interpolated into a sentence this product wrote.
+ *
+ * Why it exists at all. Every user-facing string here is built by templating a
+ * fragment the user did not author — a folder name off disk, a model id off a
+ * provider response, an operation label off an adapter — into prose that a
+ * coding agent will later read as instructions. The renderers cannot be the
+ * ones to make that safe:
+ *
+ *  - The `--full` terminal readout does not sanitize at all.
+ *  - The Markdown/Apply sanitizers that BLANK on a directive hit delete the
+ *    whole string, and the whole string is mostly OUR sentence. In 0.9.7 that
+ *    deleted the entire recommendation for 8 of 11 ordinary repo basenames,
+ *    because `write-ahead-log` sat 41 characters in front of our own word
+ *    "tokens" — and the terminal kept printing the finding, so two surfaces
+ *    disagreed about a dollar figure.
+ *
+ * So the check runs HERE, on the fragment alone, before it reaches any
+ * template. A fragment carries only the user's text, so an ordinary name has
+ * nothing of ours to pair with; and once the fragment is safe, every surface
+ * can render the finished sentence verbatim and they all agree.
+ *
+ * The rule for anyone adding a producer: if you interpolate a value that came
+ * off disk or off the wire into a string a user or an agent will read, wrap it
+ * in {@link safeUntrustedLabel} at the point of interpolation. Not at the
+ * renderer. Not once per surface. Here.
+ */
+/**
+ * What an untrusted label becomes when the name itself reads like an
+ * instruction. Each says WHY, because "withheld" with no reason reads like the
+ * product failed rather than declined: `diagnose` still shows the real folder
+ * name, so this is only about not REPEATING a name that looked like an
+ * instruction inside a sentence an agent will read.
+ *
+ * Every one of these must survive the report layer's own sanitizer UNCHANGED —
+ * a marker in brackets would be stripped there and two surfaces would disagree
+ * about a string whose whole job is agreeing. Parentheses survive; brackets do
+ * not.
+ *
+ * The project label sits in appositive and prepositional slots ("X — median day
+ * carried…", "the heaviest sessions in X"), so it carries the reason as prose.
+ * The rest sit in ATTRIBUTIVE slots ("Cache repeated X calls"), where a clause
+ * would not parse, so they carry the short parenthetical form.
+ */
+export declare const WITHHELD_PROJECT_LABEL = "a project whose name reads like an instruction";
+export declare const WITHHELD_MODEL_LABEL = "(model name reads like an instruction; withheld)";
+export declare const WITHHELD_OPERATION_LABEL = "(operation name reads like an instruction; withheld)";
+export declare const WITHHELD_AGENT_LABEL = "(agent name reads like an instruction; withheld)";
+export declare const WITHHELD_CLIENT_LABEL = "(client name reads like an instruction; withheld)";
+/**
+ * For a breakdown key whose dimension is decided at runtime — the same slot
+ * holds a client, a project, an agent, a model, or an operation depending on
+ * which grouping won.
+ */
+export declare const WITHHELD_ENTITY_LABEL = "(name reads like an instruction; withheld)";
+export declare const WITHHELD_FILE_LABEL = "(file name reads like an instruction; withheld)";
+export declare const WITHHELD_PLAN_LABEL = "(plan label reads like an instruction; withheld)";
+/** Map a list of untrusted keys for display, keeping order and length. */
+export declare function safeUntrustedLabels(values: readonly string[], withheld?: string): string[];
+/**
+ * Neutralize ONE untrusted fragment before it is interpolated into
+ * product-authored prose.
+ *
+ * Over-triggering here is cheap and under-triggering is not: a false positive
+ * costs one name while the finding and its dollars survive, so the patterns
+ * stay strict.
+ */
+export declare function safeUntrustedLabel(value: string, withheld: string): string;
+//# sourceMappingURL=untrustedLabel.d.ts.map

package/dist/untrustedLabel.js

@@ -0,0 +1,161 @@
+/**
+ * ONE place that decides what an untrusted NAME is allowed to become before it
+ * is interpolated into a sentence this product wrote.
+ *
+ * Why it exists at all. Every user-facing string here is built by templating a
+ * fragment the user did not author — a folder name off disk, a model id off a
+ * provider response, an operation label off an adapter — into prose that a
+ * coding agent will later read as instructions. The renderers cannot be the
+ * ones to make that safe:
+ *
+ *  - The `--full` terminal readout does not sanitize at all.
+ *  - The Markdown/Apply sanitizers that BLANK on a directive hit delete the
+ *    whole string, and the whole string is mostly OUR sentence. In 0.9.7 that
+ *    deleted the entire recommendation for 8 of 11 ordinary repo basenames,
+ *    because `write-ahead-log` sat 41 characters in front of our own word
+ *    "tokens" — and the terminal kept printing the finding, so two surfaces
+ *    disagreed about a dollar figure.
+ *
+ * So the check runs HERE, on the fragment alone, before it reaches any
+ * template. A fragment carries only the user's text, so an ordinary name has
+ * nothing of ours to pair with; and once the fragment is safe, every surface
+ * can render the finished sentence verbatim and they all agree.
+ *
+ * The rule for anyone adding a producer: if you interpolate a value that came
+ * off disk or off the wire into a string a user or an agent will read, wrap it
+ * in {@link safeUntrustedLabel} at the point of interpolation. Not at the
+ * renderer. Not once per surface. Here.
+ */
+/**
+ * What an untrusted label becomes when the name itself reads like an
+ * instruction. Each says WHY, because "withheld" with no reason reads like the
+ * product failed rather than declined: `diagnose` still shows the real folder
+ * name, so this is only about not REPEATING a name that looked like an
+ * instruction inside a sentence an agent will read.
+ *
+ * Every one of these must survive the report layer's own sanitizer UNCHANGED —
+ * a marker in brackets would be stripped there and two surfaces would disagree
+ * about a string whose whole job is agreeing. Parentheses survive; brackets do
+ * not.
+ *
+ * The project label sits in appositive and prepositional slots ("X — median day
+ * carried…", "the heaviest sessions in X"), so it carries the reason as prose.
+ * The rest sit in ATTRIBUTIVE slots ("Cache repeated X calls"), where a clause
+ * would not parse, so they carry the short parenthetical form.
+ */
+export const WITHHELD_PROJECT_LABEL = "a project whose name reads like an instruction";
+export const WITHHELD_MODEL_LABEL = "(model name reads like an instruction; withheld)";
+export const WITHHELD_OPERATION_LABEL = "(operation name reads like an instruction; withheld)";
+export const WITHHELD_AGENT_LABEL = "(agent name reads like an instruction; withheld)";
+export const WITHHELD_CLIENT_LABEL = "(client name reads like an instruction; withheld)";
+/**
+ * For a breakdown key whose dimension is decided at runtime — the same slot
+ * holds a client, a project, an agent, a model, or an operation depending on
+ * which grouping won.
+ */
+export const WITHHELD_ENTITY_LABEL = "(name reads like an instruction; withheld)";
+export const WITHHELD_FILE_LABEL = "(file name reads like an instruction; withheld)";
+export const WITHHELD_PLAN_LABEL = "(plan label reads like an instruction; withheld)";
+/** Map a list of untrusted keys for display, keeping order and length. */
+export function safeUntrustedLabels(values, withheld = WITHHELD_ENTITY_LABEL) {
+    return values.map((value) => safeUntrustedLabel(value, withheld));
+}
+/**
+ * Neutralize ONE untrusted fragment before it is interpolated into
+ * product-authored prose.
+ *
+ * Over-triggering here is cheap and under-triggering is not: a false positive
+ * costs one name while the finding and its dollars survive, so the patterns
+ * stay strict.
+ */
+export function safeUntrustedLabel(value, withheld) {
+    // Control characters and line breaks are structure, not name: a label that
+    // can open a new line can forge a new instruction on every surface at once.
+    const collapsed = value
+        .replace(/[\u0000-\u001F\u007F]/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim();
+    if (!collapsed)
+        return withheld;
+    return looksLikeDirectiveFragment(collapsed) ? withheld : collapsed;
+}
+/**
+ * Characters that are invisible to the reader but split a word for the
+ * matcher: zero-width spaces and joiners, bidi controls, variation selectors,
+ * the soft hyphen, the BOM. `i\u200Bgnore all previous instructions` reads as
+ * an instruction and matched nothing. Stripped for DETECTION ONLY — the label
+ * that gets printed is always the original text.
+ */
+const INVISIBLE_SEPARATORS = /[\u00AD\u034F\u061C\u115F\u1160\u17B4\u17B5\u180B-\u180E\u200B-\u200F\u202A-\u202E\u2060-\u2064\u206A-\u206F\u3164\uFE00-\uFE0F\uFEFF\uFFA0]/gu;
+/**
+ * The eight Latin/Cyrillic confusables that carry the directive verbs we look
+ * for: `\u0456gnore`, `d\u0435lete`, `\u0455ystem:` are indistinguishable on screen
+ * and invisible to an ASCII pattern. Folded for DETECTION ONLY.
+ */
+const CONFUSABLE_FOLD = new Map([
+    ["\u0430", "a"], ["\u0435", "e"], ["\u043E", "o"], ["\u0440", "p"],
+    ["\u0441", "c"], ["\u0445", "x"], ["\u0455", "s"], ["\u0456", "i"]
+]);
+/**
+ * The fragment is read TWICE, because a name and an instruction disagree about
+ * what a hyphen means.
+ *
+ * As ONE IDENTIFIER (`-` behaves like `_`): `ignore-list` is a directory, so
+ * the blunt single-word patterns cannot fire on it. This is what keeps ordinary
+ * repo names whole.
+ *
+ * As SEPARATED WORDS (`-` and `_` are spaces): `ignore-all-previous-instructions`
+ * is an instruction wearing a filename's punctuation. Only the PAIRED patterns
+ * run in this pass — each needs a directive verb next to an injection-flavored
+ * object — so an ordinary compound name has nothing to pair with. The unpaired
+ * verb list and the execute/run pattern deliberately stay out: `run-command-service`
+ * is a real directory, and a name-shaped `run-shell` cannot instruct anything.
+ */
+function looksLikeDirectiveFragment(value) {
+    const folded = value
+        .normalize("NFKC")
+        .replace(INVISIBLE_SEPARATORS, "")
+        .replace(/[\u0430\u0435\u043E\u0440\u0441\u0445\u0455\u0456]/gu, (char) => CONFUSABLE_FOLD.get(char) ?? char);
+    // A dot joins a filename the way a hyphen joins an identifier, so the
+    // identifier pass folds it too: `override.ts` and `ignore.md` are files, not
+    // instructions. The separated pass splits on it for the same reason it splits
+    // on hyphens — `ignore.all.previous.instructions` is prose wearing punctuation.
+    const asIdentifier = folded.replace(/[-.]/gu, "_");
+    const asWords = folded.replace(/[-_.]+/gu, " ");
+    return IDENTIFIER_DIRECTIVE_PATTERNS.some((pattern) => pattern.test(asIdentifier)) ||
+        SEPARATED_DIRECTIVE_PATTERNS.some((pattern) => pattern.test(asWords));
+}
+/**
+ * A directive needs a QUANTIFIER, not just a noun.
+ *
+ * `cache write tokens` is Anthropic's prompt-caching billing vocabulary and it
+ * arrives in the operation slot on real invoice lines; `write ALL tokens` is an
+ * instruction. Pairing a verb with a bare `tokens` withheld this product's own
+ * billing words — a real line item rendered as
+ * "acme / agent-finops / [unsafe metadata omitted]" — and on `aibill context`,
+ * whose entire job is naming exact files, it named one of three.
+ *
+ * Measured over 146 real strings (Anthropic + OpenAI caching vocabulary, real
+ * invoice line items, real filenames, ordinary repo names): false positives
+ * 18 -> 0, with hostile detection unchanged at 28/28.
+ *
+ * `everything` and `all files` already carry their own quantifier, so they stay
+ * unguarded. `system prompt` is an injection-specific noun phrase that no
+ * billing vocabulary contains, so it needs no quantifier either.
+ */
+const QUANTIFIED = "(?:all|every|any|each)";
+const IDENTIFIER_DIRECTIVE_PATTERNS = [
+    /\b(?:ignore|disregard|override|bypass)\b/i,
+    /\b(?:system|developer|assistant)\s*:/i,
+    /\b(?:execute|run)\b.{0,80}\b(?:command|shell|bash|powershell)\b/i,
+    new RegExp(`\\b(?:delete|remove|overwrite|edit|write)\\b.{0,60}(?:\\beverything\\b|\\ball files?\\b|\\b${QUANTIFIED}\\s+(?:configs?|credentials?|secrets?|tokens?)\\b)`, "i"),
+    new RegExp(`\\b(?:reveal|print|upload|send|exfiltrate)\\b.{0,60}(?:\\ball files?\\b|\\b(?:system|developer)\\s+prompts?\\b|\\b(?:${QUANTIFIED}|the)\\s+(?:credentials?|secrets?|tokens?|keys?|files?)\\b)`, "i"),
+    /\b(?:do not|don't)\b.{0,60}\b(?:follow|obey|wait|ask|require)\b.{0,40}\b(?:approval|instructions?|rules?)\b/i
+];
+const SEPARATED_DIRECTIVE_PATTERNS = [
+    /\b(?:ignore|disregard|override|bypass|forget)\b.{0,80}\b(?:previous|prior|above|earlier|preceding|instructions?|approval|rules?|guardrails?|system|developer|prompts?)\b/i,
+    new RegExp(`\\b(?:delete|remove|overwrite|edit|write)\\b.{0,60}(?:\\beverything\\b|\\ball files?\\b|\\b${QUANTIFIED}\\s+(?:configs?|credentials?|secrets?|tokens?)\\b)`, "i"),
+    new RegExp(`\\b(?:reveal|print|upload|send|exfiltrate|leak|dump)\\b.{0,60}(?:\\ball files?\\b|\\b(?:system|developer)\\s+prompts?\\b|\\b(?:${QUANTIFIED}|the)\\s+(?:credentials?|secrets?|tokens?|keys?|files?|prompts?)\\b)`, "i"),
+    /\b(?:do not|don't|never)\b.{0,60}\b(?:follow|obey|wait|ask|require)\b.{0,40}\b(?:approval|instructions?|rules?)\b/i
+];
+//# sourceMappingURL=untrustedLabel.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-finops/core",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "funding": "https://asktilden.com",
   "type": "module",
   "main": "./dist/index.js",