@shield-agent/kya 0.22.0 → 0.23.0

package/dist/showback/trail-usage.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Trail-usage showback (observe only). Aggregates per-event usage captured on
+ * the trail: real token counts when the host reported them, a static
+ * per-event estimate when it did not. Not a billing meter. Not a PEP -
+ * spend must never influence verdicts, so nothing here feeds the gate.
+ */
+import type { TrailEvent } from "../trail.js";
+/** Static fallback estimate for one gated tool call without reported usage. */
+export declare const STATIC_ESTIMATE_TOKENS_IN = 2000;
+export declare const STATIC_ESTIMATE_TOKENS_OUT = 500;
+export interface TrailUsageSummary {
+    readonly events: number;
+    /** Events whose token counts came from the host, not the estimate. */
+    readonly realUsageEvents: number;
+    /** events - realUsageEvents (rows priced at the static estimate). */
+    readonly estimatedEvents: number;
+    /** real + estimated, what the panel totals display. */
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly realTokensIn: number;
+    readonly realTokensOut: number;
+    readonly estimatedTokensIn: number;
+    readonly estimatedTokensOut: number;
+}
+/**
+ * Per event: prefer reported tokensIn/tokensOut; fall back to the static
+ * estimate only when the event carries no real usage at all.
+ */
+export declare function summarizeTrailUsage(events: readonly TrailEvent[]): TrailUsageSummary;
+//# sourceMappingURL=trail-usage.d.ts.map

package/dist/showback/trail-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail-usage.d.ts","sourceRoot":"","sources":["../../src/showback/trail-usage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,qEAAqE;IACrE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAQD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,UAAU,EAAE,GAC5B,iBAAiB,CA6BnB"}

package/dist/showback/trail-usage.js

@@ -0,0 +1,50 @@
+/**
+ * Trail-usage showback (observe only). Aggregates per-event usage captured on
+ * the trail: real token counts when the host reported them, a static
+ * per-event estimate when it did not. Not a billing meter. Not a PEP -
+ * spend must never influence verdicts, so nothing here feeds the gate.
+ */
+/** Static fallback estimate for one gated tool call without reported usage. */
+export const STATIC_ESTIMATE_TOKENS_IN = 2000;
+export const STATIC_ESTIMATE_TOKENS_OUT = 500;
+function realTokens(n) {
+    return typeof n === "number" && Number.isFinite(n) && n >= 0
+        ? Math.floor(n)
+        : undefined;
+}
+/**
+ * Per event: prefer reported tokensIn/tokensOut; fall back to the static
+ * estimate only when the event carries no real usage at all.
+ */
+export function summarizeTrailUsage(events) {
+    let realUsageEvents = 0;
+    let realIn = 0;
+    let realOut = 0;
+    let estimatedEvents = 0;
+    for (const e of events) {
+        const tin = realTokens(e.tokensIn);
+        const tout = realTokens(e.tokensOut);
+        if (tin !== undefined || tout !== undefined) {
+            realUsageEvents += 1;
+            realIn += tin ?? 0;
+            realOut += tout ?? 0;
+        }
+        else {
+            estimatedEvents += 1;
+        }
+    }
+    const estimatedTokensIn = estimatedEvents * STATIC_ESTIMATE_TOKENS_IN;
+    const estimatedTokensOut = estimatedEvents * STATIC_ESTIMATE_TOKENS_OUT;
+    return {
+        events: events.length,
+        realUsageEvents,
+        estimatedEvents,
+        tokensIn: realIn + estimatedTokensIn,
+        tokensOut: realOut + estimatedTokensOut,
+        realTokensIn: realIn,
+        realTokensOut: realOut,
+        estimatedTokensIn,
+        estimatedTokensOut,
+    };
+}
+//# sourceMappingURL=trail-usage.js.map

