@shield-agent/kya 0.22.0 → 0.23.0

package/dist/notify/sender.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Webhook delivery for trail verdicts. Reliability contract (a notify failure must never change
+ * what the gate does with the tool call itself):
+ *
+ *  - up to 3 retries after the first attempt, backoff 250ms / 1s / 4s with up to +25% jitter;
+ *  - per-attempt timeout (default 3s) via AbortController;
+ *  - process-wide rate limit: max 20 sends per rolling minute, overflow counted and dropped;
+ *  - per-URL circuit breaker: 5 consecutive failed deliveries open the circuit for 5 minutes,
+ *    while open the URL gets nothing (drops counted separately);
+ *  - nothing in this module throws.
+ */
+export type NotifyFetchLike = (input: string, init?: RequestInit) => Promise<Pick<Response, "ok" | "status">>;
+export interface NotifyDeps {
+    readonly fetchImpl?: NotifyFetchLike;
+    /** Test seam: replaces the backoff wait. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Test seam: jitter source, defaults to Math.random. */
+    readonly random?: () => number;
+    /** Test seam: clock for the rate window and circuit breaker. */
+    readonly nowMs?: () => number;
+}
+export interface SendOptions {
+    readonly url: string;
+    readonly body: string;
+    readonly headers?: Record<string, string>;
+    readonly timeoutMs?: number;
+    /** Test seam: replaces RETRY_DELAYS_MS. */
+    readonly retryDelaysMs?: readonly number[];
+}
+export declare const DEFAULT_TIMEOUT_MS = 3000;
+/** Wait before retry attempts 1..3 (the first send is immediate, so 4 sends worst case). */
+export declare const RETRY_DELAYS_MS: readonly number[];
+export declare const JITTER_RATIO = 0.25;
+export declare const RATE_LIMIT_MAX_SENDS = 20;
+export declare const RATE_LIMIT_WINDOW_MS = 60000;
+export declare const CIRCUIT_FAILURES_TO_OPEN = 5;
+export declare const CIRCUIT_OPEN_MS: number;
+/** Snapshot of drop counters, for `kya` diagnostics and tests. */
+export declare function notifyStats(): {
+    droppedByRateLimit: number;
+    droppedByCircuitOpen: number;
+};
+/** Test helper: clears the rate window, the drop counters and every circuit. */
+export declare function resetNotifyState(): void;
+/** Single attempt. ok only on a 2xx; timeout, abort, redirect and network errors are all false. */
+export declare function postWebhook(url: string, body: string, opts?: {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}, fetchImpl?: NotifyFetchLike): Promise<boolean>;
+/**
+ * Deliver one serialized payload with retries. Returns whether it was delivered (or at least
+ * accepted by the receiver). Rate-limited attempts drop the whole delivery without counting as a
+ * receiver failure; an exhausted retry sequence feeds the circuit breaker. Never throws.
+ */
+export declare function sendWithRetry(opts: SendOptions, deps?: NotifyDeps): Promise<boolean>;
+//# sourceMappingURL=sender.d.ts.map

package/dist/notify/sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../src/notify/sender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC;AAE9C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AACxC,4FAA4F;AAC5F,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAwB,CAAC;AACtE,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,eAAe,QAAa,CAAC;AAe1C,kEAAkE;AAClE,wBAAgB,WAAW,IAAI;IAAE,kBAAkB,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,CAE1F;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AA4CD,mGAAmG;AACnG,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,EACnE,SAAS,GAAE,eAAuB,GACjC,OAAO,CAAC,OAAO,CAAC,CAyBlB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAkC9F"}

package/dist/notify/sender.js

