@shield-agent/kya 0.33.6 → 0.34.0

package/dist/alerts/scan.js

@@ -0,0 +1,188 @@
+/**
+ * Incident alert scan. Runs the deterministic detectors over the trail events of the last
+ * `windowMinutes`, keeps incidents at or above the severity floor, drops the ones already alerted
+ * (alerts-state.json) and sends `incident.opened` to the user-level webhooks and the desktop.
+ * Optional local triage model: when installed, each new alert gets category, urgency, action and benign
+ * (advisory text only). The model never decides whether an alert is sent: no model, a failed model and a
+ * slow model all give the same alert with the detector severity.
+ *
+ * Callers: the detached `kya notify-flush` child and the report daemon. Both are off the hook path.
+ * Advisory and fail open: nothing here throws, and a failed scan changes no verdict.
+ * Receivers and settings come from the user-level config only; a project config is never read.
+ */
+import { kyaHome, readFileConfig } from "../config.js";
+import { investigateTrail } from "../investigate/index.js";
+import { notifyIncident, resolveIncidentWebhooks } from "../notify/index.js";
+import { readGlobalTrail } from "../trail.js";
+import { resolveAlertsConfig, severityRank } from "./config.js";
+import { desktopNotify } from "./desktop.js";
+import { buildIncidentAlert } from "./incident-alert.js";
+import { incidentRef, needsAlert, readAlertsState, withStateLock, writeAlertsState, } from "./state.js";
+import { buildTriageInput } from "./triage-input.js";
+import { triageInstalled } from "./triage-status.js";
+const NONE = { alerted: [], delivered: 0 };
+/** Model load plus one inference. Longer than this and the alert goes out without triage. */
+export const TRIAGE_TIMEOUT_MS = 8_000;
+/** One scan opens at most this many desktop notifications (an incident storm must not flood the screen). */
+export const MAX_DESKTOP_PER_SCAN = 3;
+function withTimeout(p, ms) {
+    let timer;
+    const t = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), ms);
+        timer.unref?.();
+    });
+    return Promise.race([p, t]).finally(() => clearTimeout(timer));
+}
+/** The model is loaded here, in the flush child or the report daemon, and only when an alert is new. Never in the hook. */
+function defaultTriage(env) {
+    if (!triageInstalled(env))
+        return undefined;
+    return async (input) => (await import("./triage-model.js")).triageIncident(input, env);
+}
+/**
+ * Add triage to each claimed alert on its first attempt. A retry never loads the model again: a crash of the
+ * model code (it is native code) must not be able to eat the retries of an alert. Any failure leaves the alert as it is.
+ */
+async function addTriage(due, events, env, deps) {
+    const run = deps.triage ?? defaultTriage(env);
+    const todo = due.filter((d) => d.first);
+    if (!run || todo.length === 0)
+        return;
+    try {
+        let slow = false;
+        for (const d of todo) {
+            if (slow)
+                break; // no result (timeout or a failing model): the rest of this scan goes out without triage, at once
+            try {
+                const triage = await withTimeout(run(buildTriageInput(d.inc, events)), deps.triageTimeoutMs ?? TRIAGE_TIMEOUT_MS);
+                if (triage)
+                    d.alert = { ...d.alert, triage };
+                else
+                    slow = true;
+            }
+            catch {
+                /* fail open: no triage, same alert */
+            }
+        }
+    }
+    finally {
+        // The report daemon lives long: give the model memory back after each scan.
+        if (!deps.triage)
+            await (await import("./triage-model.js")).releaseTriageModel().catch(() => undefined);
+    }
+}
+/** Events may be at most this far in the future (clock skew). Later ones are forged or broken. */
+export const MAX_FUTURE_MS = 5 * 60_000;
+/** Events inside the window. A ts that does not parse, or lies more than 5 minutes ahead, is dropped. */
+export function windowEvents(events, now, windowMinutes) {
+    const from = now.getTime() - windowMinutes * 60_000;
+    const to = now.getTime() + MAX_FUTURE_MS;
+    return events.filter((e) => {
+        const t = Date.parse(e.ts);
+        return !Number.isNaN(t) && t >= from && t <= to;
+    });
+}
+/** Pure core: events in, incidents at or above the floor out. */
+export function incidentsAboveFloor(events, minSeverity) {
+    const result = investigateTrail(events);
+    return {
+        incidents: result.incidents.filter((i) => severityRank(i.severity) >= severityRank(minSeverity)),
+        briefs: result.briefs,
+    };
+}
+async function saveTriage(env, claimed) {
+    await withStateLock(env, () => {
+        const byKey = new Map(claimed.map((c) => [c.key, c.alert.triage]));
+        writeAlertsState(env, readAlertsState(env).map((e) => {
+            const triage = byKey.get(e.key);
+            return triage ? { ...e, triage } : e;
+        }));
+    });
+}
+export async function runAlertScan(_cwd, env, deps = {}) {
+    try {
+        const cfg = resolveAlertsConfig(env);
+        if (!cfg.enabled)
+            return NONE;
+        const now = (deps.now ?? (() => new Date()))();
+        // User-level trail only (tail-capped): a project trail ships with a cloned repo and could be forged.
+        const events = windowEvents(readGlobalTrail(env), now, cfg.windowMinutes);
+        if (events.length === 0)
+            return NONE;
+        const { incidents, briefs } = incidentsAboveFloor(events, cfg.minSeverity);
+        if (incidents.length === 0)
+            return NONE;
+        const targets = resolveIncidentWebhooks(readFileConfig(kyaHome(env)));
+        // Claim under the lock so two flush children never send the same alert.
+        const claimed = await withStateLock(env, () => {
+            const entries = readAlertsState(env);
+            const due = [];
+            for (const inc of incidents) {
+                const ref = incidentRef(inc.id);
+                if (!needsAlert(entries, { ref, severity: inc.severity, firstTs: inc.firstTs, lastTs: inc.lastTs }, now.getTime()))
+                    continue;
+                const alert = buildIncidentAlert(inc, events, briefs.get(inc.id));
+                const key = `${ref}:${inc.severity}`;
+                const prev = entries.find((e) => e.key === key);
+                // A pending entry is a retry of the same alert (delivery failed). A sent one means this is a new occurrence.
+                const retry = prev?.status === "pending";
+                const entry = {
+                    key,
+                    ref,
+                    severity: inc.severity,
+                    ts: now.toISOString(),
+                    lastTs: inc.lastTs,
+                    title: alert.title,
+                    detectors: [...alert.detectorIds],
+                    delivered: 0,
+                    attempts: (prev?.attempts ?? 0) + 1,
+                    ...(retry && prev?.triage ? { triage: prev.triage } : {}),
+                    // No receiver: the alert shows in the report only, nothing more to retry.
+                    status: targets.length === 0 ? "sent" : "pending",
+                };
+                if (prev)
+                    entries.splice(entries.indexOf(prev), 1);
+                entries.push(entry);
+                due.push({ alert: retry && prev?.triage ? { ...alert, triage: prev.triage } : alert, key, inc, first: !retry });
+            }
+            if (due.length > 0)
+                writeAlertsState(env, entries);
+            return due;
+        });
+        if (!claimed || claimed.length === 0)
+            return NONE;
+        // Desktop first: its text holds no triage, and a crash of the model code (native) must not take the notification with it.
+        if (cfg.desktop) {
+            const fresh = claimed.filter((c) => c.first).slice(0, MAX_DESKTOP_PER_SCAN);
+            for (const { alert } of fresh)
+                await desktopNotify(alert, env, deps.desktop);
+        }
+        await addTriage(claimed, events, env, deps);
+        // Keep the triage before anything is sent: a retry then reuses it and never needs the model.
+        if (claimed.some((c) => c.first && c.alert.triage))
+            await saveTriage(env, claimed);
+        let delivered = 0;
+        const results = new Map();
+        if (targets.length > 0) {
+            for (const { alert, key } of claimed) {
+                const n = await notifyIncident(alert, targets, env, deps);
+                results.set(key, n);
+                delivered += n;
+            }
+        }
+        if (targets.length > 0) {
+            await withStateLock(env, () => {
+                const next = readAlertsState(env).map((e) => {
+                    const n = results.get(e.key);
+                    return n === undefined ? e : { ...e, delivered: n, status: n > 0 ? "sent" : "pending" };
+                });
+                writeAlertsState(env, next);
+            });
+        }
+        return { alerted: claimed.map((c) => c.alert), delivered };
+    }
+    catch {
+        return NONE;
+    }
+}
+//# sourceMappingURL=scan.js.map