package/dist/showback/trail-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail-usage.js","sourceRoot":"","sources":["../../src/showback/trail-usage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAC9C,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAiB9C,SAAS,UAAU,CAAC,CAAqB;IACvC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC1D,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACf,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAA6B;IAE7B,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACrC,IAAI,GAAG,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5C,eAAe,IAAI,CAAC,CAAC;YACrB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC;YACnB,OAAO,IAAI,IAAI,IAAI,CAAC,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,eAAe,IAAI,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IACD,MAAM,iBAAiB,GAAG,eAAe,GAAG,yBAAyB,CAAC;IACtE,MAAM,kBAAkB,GAAG,eAAe,GAAG,0BAA0B,CAAC;IACxE,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,eAAe;QACf,eAAe;QACf,QAAQ,EAAE,MAAM,GAAG,iBAAiB;QACpC,SAAS,EAAE,OAAO,GAAG,kBAAkB;QACvC,YAAY,EAAE,MAAM;QACpB,aAAa,EAAE,OAAO;QACtB,iBAAiB;QACjB,kBAAkB;KACnB,CAAC;AACJ,CAAC"}

package/dist/sign/evidence-bundle.d.ts

@@ -1,8 +1,8 @@
 /**
- * Signed evidence bundles (v1) — the OSS half of hosted verification.
+ * Signed evidence bundles (v1) - the OSS half of hosted verification.
  * Self-signed by a locally generated ed25519 key: proves bundle integrity and
  * continuity of a key, NOT identity. Identity binding is a hosted claim.
- * node:crypto only — the package dependency list is locked.
+ * node:crypto only - the package dependency list is locked.
  */
 import { type KeyObject } from "node:crypto";
 import type { CertifyReport } from "../certify/evaluate.js";
@@ -12,7 +12,7 @@ export declare const EVIDENCE_BUNDLE_VERSION = 1;
 export interface EvidenceKey {
     readonly publicKey: KeyObject;
     readonly privateKey: KeyObject;
-    /** base64url(SPKI DER) — the `pubkey` field of every bundle. */
+    /** base64url(SPKI DER) - the `pubkey` field of every bundle. */
     readonly pubkeyB64u: string;
     /** First 16 hex chars of sha256(SPKI DER). */
     readonly fingerprint: string;
@@ -33,7 +33,7 @@ export declare function fingerprintSpki(spkiDer: Buffer): string;
 export declare function evidenceKeyFromSerialized(raw: unknown): EvidenceKey;
 /** Load the evidence signing key, generating one (mode 0600) on first use. */
 export declare function loadOrCreateEvidenceKey(env?: NodeJS.ProcessEnv): EvidenceKey;
-/** sig = base64url( ed25519_sign( canonicalJson(body) ) ) — canonicalJson from src/hash.ts. */
+/** sig = base64url( ed25519_sign( canonicalJson(body) ) ) - canonicalJson from src/hash.ts. */
 export declare function signCanonicalPayload(body: unknown, privateKey: KeyObject): string;
 /** Verify `sig` over canonicalJson(bundle without the `sig` and `pubkey` fields) using the embedded `pubkey`. */
 export declare function verifyBundleSignature(bundle: Record<string, unknown>): boolean;
@@ -45,12 +45,12 @@ export interface BundleAgent {
 }
 export interface EvidenceBundleInput {
     readonly report: CertifyReport;
-    /** Events inside report.window — the digest binds the bundle to the tape. */
+    /** Events inside report.window - the digest binds the bundle to the tape. */
     readonly windowEvents: readonly TrailEvent[];
     readonly agent?: BundleAgent;
 }
 /**
- * Build a signed evidence bundle v1 (hard cross-repo contract — see
+ * Build a signed evidence bundle v1 (hard cross-repo contract - see
  * docs/certify.md). sig = base64url(ed25519_sign(canonicalJson(body))) where
  * body is the bundle without the sig and pubkey fields (same stripping as
  * verifyBundleSignature). Self-signed: integrity + key continuity, NOT identity.

package/dist/sign/evidence-bundle.js

@@ -1,8 +1,8 @@
 /**
- * Signed evidence bundles (v1) — the OSS half of hosted verification.
+ * Signed evidence bundles (v1) - the OSS half of hosted verification.
  * Self-signed by a locally generated ed25519 key: proves bundle integrity and
  * continuity of a key, NOT identity. Identity binding is a hosted claim.
- * node:crypto only — the package dependency list is locked.
+ * node:crypto only - the package dependency list is locked.
  */
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify, } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
@@ -58,7 +58,7 @@ export function evidenceKeyFromSerialized(raw) {
         };
     }
     catch {
-        throw new UsageError("evidence key file is corrupt — regenerating (old bundles stay verifiable only with the old pubkey)");
+        throw new UsageError("evidence key file is corrupt - regenerating (old bundles stay verifiable only with the old pubkey)");
     }
 }
 /** Load the evidence signing key, generating one (mode 0600) on first use. */
