@shield-agent/kya 0.22.0 → 0.23.1

package/dist/receipt/share.js

@@ -1,10 +1,10 @@
 /**
- * `kya receipt --share` — publish a redacted summary of the current report
+ * `kya receipt --share` - publish a redacted summary of the current report
  * window to the hosted platform and get back a public URL.
  *
  * The payload is built FROM THE RECEIPT MODEL, never from the raw trail:
  * aggregate counts and public labels only. No absolute paths, no session ids,
- * no tool arguments, no identity (baseUrl/IP) — anything that could identify
+ * no tool arguments, no identity (baseUrl/IP) - anything that could identify
  * a machine, project, or person stays local. Dependency-free: global fetch.
  */
 import { CLI_VERSION } from "../version.js";
@@ -94,7 +94,7 @@ export function clampShareRetries(raw) {
         return 0;
     return Math.min(n, SHARE_MAX_RETRIES);
 }
-/** POST the payload; 15s timeout. Never throws — failures come back as {ok:false}. */
+/** POST the payload; 15s timeout. Never throws - failures come back as {ok:false}. */
 export async function shareReceiptPayload(payload, opts) {
     const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
     const controller = new AbortController();
@@ -124,8 +124,8 @@ export async function shareReceiptPayload(payload, opts) {
                     status: 429,
                     retryAfterSeconds,
                     error: retryAfterSeconds != null
-                        ? `share failed: rate limited — retry in ~${retryAfterSeconds}s`
-                        : "share failed: rate limited — retry later",
+                        ? `share failed: rate limited - retry in ~${retryAfterSeconds}s`
+                        : "share failed: rate limited - retry later",
                 };
             }
             return { ok: false, status: res.status, error: `share failed: HTTP ${res.status}` };

package/dist/sample-tools.d.ts

@@ -1,5 +1,5 @@
 /**
- * Sample custom tools for light install — zero vertical packs (R8).
+ * Sample custom tools for light install - zero vertical packs (R8).
  * Same descriptors as docs/dev/kya-custom-tools-sample.md.
  */
 export type ActionClass = "READ" | "WRITE" | "EXTERNAL_SIDE_EFFECT" | "EXPORT";

package/dist/sample-tools.js