package/dist/alerts/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../src/alerts/scan.ts"],"names":[],"mappings":"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"}

package/dist/alerts/state.d.ts

@@ -0,0 +1,55 @@
+import type { Severity } from "../investigate/detectors.js";
+import type { IncidentTriage } from "./triage-model.js";
+export declare const ALERTS_STATE_FILE = "alerts-state.json";
+export declare const ALERTS_STATE_KEEP = 500;
+/** A failed delivery is tried again at most this many times in total. */
+export declare const MAX_ATTEMPTS = 3;
+/** A pending entry is not retried before this many ms have passed (a running sibling child owns it). */
+export declare const RETRY_AFTER_MS = 60000;
+export interface AlertEntry {
+    /** `${ref}:${severity}` */
+    readonly key: string;
+    /** Hash of the detector incident id. The raw id can hold a session id, so it is never stored. */
+    readonly ref: string;
+    readonly severity: Severity;
+    /** When the alert was claimed (ISO). */
+    readonly ts: string;
+    /** Last event time of the alerted incident (ISO, "" when unknown). */
+    readonly lastTs: string;
+    readonly title: string;
+    readonly detectors: readonly string[];
+    /** Receivers that accepted the alert. */
+    readonly delivered: number;
+    readonly attempts: number;
+    readonly status: "sent" | "pending";
+    /** Local model triage of this incident, when the model was installed. Advisory. */
+    readonly triage?: IncidentTriage;
+}
+/** Defensive parse: every id is checked against a plain-word shape, so a forged state file cannot inject markup. */
+export declare function parseTriage(raw: unknown): IncidentTriage | undefined;
+export declare function incidentRef(incidentId: string): string;
+export declare function alertsStatePath(env?: NodeJS.ProcessEnv): string;
+/** Missing or bad file: an empty list (alerting then works as on a first run). */
+export declare function readAlertsState(env?: NodeJS.ProcessEnv): AlertEntry[];
+/** Atomic write, last ALERTS_STATE_KEEP entries. Never throws. */
+export declare function writeAlertsState(env: NodeJS.ProcessEnv, entries: readonly AlertEntry[]): void;
+export interface IncidentMeta {
+    readonly ref: string;
+    readonly severity: Severity;
+    readonly firstTs: string;
+    readonly lastTs: string;
+}
+/**
+ * Pure dedupe decision. `entries` is the stored list in write order.
+ * Alert when: no entry for the ref; severity above the last entry; the incident starts after the
+ * last alerted one ended (new occurrence); or the last entry is still pending (not delivered),
+ * has attempts left, and its cool-down has passed.
+ */
+export declare function needsAlert(entries: readonly AlertEntry[], inc: IncidentMeta, nowMs: number): boolean;
+/**
+ * Run `fn` while holding the state lock (an exclusive mkdir). A lock older than 15 s is stale and
+ * removed. When the lock cannot be taken within 2 s, `fn` is skipped and undefined is returned:
+ * the next flush or the next report tick covers it.
+ */
+export declare function withStateLock<T>(env: NodeJS.ProcessEnv, fn: () => T | Promise<T>): Promise<T | undefined>;
+//# sourceMappingURL=state.d.ts.map

