@agent-finops/core 0.9.6 → 0.9.7

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.7",
   "funding": "https://asktilden.com",
   "type": "module",
   "main": "./dist/index.js",