@@ -1,5 +1,5 @@
 /**
- * Sample custom tools for light install — zero vertical packs (R8).
+ * Sample custom tools for light install - zero vertical packs (R8).
  * Same descriptors as docs/dev/kya-custom-tools-sample.md.
  */
 export const SAMPLE_TOOLS = [

package/dist/sandbox/mock-driver.d.ts

@@ -1,5 +1,5 @@
 import type { SandboxDriver } from "./types.js";
-/** In-memory driver for unit tests — never talks to a real VMM. */
+/** In-memory driver for unit tests - never talks to a real VMM. */
 export declare function createMockDriver(): SandboxDriver & {
     readonly live: Set<string>;
 };

package/dist/sandbox/mock-driver.js

@@ -1,4 +1,4 @@
-/** In-memory driver for unit tests — never talks to a real VMM. */
+/** In-memory driver for unit tests - never talks to a real VMM. */
 export function createMockDriver() {
     const live = new Set();
     return {

package/dist/sdk/a2a.d.ts

@@ -4,7 +4,7 @@
  * performs the send. `a2a` is a registry-unknown server, so offline evaluate
  * lands on the safe REQUIRE_APPROVE/UNKNOWN path unless the action is
  * declared irreversible. Fleet-level A2A governance (mTLS identity, org
- * policy between runtimes) is the kya gateway's job — this is the
+ * policy between runtimes) is the kya gateway's job - this is the
  * single-process complement.
  */
 import type { ResolvedConfig } from "../config.js";
@@ -12,7 +12,7 @@ export interface GovernA2aSendOptions {
     readonly peerId: string;
     readonly peerUrl?: string;
     readonly action: string;
-    /** Short human description of the payload — trail summary only, never the body. */
+    /** Short human description of the payload - trail summary only, never the body. */
     readonly payloadSummary?: string;
     readonly irreversible?: boolean;
     readonly config?: ResolvedConfig;

package/dist/sdk/a2a.js

@@ -4,7 +4,7 @@
  * performs the send. `a2a` is a registry-unknown server, so offline evaluate
  * lands on the safe REQUIRE_APPROVE/UNKNOWN path unless the action is
  * declared irreversible. Fleet-level A2A governance (mTLS identity, org
- * policy between runtimes) is the kya gateway's job — this is the
+ * policy between runtimes) is the kya gateway's job - this is the
  * single-process complement.
  */
 import { runEvalTool } from "../commands/eval-tool.js";

package/dist/sdk/adapters/claude-agent.d.ts

@@ -1,5 +1,5 @@
 /**
- * Anthropic Agent SDK tool adapter. Structural only — no
+ * Anthropic Agent SDK tool adapter. Structural only - no
  * @anthropic-ai/claude-agent-sdk import. Matches the
  * `{ name, description, inputSchema, handler }` in-process tool shape where
  * handler receives parsed args plus SDK extras; returns the same shape with

package/dist/sdk/adapters/claude-agent.js

@@ -1,5 +1,5 @@
 /**
- * Anthropic Agent SDK tool adapter. Structural only — no
+ * Anthropic Agent SDK tool adapter. Structural only - no
  * @anthropic-ai/claude-agent-sdk import. Matches the
  * `{ name, description, inputSchema, handler }` in-process tool shape where
  * handler receives parsed args plus SDK extras; returns the same shape with

package/dist/sdk/adapters/langgraph.d.ts

@@ -1,5 +1,5 @@
 /**
- * LangGraph.js-style tool adapter. Structural only — no @langgraph imports.
+ * LangGraph.js-style tool adapter. Structural only - no @langgraph imports.
  * Matches the `{ name, description, schema, func }` tool shape; returns the
  * same shape with a governed func.
  */

package/dist/sdk/adapters/langgraph.js

@@ -1,5 +1,5 @@
 /**
- * LangGraph.js-style tool adapter. Structural only — no @langgraph imports.
+ * LangGraph.js-style tool adapter. Structural only - no @langgraph imports.
  * Matches the `{ name, description, schema, func }` tool shape; returns the
  * same shape with a governed func.
  */

package/dist/sdk/adapters/mastra.d.ts

@@ -1,5 +1,5 @@
 /**
- * Mastra-style tool adapter. Structural only — no @mastra imports. Matches
+ * Mastra-style tool adapter. Structural only - no @mastra imports. Matches
  * the `{ id, description, inputSchema, execute }` tool shape; returns the
  * same shape with a governed execute.
  */

package/dist/sdk/adapters/mastra.js

@@ -1,5 +1,5 @@
 /**
- * Mastra-style tool adapter. Structural only — no @mastra imports. Matches
+ * Mastra-style tool adapter. Structural only - no @mastra imports. Matches
  * the `{ id, description, inputSchema, execute }` tool shape; returns the
  * same shape with a governed execute.
  */

package/dist/sdk/adapters/openai-agents.d.ts

@@ -1,5 +1,5 @@
 /**
- * OpenAI Agents TS function-tool adapter. Structural only — no
+ * OpenAI Agents TS function-tool adapter. Structural only - no
  * @openai/agents import. Matches the `{ name, description, parameters,
  * invoke }` function-tool shape where invoke receives the run context and a
  * JSON string input; returns the same shape with a governed invoke. The

package/dist/sdk/adapters/openai-agents.js

@@ -1,5 +1,5 @@
 /**
- * OpenAI Agents TS function-tool adapter. Structural only — no
+ * OpenAI Agents TS function-tool adapter. Structural only - no
  * @openai/agents import. Matches the `{ name, description, parameters,
  * invoke }` function-tool shape where invoke receives the run context and a
  * JSON string input; returns the same shape with a governed invoke. The

package/dist/sdk/adapters/vercel-ai.d.ts

@@ -1,5 +1,5 @@
 /**
- * Vercel AI SDK tool adapter. Structural only — no `ai` import. Matches the
+ * Vercel AI SDK tool adapter. Structural only - no `ai` import. Matches the
  * `{ description, parameters, execute }` tool shape; returns the same shape
  * with a governed execute. AI SDK tools are keyed by name in the tools
  * record, so the name is an explicit adapter option.
@@ -11,7 +11,7 @@ export interface VercelAiToolLike<TArgs = unknown, TResult = unknown> {
     readonly execute: (args: TArgs) => Promise<TResult> | TResult;
 }
 export interface GovernVercelAiOptions extends GovernanceOptions {
-    /** Tool name — the key this definition is registered under. */
+    /** Tool name - the key this definition is registered under. */
     readonly name: string;
 }
 export declare function governVercelAiTool<TArgs, TResult>(tool: VercelAiToolLike<TArgs, TResult>, options: GovernVercelAiOptions): VercelAiToolLike<TArgs, TResult>;

package/dist/sdk/adapters/vercel-ai.js

@@ -1,5 +1,5 @@
 /**
- * Vercel AI SDK tool adapter. Structural only — no `ai` import. Matches the
+ * Vercel AI SDK tool adapter. Structural only - no `ai` import. Matches the
  * `{ description, parameters, execute }` tool shape; returns the same shape
  * with a governed execute. AI SDK tools are keyed by name in the tools
  * record, so the name is an explicit adapter option.

package/dist/sdk/govern.d.ts

@@ -1,12 +1,12 @@
 /**
  * In-process governance shim: evaluate a tool call through the same path
- * `kya wrap` uses (offline sample evaluate by default — no network, no hosted
+ * `kya wrap` uses (offline sample evaluate by default - no network, no hosted
  * plane required), record the trail event, then ALLOW/REQUIRE_APPROVE run the
  * function while DENY throws KyaDeniedError without running it.
  *
  * Importing this module starts nothing: config resolves lazily on first call.
  *
- * Deliberate coupling: the trail write is fail-closed — a governance shim
+ * Deliberate coupling: the trail write is fail-closed - a governance shim
  * where the audit record cannot be written does not run the action.
  */
 import type { ResolvedConfig } from "../config.js";

package/dist/sdk/govern.js

@@ -1,12 +1,12 @@
 /**
  * In-process governance shim: evaluate a tool call through the same path
- * `kya wrap` uses (offline sample evaluate by default — no network, no hosted
+ * `kya wrap` uses (offline sample evaluate by default - no network, no hosted
  * plane required), record the trail event, then ALLOW/REQUIRE_APPROVE run the
  * function while DENY throws KyaDeniedError without running it.
  *
  * Importing this module starts nothing: config resolves lazily on first call.
  *
- * Deliberate coupling: the trail write is fail-closed — a governance shim
+ * Deliberate coupling: the trail write is fail-closed - a governance shim
  * where the audit record cannot be written does not run the action.
  */
 import { resolveConfig } from "../config.js";
@@ -19,7 +19,7 @@ export class KyaDeniedError extends KyaError {
     reasonCode;
     toolId;
     constructor(input) {
-        super(`kya ${input.verdict}: ${input.toolId} (${input.reasonCode || "no reason"}) — function not executed`, "KYA_DENIED", 1);
+        super(`kya ${input.verdict}: ${input.toolId} (${input.reasonCode || "no reason"}) - function not executed`, "KYA_DENIED", 1);
         this.name = "KyaDeniedError";
         this.verdict = input.verdict;
         this.reasonCode = input.reasonCode;

package/dist/sdk/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @shield-agent/kya/sdk — in-process governance shims for agent frameworks.
+ * @shield-agent/kya/sdk - in-process governance shims for agent frameworks.
  * Importing this surface starts no daemons, telemetry, or network clients;
  * evaluation defaults to the offline sample path.
  */

package/dist/sdk/index.js

@@ -1,5 +1,5 @@
 /**
- * @shield-agent/kya/sdk — in-process governance shims for agent frameworks.
+ * @shield-agent/kya/sdk - in-process governance shims for agent frameworks.
  * Importing this surface starts no daemons, telemetry, or network clients;
  * evaluation defaults to the offline sample path.
  */

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);
 }