package/dist/alerts/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/alerts/state.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,mBAAmB,CAAC;AAEpE,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,yEAAyE;AACzE,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,wGAAwG;AACxG,eAAO,MAAM,cAAc,QAAS,CAAC;AAIrC,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAWD,oHAAoH;AACpH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CASpE;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE5E;AAgCD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,EAAE,CAUlF;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAQ7F;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAapG;AAID;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAgC/G"}

package/dist/alerts/state.js

@@ -0,0 +1,178 @@
+/**
+ * Dedupe memory for incident alerts: <kya-home>/.kya/alerts-state.json.
+ * One entry per (incident ref, severity). An incident alerts once. It alerts again only when its
+ * severity rises, or when a new occurrence starts after the last alerted one ended. A refresh
+ * (more events in the same incident) never alerts again. The file keeps the last 500 entries
+ * and is written atomically. Several detached flush children can run at once, so the claim step
+ * runs under a short lock directory.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { globalConfigDir } from "../config.js";
+import { atomicWriteSync } from "../fs-atomic.js";
+import { isSeverity, severityRank } from "./config.js";
+export const ALERTS_STATE_FILE = "alerts-state.json";
+export const ALERTS_STATE_KEEP = 500;
+/** A failed delivery is tried again at most this many times in total. */
+export const MAX_ATTEMPTS = 3;
+/** A pending entry is not retried before this many ms have passed (a running sibling child owns it). */
+export const RETRY_AFTER_MS = 60_000;
+const LOCK_STALE_MS = 15_000;
+const LOCK_WAIT_MS = 2_000;
+const TRIAGE_ID = /^[a-z0-9-]{1,40}$/;
+function parsePick(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const r = raw;
+    if (typeof r.id !== "string" || !TRIAGE_ID.test(r.id) || typeof r.p !== "number" || !Number.isFinite(r.p))
+        return undefined;
+    return { id: r.id, p: Math.min(1, Math.max(0, r.p)) };
+}
+/** Defensive parse: every id is checked against a plain-word shape, so a forged state file cannot inject markup. */
+export function parseTriage(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const r = raw;
+    const category = parsePick(r.category);
+    const urgency = parsePick(r.urgency);
+    const action = parsePick(r.action);
+    if (!category || !urgency || !action || typeof r.model !== "string" || !TRIAGE_ID.test(r.model))
+        return undefined;
+    if (typeof r.benign !== "number" || !Number.isFinite(r.benign))
+        return undefined;
+    return { model: r.model, category, urgency, action, benign: Math.min(1, Math.max(0, r.benign)) };
+}
+export function incidentRef(incidentId) {
+    return createHash("sha256").update(incidentId, "utf8").digest("hex").slice(0, 12);
+}
+export function alertsStatePath(env = process.env) {
+    return join(globalConfigDir(env), ALERTS_STATE_FILE);
+}
+function parseEntry(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const e = raw;
+    if (typeof e.key !== "string" ||
+        typeof e.ref !== "string" ||
+        !isSeverity(e.severity) ||
+        typeof e.ts !== "string" ||
+        typeof e.title !== "string" ||
+        (e.status !== "sent" && e.status !== "pending")) {
+        return undefined;
+    }
+    return {
+        key: e.key.slice(0, 80),
+        ref: e.ref.slice(0, 40),
+        severity: e.severity,
+        ts: e.ts.slice(0, 40),
+        lastTs: typeof e.lastTs === "string" ? e.lastTs.slice(0, 40) : "",
+        title: e.title.slice(0, 200),
+        detectors: Array.isArray(e.detectors)
+            ? e.detectors.filter((d) => typeof d === "string").slice(0, 10).map((d) => d.slice(0, 40))
+            : [],
+        delivered: typeof e.delivered === "number" && Number.isFinite(e.delivered) ? Math.max(0, Math.floor(e.delivered)) : 0,
+        attempts: typeof e.attempts === "number" && Number.isFinite(e.attempts) ? Math.max(0, Math.floor(e.attempts)) : 0,
+        status: e.status,
+        ...(parseTriage(e.triage) ? { triage: parseTriage(e.triage) } : {}),
+    };
+}
+/** Missing or bad file: an empty list (alerting then works as on a first run). */
+export function readAlertsState(env = process.env) {
+    try {
+        const path = alertsStatePath(env);
+        if (!existsSync(path))
+            return [];
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (!Array.isArray(raw.entries))
+            return [];
+        return raw.entries.map(parseEntry).filter((e) => e !== undefined);
+    }
+    catch {
+        return [];
+    }
+}
+/** Atomic write, last ALERTS_STATE_KEEP entries. Never throws. */
+export function writeAlertsState(env, entries) {
+    try {
+        mkdirSync(globalConfigDir(env), { recursive: true });
+        const kept = entries.slice(-ALERTS_STATE_KEEP);
+        atomicWriteSync(alertsStatePath(env), `${JSON.stringify({ version: 1, entries: kept }, null, 1)}\n`);
+    }
+    catch {
+        /* a lost write only means one alert may repeat */
+    }
+}
+/**
+ * Pure dedupe decision. `entries` is the stored list in write order.
+ * Alert when: no entry for the ref; severity above the last entry; the incident starts after the
+ * last alerted one ended (new occurrence); or the last entry is still pending (not delivered),
+ * has attempts left, and its cool-down has passed.
+ */
+export function needsAlert(entries, inc, nowMs) {
+    let last;
+    for (const e of entries)
+        if (e.ref === inc.ref)
+            last = e;
+    if (last === undefined)
+        return true;
+    if (severityRank(inc.severity) > severityRank(last.severity))
+        return true;
+    const first = Date.parse(inc.firstTs);
+    const prevEnd = Date.parse(last.lastTs);
+    if (!Number.isNaN(first) && !Number.isNaN(prevEnd) && first > prevEnd)
+        return true;
+    if (last.status === "pending" && last.attempts < MAX_ATTEMPTS) {
+        const claimed = Date.parse(last.ts);
+        return Number.isNaN(claimed) || nowMs - claimed >= RETRY_AFTER_MS;
+    }
+    return false;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Run `fn` while holding the state lock (an exclusive mkdir). A lock older than 15 s is stale and
+ * removed. When the lock cannot be taken within 2 s, `fn` is skipped and undefined is returned:
+ * the next flush or the next report tick covers it.
+ */
+export async function withStateLock(env, fn) {
+    const dir = `${alertsStatePath(env)}.lock`;
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    try {
+        mkdirSync(globalConfigDir(env), { recursive: true });
+    }
+    catch {
+        return undefined;
+    }
+    for (;;) {
+        try {
+            mkdirSync(dir);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                return undefined;
+            try {
+                if (Date.now() - statSync(dir).mtimeMs > LOCK_STALE_MS)
+                    rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                /* the holder just released it */
+            }
+            if (Date.now() >= deadline)
+                return undefined;
+            await sleep(25);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            /* stale lock cleanup handles it */
+        }
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/alerts/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/alerts/state.ts"],"names":[],"mappings":"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"}

package/dist/alerts/triage-input.d.ts

@@ -0,0 +1,36 @@
+import type { TrailEvent } from "../trail.js";
+import { type Severity } from "../investigate/detectors.js";
+import type { Incident } from "../investigate/incidents.js";
+export declare const TRIAGE_SCHEMA_VERSION = "1";
+export declare const MAX_REASON_CODES = 10;
+export declare const MAX_NEVER_RULES = 10;
+export declare const MAX_TARGET_CLASSES = 10;
+export declare const MAX_TOOL_IDS = 10;
+export declare const MAX_SUMMARIES = 5;
+export declare const MAX_SUMMARY_CHARS = 120;
+/** Clip for short identifier lists (tool ids, reason codes, rule ids, classes). */
+export declare const MAX_ID_CHARS = 64;
+/** Even the minimal input failed the secret check. The caller must skip the model and alert on detector severity. */
+export declare class TriageInputUnsafeError extends Error {
+    constructor();
+}
+export interface TriageInput {
+    readonly schemaVersion: string;
+    readonly detectorIds: string[];
+    readonly severity: Severity;
+    readonly reasonCodes: string[];
+    readonly neverRules: string[];
+    readonly targetClasses: string[];
+    readonly toolIds: string[];
+    readonly counts: {
+        readonly allow: number;
+        readonly hold: number;
+        readonly deny: number;
+    };
+    readonly windowMinutes: number;
+    readonly summaries: string[];
+    readonly product: string;
+    readonly repeats: number;
+}
+export declare function buildTriageInput(incident: Incident, events: readonly TrailEvent[]): TriageInput;
+//# sourceMappingURL=triage-input.d.ts.map

package/dist/alerts/triage-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triage-input.d.ts","sourceRoot":"","sources":["../../src/alerts/triage-input.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,YAAY,KAAK,CAAC;AAC/B,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,mFAAmF;AACnF,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,qHAAqH;AACrH,qBAAa,sBAAuB,SAAQ,KAAK;;CAKhD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAqDD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,WAAW,CAwC/F"}

package/dist/alerts/triage-input.js

@@ -0,0 +1,159 @@
+/**
+ * Privacy-safe model input for incident triage. Built only from the detector
+ * incident and its trail events. Free text comes from TrailEvent.summary,
+ * re-redacted and clipped. Raw arguments, argument hashes, target paths, diff
+ * previews, project folders, session ids and device ids never enter the input.
+ * Mirrored in Java: com.shieldagent.core.kya.alerts.TriageInputBuilder.
+ */
+import { assertNoSecrets } from "../dash/render.js";
+import { redactTrailText } from "../trail-summary.js";
+import { containsPii } from "../investigate/detectors.js";
+export const TRIAGE_SCHEMA_VERSION = "1";
+export const MAX_REASON_CODES = 10;
+export const MAX_NEVER_RULES = 10;
+export const MAX_TARGET_CLASSES = 10;
+export const MAX_TOOL_IDS = 10;
+export const MAX_SUMMARIES = 5;
+export const MAX_SUMMARY_CHARS = 120;
+/** Clip for short identifier lists (tool ids, reason codes, rule ids, classes). */
+export const MAX_ID_CHARS = 64;
+/** Even the minimal input failed the secret check. The caller must skip the model and alert on detector severity. */
+export class TriageInputUnsafeError extends Error {
+    constructor() {
+        super("triage input failed the secret check after every fallback stage");
+        this.name = "TriageInputUnsafeError";
+    }
+}
+const HOME_UNIX = /\/(?:Users|home)\/[^/\s]+/g;
+const HOME_ROOT = /\/root(?=[/\s]|$)/g;
+const HOME_WIN = /[A-Za-z]:\\Users\\[^\\\s]+/g;
+/** Control, format and line or paragraph separator characters (U+2028, U+2029, U+200B, U+FEFF ...). */
+const INVISIBLE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+/** Every event identifier is untrusted: only this shape reaches the model (whole value, no spaces). */
+const SAFE_ID = /^[A-Za-z0-9._:/*@+-]{1,64}$/;
+/** Replace a home folder (and the user name in it) with "~". */
+function stripHome(s) {
+    return s.replace(HOME_UNIX, "~").replace(HOME_ROOT, "~").replace(HOME_WIN, "~");
+}
+function clip(s, max) {
+    return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+/**
+ * Free text: invisible characters become a space, then redact, remove home folders, flatten
+ * whitespace. The caller clips. Empty string means drop.
+ */
+function flatten(s) {
+    const visible = s.replace(INVISIBLE, " ");
+    return stripHome(redactTrailText(visible)).replace(/\s+/g, " ").trim();
+}
+/** An identifier is kept only when it has the safe shape and redaction or home-path removal would not change it. */
+function isSafeId(v) {
+    return SAFE_ID.test(v) && stripHome(redactTrailText(v)) === v;
+}
+/** First-seen order, only safe identifiers, no duplicates, at most `max` items. */
+function uniq(values, max) {
+    const seen = new Set();
+    for (const v of values) {
+        if (typeof v === "string" && isSafeId(v))
+            seen.add(v);
+        if (seen.size >= max)
+            break;
+    }
+    return [...seen];
+}
+function incidentEvents(incident, events) {
+    const idx = new Set();
+    for (const f of incident.findings) {
+        for (const i of f.eventIdx) {
+            if (Number.isInteger(i) && i >= 0 && i < events.length)
+                idx.add(i);
+        }
+    }
+    return [...idx].sort((a, b) => a - b).map((i) => events[i]);
+}
+export function buildTriageInput(incident, events) {
+    const evs = incidentEvents(incident, events);
+    const counts = { allow: 0, hold: 0, deny: 0 };
+    const perTool = new Map();
+    const summaries = [];
+    let product = "";
+    for (const e of evs) {
+        if (e.verdict === "ALLOW")
+            counts.allow++;
+        else if (e.verdict === "REQUIRE_APPROVE")
+            counts.hold++;
+        else if (e.verdict === "DENY")
+            counts.deny++;
+        perTool.set(e.toolId, (perTool.get(e.toolId) ?? 0) + 1);
+        if (!product && e.product)
+            product = e.product;
+        if (e.summary && summaries.length < MAX_SUMMARIES) {
+            // A summary the pii-in-summary detector flags (e-mail, card number, high-entropy token) is dropped
+            // whole, before the clip: a clip could cut a match in two, and a partial mask is not a guarantee.
+            const flat = flatten(e.summary);
+            if (containsPii(e.summary) || containsPii(flat))
+                continue;
+            const s = clip(flat, MAX_SUMMARY_CHARS);
+            if (s && !summaries.includes(s))
+                summaries.push(s);
+        }
+    }
+    const first = Date.parse(incident.firstTs);
+    const last = Date.parse(incident.lastTs);
+    const windowMinutes = Number.isNaN(first) || Number.isNaN(last) ? 0 : Math.max(0, Math.ceil((last - first) / 60_000));
+    const input = {
+        schemaVersion: TRIAGE_SCHEMA_VERSION,
+        detectorIds: [...new Set(incident.findings.map((f) => f.detectorId).filter(isSafeId))].sort(),
+        severity: incident.severity,
+        reasonCodes: uniq(evs.map((e) => e.reasonCode), MAX_REASON_CODES),
+        neverRules: uniq(evs.map((e) => e.neverRule), MAX_NEVER_RULES),
+        targetClasses: uniq(evs.map((e) => e.targetClass), MAX_TARGET_CLASSES),
+        toolIds: uniq(evs.map((e) => e.toolId), MAX_TOOL_IDS),
+        counts,
+        windowMinutes,
+        summaries,
+        product: isSafeId(product) ? product : "unknown",
+        repeats: Math.max(0, ...perTool.values()),
+    };
+    return failClosed(input);
+}
+function passesSecretCheck(input) {
+    try {
+        assertNoSecrets(JSON.stringify(input));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check after every stage: full input, then no summaries, then also no tool ids, then the minimal input
+ * (no free-text field at all). Throws when even the minimal input fails, so alerting uses detector severity.
+ */
+function failClosed(input) {
+    const noText = { ...input, summaries: [] };
+    const stages = [
+        input,
+        noText,
+        { ...noText, toolIds: [] },
+        {
+            schemaVersion: input.schemaVersion,
+            detectorIds: input.detectorIds,
+            severity: input.severity,
+            reasonCodes: [],
+            neverRules: [],
+            targetClasses: [],
+            toolIds: [],
+            counts: input.counts,
+            windowMinutes: input.windowMinutes,
+            summaries: [],
+            product: "unknown",
+            repeats: input.repeats,
+        },
+    ];
+    for (const stage of stages)
+        if (passesSecretCheck(stage))
+            return stage;
+    throw new TriageInputUnsafeError();
+}
+//# sourceMappingURL=triage-input.js.map