@@ -103,7 +103,7 @@ export function loadOrCreateEvidenceKey(env = process.env) {
         regenerated: existed,
     };
 }
-/** sig = base64url( ed25519_sign( canonicalJson(body) ) ) — canonicalJson from src/hash.ts. */
+/** sig = base64url( ed25519_sign( canonicalJson(body) ) ) - canonicalJson from src/hash.ts. */
 export function signCanonicalPayload(body, privateKey) {
     const payload = Buffer.from(canonicalJson(body), "utf8");
     return sign(null, payload, privateKey).toString("base64url");
@@ -141,7 +141,7 @@ function clipBundleEvidence(evidence) {
         : evidence;
 }
 /**
- * Build a signed evidence bundle v1 (hard cross-repo contract — see
+ * Build a signed evidence bundle v1 (hard cross-repo contract - see
  * docs/certify.md). sig = base64url(ed25519_sign(canonicalJson(body))) where
  * body is the bundle without the sig and pubkey fields (same stripping as
  * verifyBundleSignature). Self-signed: integrity + key continuity, NOT identity.

package/dist/star-cta.d.ts

@@ -1,5 +1,5 @@
 export declare const STAR_REPO_URL = "https://github.com/The-Pixel-Boys/shield-agent";
-export declare const STAR_CTA_LINE = "Loving KYA? Star the repo \u2014 it keeps the OSS report free: https://github.com/The-Pixel-Boys/shield-agent";
+export declare const STAR_CTA_LINE = "Loving KYA? Star the repo - it keeps the OSS report free: https://github.com/The-Pixel-Boys/shield-agent";
 /** The CTA only fires once the trail has meaningful activity to report. */
 export declare const STAR_CTA_MIN_EVENTS = 10;
 export declare function starCtaFlagPath(cwd: string): string;

package/dist/star-cta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"star-cta.d.ts","sourceRoot":"","sources":["../src/star-cta.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,aAAa,mDAAmD,CAAC;AAC9E,eAAO,MAAM,aAAa,kHAA+E,CAAC;AAC1G,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAkB,GACvC,OAAO,CAkBT"}
+{"version":3,"file":"star-cta.d.ts","sourceRoot":"","sources":["../src/star-cta.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,aAAa,mDAAmD,CAAC;AAC9E,eAAO,MAAM,aAAa,6GAA+E,CAAC;AAC1G,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAkB,GACvC,OAAO,CAkBT"}

package/dist/star-cta.js

@@ -2,7 +2,7 @@
  * One-time "star the repo" CTA, printed after `kya start` / `kya receipt`
  * surface a live report URL and the trail has real activity in the window.
  * The flag lives in the project `.kya/` dir, so the CTA prints at most once
- * per project — it never gates or delays the report itself.
+ * per project - it never gates or delays the report itself.
  */
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -10,7 +10,7 @@ import { configDir } from "./config.js";
 import { atomicWriteSync } from "./fs-atomic.js";
 import { readTrailSince } from "./trail.js";
 export const STAR_REPO_URL = "https://github.com/The-Pixel-Boys/shield-agent";
-export const STAR_CTA_LINE = `Loving KYA? Star the repo — it keeps the OSS report free: ${STAR_REPO_URL}`;
+export const STAR_CTA_LINE = `Loving KYA? Star the repo - it keeps the OSS report free: ${STAR_REPO_URL}`;
 /** The CTA only fires once the trail has meaningful activity to report. */
 export const STAR_CTA_MIN_EVENTS = 10;
 export function starCtaFlagPath(cwd) {
@@ -40,7 +40,7 @@ export function maybePrintStarCta(cwd, days, log = console.log) {
             atomicWriteSync(starCtaFlagPath(cwd), `${new Date().toISOString()}\n`);
         }
         catch {
-            /* flag persistence is best-effort — worst case the CTA prints again */
+            /* flag persistence is best-effort - worst case the CTA prints again */
         }
         return true;
     }

package/dist/trail-summary.d.ts

@@ -1,7 +1,7 @@
 /** Strip query/fragment from URLs before they enter the summary. */
 export declare function scrubUrl(value: string): string;
 /**
- * Shell lines: keep bin + arg count only — never the full command
+ * Shell lines: keep bin + arg count only - never the full command
  * (env assignments, -p passwords, Basic auth headers).
  */
 export declare function summarizeShellCommand(cmd: string): string;

package/dist/trail-summary.js

@@ -124,14 +124,14 @@ export function scrubUrl(value) {
     return value.replace(/([?&#][^=\s]*=)[^&\s#]+/g, "$1[redacted]");
 }
 /**
- * Shell lines: keep bin + arg count only — never the full command
+ * Shell lines: keep bin + arg count only - never the full command
  * (env assignments, -p passwords, Basic auth headers).
  */
 export function summarizeShellCommand(cmd) {
     const trimmed = cmd.trim();
     if (!trimmed)
         return "shell";
-    // Space-free URL masquerading as a "command" — scrub query before binning.
+    // Space-free URL masquerading as a "command" - scrub query before binning.
     if (!/\s/.test(trimmed) && (/^[a-z][a-z0-9+.-]*:/i.test(trimmed) || /[?&#].*=/.test(trimmed))) {
         return finalize([`shell`, pathLike(trimmed)]) ?? "shell";
     }
@@ -223,7 +223,7 @@ export function deriveTrailSummary(toolId, args) {
         return undefined;
     }
     if (typeof args === "string") {
-        // Treat bare strings as opaque — only length, avoid dumping secrets.
+        // Treat bare strings as opaque - only length, avoid dumping secrets.
         return finalize([verb || "args", `(${args.length} chars)`]);
     }
     if (typeof args === "number" || typeof args === "boolean") {

package/dist/trail.d.ts

@@ -20,11 +20,17 @@ export interface TrailEvent {
     readonly diffPreview?: string;
     /** Clipped redacted target file path (never raw args). */
     readonly targetPath?: string;
+    /** Wall latency of the evaluate call in ms. Observe-only; never a verdict input. */
+    readonly latencyMs?: number;
+    /** Real input tokens reported by the host. Observe-only showback. */
+    readonly tokensIn?: number;
+    /** Real output tokens reported by the host. Observe-only showback. */
+    readonly tokensOut?: number;
 }
 export declare function globalTrailPath(env?: NodeJS.ProcessEnv): string;
 /** Pre-0.3.0 per-project trail location, still merged on read. */
 export declare function legacyTrailPath(cwd: string): string;
-/** The trail is global since 0.3.0 — one file for all projects. */
+/** The trail is global since 0.3.0 - one file for all projects. */
 export declare function trailPath(_cwd: string, env?: NodeJS.ProcessEnv): string;
 export declare function receiptsDir(cwd: string): string;
 /** Detect Cursor / Claude Code / Codex / Grok / host from env. */
@@ -33,7 +39,7 @@ export declare function productLabel(p: TrailProduct | undefined): string;
 /** Map a hook --host id to the trail product (explicit beats env sniffing). */
 export declare function hostToProduct(host: string): TrailProduct;
 export declare function appendTrail(cwd: string, event: TrailEvent, env?: NodeJS.ProcessEnv): void;
-/** trail.jsonl read cap — oversized files are tail-read (recent events win). */
+/** trail.jsonl read cap - oversized files are tail-read (recent events win). */
 export declare const MAX_TRAIL_BYTES: number;
 /**
  * Global trail + legacy per-cwd trail (pre-0.3.0 installs), merged and sorted

package/dist/trail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trail.d.ts","sourceRoot":"","sources":["../src/trail.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,MAAM,GACN,MAAM,GACN,KAAK,GACL,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,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,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE5E;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEpF;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,CAAC,EAAE,MAAM,GACZ,YAAY,CAed;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAmBhE;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAexD;AAED,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,IAAI,CAQN;AAsDD,gFAAgF;AAChF,eAAO,MAAM,eAAe,QAAc,CAAC;AAqC3C;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,EAAE,CAazF;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,IAAI,EACX,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,UAAU,EAAE,CAOd;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAO7E"}
+{"version":3,"file":"trail.d.ts","sourceRoot":"","sources":["../src/trail.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,MAAM,GACN,MAAM,GACN,KAAK,GACL,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,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,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE5E;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEpF;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,CAAC,EAAE,MAAM,GACZ,YAAY,CAed;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAmBhE;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAexD;AAED,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,IAAI,CAQN;AAoED,gFAAgF;AAChF,eAAO,MAAM,eAAe,QAAc,CAAC;AAqC3C;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,EAAE,CAazF;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,IAAI,EACX,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,UAAU,EAAE,CAOd;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAO7E"}

package/dist/trail.js

@@ -1,5 +1,5 @@
 /**
- * Local session trail (JSONL). Observe path — not a second PEP.
+ * Local session trail (JSONL). Observe path - not a second PEP.
  */
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, } from "node:fs";
 import { basename, join } from "node:path";
@@ -11,7 +11,7 @@ export function globalTrailPath(env = process.env) {
 export function legacyTrailPath(cwd) {
     return join(configDir(cwd), "trail.jsonl");
 }
-/** The trail is global since 0.3.0 — one file for all projects. */
+/** The trail is global since 0.3.0 - one file for all projects. */
 export function trailPath(_cwd, env = process.env) {
     return globalTrailPath(env);
 }
@@ -97,7 +97,7 @@ const TRAIL_PRODUCTS = new Set([
 ]);
 /**
  * Validate one parsed JSONL line against the TrailEvent shape. Untrusted
- * fields (wrong type, unknown mode/product) drop the line or the field —
+ * fields (wrong type, unknown mode/product) drop the line or the field -
  * a single malformed line must never brick the report render.
  */
 function parseTrailEvent(raw) {
@@ -131,9 +131,22 @@ function parseTrailEvent(raw) {
         ...(typeof e.summary === "string" ? { summary: e.summary } : {}),
         ...(typeof e.diffPreview === "string" ? { diffPreview: e.diffPreview } : {}),
         ...(typeof e.targetPath === "string" ? { targetPath: e.targetPath } : {}),
+        ...(nonNegNumber(e.latencyMs) !== undefined
+            ? { latencyMs: nonNegNumber(e.latencyMs) }
+            : {}),
+        ...(nonNegNumber(e.tokensIn) !== undefined
+            ? { tokensIn: nonNegNumber(e.tokensIn) }
+            : {}),
+        ...(nonNegNumber(e.tokensOut) !== undefined
+            ? { tokensOut: nonNegNumber(e.tokensOut) }
+            : {}),
     };
 }
-/** trail.jsonl read cap — oversized files are tail-read (recent events win). */
+/** Usage/latency fields pass only as finite non-negative numbers. */
+function nonNegNumber(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : undefined;
+}
+/** trail.jsonl read cap - oversized files are tail-read (recent events win). */
 export const MAX_TRAIL_BYTES = 1024 * 1024;
 function readTrailText(path) {
     const size = statSync(path).size;
@@ -151,7 +164,7 @@ function readTrailText(path) {
     finally {
         closeSync(fd);
     }
-    // First line is partial (possibly mid-multibyte) — drop it.
+    // First line is partial (possibly mid-multibyte) - drop it.
     const nl = tail.indexOf("\n");
     return nl === -1 ? "" : tail.slice(nl + 1);
 }

package/dist/trail.js.map

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

package/dist/update-check.d.ts

@@ -0,0 +1,17 @@
+export interface UpdateCheckResult {
+    readonly current: string;
+    readonly latest: string;
+}
+export declare function shouldSkipUpdateCheck(command: string | undefined, flags: Readonly<Record<string, string | boolean>>, env: NodeJS.ProcessEnv): boolean;
+export declare function compareVersions(a: string, b: string): number;
+export interface UpdateCheckDeps {
+    readonly fetch?: typeof fetch;
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * Returns { current, latest } when a newer version is available on npm,
+ * undefined when already up-to-date, offline, or the check failed.
+ */
+export declare function checkForUpdate(deps?: UpdateCheckDeps): Promise<UpdateCheckResult | undefined>;
+export declare function formatUpdateBanner(result: UpdateCheckResult): string;
+//# sourceMappingURL=update-check.d.ts.map

package/dist/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAmBD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EACjD,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,OAAO,CAQT;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAU5D;AA6DD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAcvG;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAEpE"}

package/dist/update-check.js

@@ -0,0 +1,134 @@
+/**
+ * Lightweight "new KYA version available" check.
+ *
+ * - Queries npm registry at most once per 24 h and caches the result in
+ *   ~/.kya/update-check.json.
+ * - Never fails a command: network/cache problems return undefined.
+ * - Honors KYA_UPDATE_CHECK=0 and --no-update-check.
+ * - Skips machine-readable/integrated subcommands so hosts aren't confused.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { globalConfigDir } from "./config.js";
+import { CLI_VERSION } from "./version.js";
+const NPM_REGISTRY_URL = "https://registry.npmjs.org/@shield-agent%2Fkya";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+/** Commands whose output is consumed by hosts, scripts, or pipes. */
+const SKIP_COMMANDS = new Set([
+    "serve-mcp",
+    "receipt-serve",
+    "hook",
+    "wrap",
+    "eval-tool",
+    "invoke",
+    "approve",
+    "reject",
+]);
+export function shouldSkipUpdateCheck(command, flags, env) {
+    if (!command)
+        return true;
+    if (SKIP_COMMANDS.has(command))
+        return true;
+    if (flags["no-update-check"] === true || flags["no-update-check"] === "true")
+        return true;
+    if (env.KYA_UPDATE_CHECK === "0" || env.KYA_UPDATE_CHECK === "false")
+        return true;
+    if (env.CI === "true" || env.GITHUB_ACTIONS === "true")
+        return true;
+    if (flags["json"] === true || flags["json"] === "true")
+        return true;
+    return false;
+}
+export function compareVersions(a, b) {
+    const parse = (v) => v.replace(/^v/, "").split(".").map((n) => Number.parseInt(n, 10));
+    const av = parse(a);
+    const bv = parse(b);
+    for (let i = 0; i < 3; i++) {
+        const an = Number.isFinite(av[i]) ? av[i] : 0;
+        const bn = Number.isFinite(bv[i]) ? bv[i] : 0;
+        if (an !== bn)
+            return an - bn;
+    }
+    return 0;
+}
+function cachePath(env) {
+    return `${globalConfigDir(env)}/update-check.json`;
+}
+function readCache(env) {
+    try {
+        const raw = readFileSync(cachePath(env), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.latest === "string" && typeof parsed.checkedAt === "string") {
+            return parsed;
+        }
+    }
+    catch {
+        /* ignore corrupt/missing cache */
+    }
+    return undefined;
+}
+function writeCache(latest, env) {
+    try {
+        const dir = globalConfigDir(env);
+        mkdirSync(dir, { recursive: true });
+        const cache = { latest, checkedAt: new Date().toISOString() };
+        writeFileSync(cachePath(env), `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+    }
+    catch {
+        /* ignore write failures */
+    }
+}
+function cacheFresh(cache) {
+    try {
+        const checked = new Date(cache.checkedAt).getTime();
+        return Number.isFinite(checked) && Date.now() - checked < CACHE_TTL_MS;
+    }
+    catch {
+        return false;
+    }
+}
+async function fetchLatestVersion(env, fetchImpl = fetch) {
+    if (env.KYA_OFFLINE === "1" || env.KYA_OFFLINE === "true")
+        return undefined;
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        const res = await fetchImpl(NPM_REGISTRY_URL, {
+            signal: controller.signal,
+            headers: { Accept: "application/json" },
+        });
+        clearTimeout(timeout);
+        if (!res.ok)
+            return undefined;
+        const data = (await res.json());
+        const latest = data?.["dist-tags"]?.latest;
+        return typeof latest === "string" && latest ? latest : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Returns { current, latest } when a newer version is available on npm,
+ * undefined when already up-to-date, offline, or the check failed.
+ */
+export async function checkForUpdate(deps = {}) {
+    const env = deps.env ?? process.env;
+    const cache = readCache(env);
+    let latest = cache && cacheFresh(cache) ? cache.latest : undefined;
+    if (!latest) {
+        latest = await fetchLatestVersion(env, deps.fetch);
+        if (latest)
+            writeCache(latest, env);
+    }
+    if (!latest)
+        return undefined;
+    const current = CLI_VERSION;
+    if (compareVersions(latest, current) <= 0)
+        return undefined;
+    return { current, latest };
+}
+export function formatUpdateBanner(result) {
+    return `A new version of KYA is available: ${result.latest} (you have ${result.current}).\nRun: kya update\nOr:  npm i -g @shield-agent/kya@latest`;
+}
+//# sourceMappingURL=update-check.js.map

package/dist/update-check.js.map

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

package/droid/README.md

@@ -1,6 +1,6 @@
 # Droid (Factory) + Shield KYA
 
-Preferred path is Droid's own CLI: `droid mcp add shield-kya "npx --no-install @shield-agent/kya@0.22.0 serve-mcp --stdio" --env KYA_BASE_URL=https://shield-agent.com --env KYA_API_KEY=$KYA_API_KEY --env KYA_HOST=ide`.
+Preferred path is Droid's own CLI: `droid mcp add shield-kya "npx --no-install @shield-agent/kya@0.23.0 serve-mcp --stdio" --env KYA_BASE_URL=https://shield-agent.com --env KYA_API_KEY=$KYA_API_KEY --env KYA_HOST=ide`.
 
 `mcp.example.json` shows the expected on-disk shape (`~/.factory/mcp.json`) — **schema not yet verified against a live Droid install**; treat as a starting point and prefer `droid mcp add`.
 

package/droid/mcp.example.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.22.0", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.23.0", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "https://shield-agent.com",
         "KYA_API_KEY": "${KYA_API_KEY}",

package/gemini/settings.example.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.22.0", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.23.0", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "https://shield-agent.com",
         "KYA_API_KEY": "${KYA_API_KEY}",

package/grok/README.md

@@ -40,7 +40,7 @@ chat = client.chat.create(
 There is no grok.com stdio path. For a local agent host use the same stdio launch as Claude:
 
 ```bash
-npx --no-install @shield-agent/kya@0.22.0 serve-mcp --stdio
+npx --no-install @shield-agent/kya@0.23.0 serve-mcp --stdio
 ```
 
 Env: `KYA_BASE_URL`, `KYA_API_KEY`, `KYA_HOST`. Codex and Gemini example configs in this package show the full snippets.

package/kilo/kilo.example.json

@@ -2,7 +2,7 @@
   "mcp": {
     "shield-kya": {
       "type": "local",
-      "command": ["npx", "--no-install", "@shield-agent/kya@0.22.0", "serve-mcp", "--stdio"],
+      "command": ["npx", "--no-install", "@shield-agent/kya@0.23.0", "serve-mcp", "--stdio"],
       "enabled": true,
       "environment": {
         "KYA_BASE_URL": "https://shield-agent.com",

package/kimi/mcp.example.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.22.0", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.23.0", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "https://shield-agent.com",
         "KYA_API_KEY": "${KYA_API_KEY}",

package/kiro/mcp.example.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.22.0", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.23.0", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "https://shield-agent.com",
         "KYA_API_KEY": "${KYA_API_KEY}",