@@ -0,0 +1,139 @@
+/**
+ * Webhook delivery for trail verdicts. Reliability contract (a notify failure must never change
+ * what the gate does with the tool call itself):
+ *
+ *  - up to 3 retries after the first attempt, backoff 250ms / 1s / 4s with up to +25% jitter;
+ *  - per-attempt timeout (default 3s) via AbortController;
+ *  - process-wide rate limit: max 20 sends per rolling minute, overflow counted and dropped;
+ *  - per-URL circuit breaker: 5 consecutive failed deliveries open the circuit for 5 minutes,
+ *    while open the URL gets nothing (drops counted separately);
+ *  - nothing in this module throws.
+ */
+export const DEFAULT_TIMEOUT_MS = 3_000;
+/** Wait before retry attempts 1..3 (the first send is immediate, so 4 sends worst case). */
+export const RETRY_DELAYS_MS = [250, 1_000, 4_000];
+export const JITTER_RATIO = 0.25;
+export const RATE_LIMIT_MAX_SENDS = 20;
+export const RATE_LIMIT_WINDOW_MS = 60_000;
+export const CIRCUIT_FAILURES_TO_OPEN = 5;
+export const CIRCUIT_OPEN_MS = 5 * 60_000;
+// Process-wide state: the hook path is spawn-per-tool-call in some hosts, but long-lived MCP /
+// gateway processes share one limiter so a flood of denies cannot hammer a receiver.
+const sendTimestamps = [];
+let droppedByRateLimit = 0;
+let droppedByCircuitOpen = 0;
+const circuits = new Map();
+/** Snapshot of drop counters, for `kya` diagnostics and tests. */
+export function notifyStats() {
+    return { droppedByRateLimit, droppedByCircuitOpen };
+}
+/** Test helper: clears the rate window, the drop counters and every circuit. */
+export function resetNotifyState() {
+    sendTimestamps.length = 0;
+    droppedByRateLimit = 0;
+    droppedByCircuitOpen = 0;
+    circuits.clear();
+}
+/** One POST against the rolling-minute quota. False (and counted) when the window is full. */
+function consumeSendQuota(nowMs) {
+    while (sendTimestamps.length > 0 && nowMs - (sendTimestamps[0] ?? 0) >= RATE_LIMIT_WINDOW_MS) {
+        sendTimestamps.shift();
+    }
+    if (sendTimestamps.length >= RATE_LIMIT_MAX_SENDS) {
+        droppedByRateLimit += 1;
+        return false;
+    }
+    sendTimestamps.push(nowMs);
+    return true;
+}
+function circuitOpen(url, nowMs) {
+    const state = circuits.get(url);
+    if (state === undefined)
+        return false;
+    if (state.openUntil > nowMs)
+        return true;
+    if (state.failures >= CIRCUIT_FAILURES_TO_OPEN) {
+        // Cooldown elapsed: half-open, the next delivery decides.
+        state.failures = 0;
+        state.openUntil = 0;
+    }
+    return false;
+}
+function recordDeliverySuccess(url) {
+    circuits.delete(url);
+}
+function recordDeliveryFailure(url, nowMs) {
+    const state = circuits.get(url) ?? { failures: 0, openUntil: 0 };
+    state.failures += 1;
+    if (state.failures >= CIRCUIT_FAILURES_TO_OPEN) {
+        state.openUntil = nowMs + CIRCUIT_OPEN_MS;
+    }
+    circuits.set(url, state);
+}
+function backoffWithJitter(baseMs, random) {
+    return baseMs + Math.floor(baseMs * JITTER_RATIO * random());
+}
+/** Single attempt. ok only on a 2xx; timeout, abort, redirect and network errors are all false. */
+export async function postWebhook(url, body, opts = {}, fetchImpl = fetch) {
+    const controller = new AbortController();
+    const timeoutMs = opts.timeoutMs !== undefined && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0
+        ? opts.timeoutMs
+        : DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "user-agent": "shield-agent-kya-cli/notify",
+                ...opts.headers,
+            },
+            body,
+            redirect: "error",
+            signal: controller.signal,
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Deliver one serialized payload with retries. Returns whether it was delivered (or at least
+ * accepted by the receiver). Rate-limited attempts drop the whole delivery without counting as a
+ * receiver failure; an exhausted retry sequence feeds the circuit breaker. Never throws.
+ */
+export async function sendWithRetry(opts, deps = {}) {
+    try {
+        const nowMs = deps.nowMs ?? Date.now;
+        const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        const random = deps.random ?? Math.random;
+        const fetchImpl = deps.fetchImpl ?? fetch;
+        const delays = opts.retryDelaysMs ?? RETRY_DELAYS_MS;
+        if (circuitOpen(opts.url, nowMs())) {
+            droppedByCircuitOpen += 1;
+            return false;
+        }
+        for (let attempt = 0; attempt <= delays.length; attempt++) {
+            if (attempt > 0) {
+                await sleep(backoffWithJitter(delays[attempt - 1] ?? 0, random));
+            }
+            if (!consumeSendQuota(nowMs()))
+                return false;
+            const ok = await postWebhook(opts.url, opts.body, { headers: opts.headers, timeoutMs: opts.timeoutMs }, fetchImpl);
+            if (ok) {
+                recordDeliverySuccess(opts.url);
+                return true;
+            }
+        }
+        recordDeliveryFailure(opts.url, nowMs());
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=sender.js.map

package/dist/notify/sender.js.map

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

package/dist/notify/templates.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-receiver payload shapes for trail verdict notifications (slack / linear / jira / generic).
+ * Every builder works from the already-redacted trail fields only - raw tool args and diff content
+ * never reach this module, and the allow-list below is the complete set of fields a payload may carry.
+ */
+import type { TrailEvent } from "../trail.js";
+export type NotifyTemplate = "slack" | "linear" | "jira" | "generic";
+export declare const NOTIFY_TEMPLATES: readonly NotifyTemplate[];
+/** `kind` marker on the generic payload so receivers can route without inspecting fields. */
+export declare const NOTIFY_KIND = "kya.trail.verdict";
+/**
+ * The ONLY trail fields a payload may carry: ts, sessionId, toolId, verdict, reasonCode, mode,
+ * plus the optional redacted/host fields when present. argsHash, diffPreview and neverEvent are
+ * excluded by omission; the trail never holds raw args at all.
+ */
+export declare function allowedEventFields(event: TrailEvent): Record<string, string>;
+/** One-line headline shared by every template, e.g. "KYA DENY: shell.exec (NEVER_COMMAND)". */
+export declare function headline(event: TrailEvent): string;
+/** Slack incoming-webhook shape: top-level text fallback plus Block Kit blocks. */
+export declare function buildSlackPayload(event: TrailEvent): Record<string, unknown>;
+/** Linear create-issue-shaped body (title / description / priority). DENY is urgent. */
+export declare function buildLinearPayload(event: TrailEvent): Record<string, unknown>;
+/** Jira create-issue-shaped body (fields.summary / fields.description / issuetype). */
+export declare function buildJiraPayload(event: TrailEvent): Record<string, unknown>;
+/** Generic: the allow-listed event fields plus a routing kind. */
+export declare function buildGenericPayload(event: TrailEvent): Record<string, unknown>;
+export declare function buildPayload(template: NotifyTemplate, event: TrailEvent): Record<string, unknown>;
+/**
+ * Last-resort body when assertNoSecrets rejects the full payload: four fields only, no free text
+ * (summary / targetPath are the fields that could carry a leaked secret).
+ */
+export declare function buildMinimizedPayload(event: TrailEvent): Record<string, unknown>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/notify/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/notify/templates.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAErE,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAA2C,CAAC;AAElG,6FAA6F;AAC7F,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgB5E;AAED,+FAA+F;AAC/F,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAElD;AAmBD,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAe5E;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAM7E;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ3E;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWjG;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOhF"}

package/dist/notify/templates.js

@@ -0,0 +1,119 @@
+export const NOTIFY_TEMPLATES = ["slack", "linear", "jira", "generic"];
+/** `kind` marker on the generic payload so receivers can route without inspecting fields. */
+export const NOTIFY_KIND = "kya.trail.verdict";
+/**
+ * The ONLY trail fields a payload may carry: ts, sessionId, toolId, verdict, reasonCode, mode,
+ * plus the optional redacted/host fields when present. argsHash, diffPreview and neverEvent are
+ * excluded by omission; the trail never holds raw args at all.
+ */
+export function allowedEventFields(event) {
+    const out = {
+        ts: event.ts,
+        sessionId: event.sessionId,
+        toolId: event.toolId,
+        verdict: event.verdict,
+        reasonCode: event.reasonCode,
+        mode: event.mode,
+    };
+    if (event.host !== undefined)
+        out["host"] = event.host;
+    if (event.product !== undefined)
+        out["product"] = event.product;
+    if (event.project !== undefined)
+        out["project"] = event.project;
+    if (event.packId !== undefined)
+        out["packId"] = event.packId;
+    if (event.summary !== undefined)
+        out["summary"] = event.summary;
+    if (event.targetPath !== undefined)
+        out["targetPath"] = event.targetPath;
+    return out;
+}
+/** One-line headline shared by every template, e.g. "KYA DENY: shell.exec (NEVER_COMMAND)". */
+export function headline(event) {
+    return `KYA ${event.verdict}: ${event.toolId} (${event.reasonCode})`;
+}
+function descriptionLines(event) {
+    const f = allowedEventFields(event);
+    const lines = [
+        `verdict: ${f["verdict"]}`,
+        `tool: ${f["toolId"]}`,
+        `reason: ${f["reasonCode"]}`,
+        `mode: ${f["mode"]}`,
+        `session: ${f["sessionId"]}`,
+        `ts: ${f["ts"]}`,
+    ];
+    if (f["product"] !== undefined)
+        lines.push(`product: ${f["product"]}`);
+    if (f["host"] !== undefined)
+        lines.push(`host: ${f["host"]}`);
+    if (f["targetPath"] !== undefined)
+        lines.push(`target: ${f["targetPath"]}`);
+    if (f["summary"] !== undefined)
+        lines.push(`summary: ${f["summary"]}`);
+    return lines;
+}
+/** Slack incoming-webhook shape: top-level text fallback plus Block Kit blocks. */
+export function buildSlackPayload(event) {
+    const f = allowedEventFields(event);
+    const fields = ["toolId", "reasonCode", "mode", "sessionId", "ts"]
+        .map((k) => ({ type: "mrkdwn", text: `*${k}*\n${f[k]}` }));
+    if (f["targetPath"] !== undefined) {
+        fields.push({ type: "mrkdwn", text: `*target*\n${f["targetPath"]}` });
+    }
+    const blocks = [
+        { type: "header", text: { type: "plain_text", text: `KYA verdict: ${event.verdict}` } },
+        { type: "section", fields },
+    ];
+    if (f["summary"] !== undefined) {
+        blocks.push({ type: "section", text: { type: "mrkdwn", text: f["summary"] } });
+    }
+    return { text: headline(event), blocks };
+}
+/** Linear create-issue-shaped body (title / description / priority). DENY is urgent. */
+export function buildLinearPayload(event) {
+    return {
+        title: headline(event),
+        description: descriptionLines(event).join("\n"),
+        priority: event.verdict === "DENY" ? 1 : 2,
+    };
+}
+/** Jira create-issue-shaped body (fields.summary / fields.description / issuetype). */
+export function buildJiraPayload(event) {
+    return {
+        fields: {
+            summary: headline(event),
+            description: descriptionLines(event).join("\n"),
+            issuetype: { name: "Task" },
+        },
+    };
+}
+/** Generic: the allow-listed event fields plus a routing kind. */
+export function buildGenericPayload(event) {
+    return { kind: NOTIFY_KIND, event: allowedEventFields(event) };
+}
+export function buildPayload(template, event) {
+    switch (template) {
+        case "slack":
+            return buildSlackPayload(event);
+        case "linear":
+            return buildLinearPayload(event);
+        case "jira":
+            return buildJiraPayload(event);
+        default:
+            return buildGenericPayload(event);
+    }
+}
+/**
+ * Last-resort body when assertNoSecrets rejects the full payload: four fields only, no free text
+ * (summary / targetPath are the fields that could carry a leaked secret).
+ */
+export function buildMinimizedPayload(event) {
+    return {
+        toolId: event.toolId,
+        verdict: event.verdict,
+        reasonCode: event.reasonCode,
+        ts: event.ts,
+    };
+}
+//# sourceMappingURL=templates.js.map

package/dist/notify/templates.js.map

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

package/dist/offline-evaluate.d.ts

@@ -1,6 +1,6 @@
 /**
  * Offline sample policy evaluate for light-install demos.
- * Not a second production PEP — production injects HTTP evaluate against Shield.
+ * Not a second production PEP - production injects HTTP evaluate against Shield.
  * Same sample tools as docs/dev/kya-custom-tools-sample.md (R8: packs off),
  * plus the well-known host tool vocabulary in host-tools.ts.
  */
@@ -17,7 +17,7 @@ export declare function applySessionRisk(base: {
     reasonCode: string;
 };
 /**
- * Local fixture evaluate — day-1 offline demo without paid cloud or full console.
+ * Local fixture evaluate - day-1 offline demo without paid cloud or full console.
  * Doctrine: sole production PEP remains Shield HTTP; this is demo/CT only.
  */
 export declare function evaluateOffline(req: PolicyEvaluateRequest, host?: Host): PolicyEvaluateResponse;

package/dist/offline-evaluate.js

@@ -1,6 +1,6 @@
 /**
  * Offline sample policy evaluate for light-install demos.
- * Not a second production PEP — production injects HTTP evaluate against Shield.
+ * Not a second production PEP - production injects HTTP evaluate against Shield.
  * Same sample tools as docs/dev/kya-custom-tools-sample.md (R8: packs off),
  * plus the well-known host tool vocabulary in host-tools.ts.
  */
@@ -22,7 +22,7 @@ function baseTier(toolId, irreversible, actionClass) {
         return { verdict: "ALLOW", reasonCode: "ALLOW" };
     }
     // Clearly destructive admin names on a KNOWN MCP server deny outright, even
-    // when the caller declared risk signals — mirroring sample-tool NEVER.
+    // when the caller declared risk signals - mirroring sample-tool NEVER.
     const mcp = parseMcpToolId(toolId);
     if (mcp && /drop|truncate|purge|transfer/.test(mcp.tool)) {
         return { verdict: "DENY", reasonCode: "NEVER_EVENT" };
@@ -79,7 +79,7 @@ export function applySessionRisk(base, risk) {
     return base;
 }
 /**
- * Local fixture evaluate — day-1 offline demo without paid cloud or full console.
+ * Local fixture evaluate - day-1 offline demo without paid cloud or full console.
  * Doctrine: sole production PEP remains Shield HTTP; this is demo/CT only.
  */
 export function evaluateOffline(req, host = "ide") {

package/dist/orr/agentshield.d.ts

@@ -1,6 +1,6 @@
 /**
  * Optional ORR producer for affaan-m/agentshield (CLI `agentshield`).
- * Evidence only — never a PEP. Never `--fix`, never MiniClaw, never npx -y.
+ * Evidence only - never a PEP. Never `--fix`, never MiniClaw, never npx -y.
  */
 import type { OrrCoverageGap, OrrFinding } from "../commands/orr.js";
 export declare const AGENTSHIELD_PRODUCER_ID = "harness.agentshield";
@@ -23,7 +23,7 @@ export declare function buildAgentShieldArgv(absPath: string): {
 };
 export declare function redactEvidence(s: string): string;
 export declare function looksLikeRealSecret(s: string): boolean;
-/** Secrets category: judge evidence / fix.before only — never path/title text. */
+/** Secrets category: judge evidence / fix.before only - never path/title text. */
 export declare function secretsValueLooksReal(evidence: string, fixBefore: string): boolean;
 export declare function mapAgentShieldFinding(raw: unknown): OrrFinding | null;
 export declare function ingestAgentShieldReport(parsed: unknown): OrrFinding[];

package/dist/orr/agentshield.js

@@ -1,6 +1,6 @@
 /**
  * Optional ORR producer for affaan-m/agentshield (CLI `agentshield`).
- * Evidence only — never a PEP. Never `--fix`, never MiniClaw, never npx -y.
+ * Evidence only - never a PEP. Never `--fix`, never MiniClaw, never npx -y.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
@@ -65,7 +65,7 @@ export function looksLikeRealSecret(s) {
         return false;
     return false;
 }
-/** Secrets category: judge evidence / fix.before only — never path/title text. */
+/** Secrets category: judge evidence / fix.before only - never path/title text. */
 export function secretsValueLooksReal(evidence, fixBefore) {
     const value = [evidence, fixBefore].filter(Boolean).join("\n");
     if (!value.trim())
@@ -120,7 +120,7 @@ export function ingestAgentShieldReport(parsed) {
             category: "engineering_craft",
             severity: "info",
             title: "AgentShield report ingested as evidence",
-            detail: `${mapped.length} finding(s) mapped. Evidence only — not a PEP.`,
+            detail: `${mapped.length} finding(s) mapped. Evidence only - not a PEP.`,
             evidence: "harness.agentshield JSON ingest",
             source_tool: AGENTSHIELD_PRODUCER_ID,
         },
@@ -136,7 +136,7 @@ export function readAgentShieldJson(path) {
                 category: "engineering_craft",
                 severity: "info",
                 title: "AgentShield JSON not found",
-                detail: `${path} was requested as an optional producer. Evidence only — not a PEP.`,
+                detail: `${path} was requested as an optional producer. Evidence only - not a PEP.`,
                 evidence: abs,
                 source_tool: AGENTSHIELD_PRODUCER_ID,
             },

package/dist/orr/scorecard.d.ts

@@ -1,6 +1,6 @@
 /**
  * Optional ORR producer for OpenSSF Scorecard (CLI `scorecard`).
- * Evidence only — never a PEP. Never --fix, never npx -y.
+ * Evidence only - never a PEP. Never --fix, never npx -y.
  */
 import type { OrrCoverageGap, OrrFinding } from "../commands/orr.js";
 export declare const SCORECARD_PRODUCER_ID = "openssf.scorecard";

package/dist/orr/scorecard.js

@@ -1,6 +1,6 @@
 /**
  * Optional ORR producer for OpenSSF Scorecard (CLI `scorecard`).
- * Evidence only — never a PEP. Never --fix, never npx -y.
+ * Evidence only - never a PEP. Never --fix, never npx -y.
  */
 import { spawnSync } from "node:child_process";
 export const SCORECARD_PRODUCER_ID = "openssf.scorecard";
@@ -24,7 +24,7 @@ export function ingestScorecardJson(parsed, evidencePath) {
             title: "Scorecard ingested as evidence",
             detail: score === undefined
                 ? "Scorecard dump loaded. Does not ALLOW side effects."
-                : `Scorecard score=${score} (evidence only — not a PEP).`,
+                : `Scorecard score=${score} (evidence only - not a PEP).`,
             evidence: evidencePath,
             source_tool: SCORECARD_PRODUCER_ID,
         },
@@ -40,7 +40,7 @@ export function ingestScorecardJson(parsed, evidencePath) {
             category: "enterprise_readiness",
             severity: "info",
             title: `Scorecard ${name}`,
-            detail: `score=${String(checkScore ?? "n/a")} — evidence only`,
+            detail: `score=${String(checkScore ?? "n/a")} - evidence only`,
             evidence: evidencePath,
             source_tool: SCORECARD_PRODUCER_ID,
         });

package/dist/otel/exporter.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Best-effort OTLP/HTTP export of KYA verdicts as GenAI spans. Opt-in:
+ * disabled unless an endpoint is configured (env KYA_OTLP_EXPORT_ENDPOINT or
+ * "otlpExport" in .kya/config.json). Fire-and-forget: export NEVER blocks,
+ * delays, or changes a verdict. Every failure is swallowed and counted
+ * in-memory for a future status surface.
+ *
+ * Privacy: only verdict metadata ships (tool id, verdict, reason code, mode,
+ * host, session id, token counts when known). Tool args, prompts, approval
+ * bodies, and API keys are never exported - same rule as docs/otlp.md.
+ *
+ * No new dependencies: one hand-built OTLP/JSON payload and the global fetch.
+ */
+export interface OtlpExportConfig {
+    /** Base OTLP/HTTP endpoint, e.g. http://127.0.0.1:4318 ("/v1/traces" appended). */
+    readonly endpoint: string;
+    /** Extra headers (auth tokens live here or on the Collector, never in code). */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Permit plaintext http to a non-loopback host. Default false. */
+    readonly insecure?: boolean;
+}
+export interface VerdictEvent {
+    readonly ts?: string;
+    readonly sessionId: string;
+    readonly toolId: string;
+    readonly verdict: string;
+    readonly reasonCode: string;
+    readonly mode: string;
+    readonly host?: string;
+    /** GenAI usage, when the caller knows it. */
+    readonly tokensIn?: number;
+    readonly tokensOut?: number;
+}
+/** In-memory counters for a future status command; process-local only. */
+export declare function otlpExportStats(): {
+    attempted: number;
+    exported: number;
+    failed: number;
+};
+/**
+ * Resolve export config from env > parsed .kya/config.json. Accepts the parsed
+ * config object so callers that already read the file (resolveConfig) need no
+ * config.ts change. Returns undefined when disabled (no endpoint anywhere).
+ */
+export declare function resolveOtlpExportConfig(env?: NodeJS.ProcessEnv, configJson?: unknown): OtlpExportConfig | undefined;
+/** One OTLP/JSON ExportTraceServiceRequest carrying exactly one verdict span. */
+export declare function buildVerdictTracePayload(event: VerdictEvent): unknown;
+/**
+ * Export one verdict span. Never throws, never blocks the caller beyond the
+ * 2s timeout budget, and never touches the verdict itself. No-op when the
+ * config is undefined (unconfigured) or the endpoint fails the scheme check.
+ */
+export declare function exportVerdictSpan(event: VerdictEvent, config: OtlpExportConfig | undefined): Promise<void>;
+export interface OtlpExportSelfTestResult {
+    readonly ok: boolean;
+    readonly detail: string;
+}
+/**
+ * CLI-invocable self-test: POST one synthetic span and report the outcome.
+ * Unlike exportVerdictSpan it reports failure detail instead of only counting
+ * it - still never throws.
+ */
+export declare function otlpExportSelfTest(config: OtlpExportConfig | undefined): Promise<OtlpExportSelfTestResult>;
+//# sourceMappingURL=exporter.d.ts.map

package/dist/otel/exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../../src/otel/exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAUD,0EAA0E;AAC1E,wBAAgB,eAAe,IAAI;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,UAAU,CAAC,EAAE,OAAO,GACnB,gBAAgB,GAAG,SAAS,CAS9B;AA0ED,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CA8CrE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,OAAO,CAAC,wBAAwB,CAAC,CAwCnC"}