@shield-agent/kya 0.21.0 → 0.23.0

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/telemetry.d.ts

@@ -0,0 +1,135 @@
+export type TelemetrySurface = "mcp-stdio" | "mcp-http" | "report" | "gateway" | "hook";
+export type TelemetryEventKind = "start" | "heartbeat" | "end" | "ping";
+export interface TelemetryState {
+    /** true = opted in, false = opted out, undefined = never answered. */
+    readonly enabled?: boolean;
+    /** Random UUID, created only when the user opts in. Never derived from the machine or user. */
+    readonly installId?: string;
+    /** When the question was answered; its presence means "do not ask again". */
+    readonly askedAt?: string;
+}
+export interface TelemetryPayload {
+    readonly schema: 1;
+    readonly installId: string;
+    readonly sessionId: string;
+    readonly event: TelemetryEventKind;
+    readonly surface: TelemetrySurface;
+    readonly cliVersion: string;
+    readonly os: string;
+    readonly arch: string;
+    readonly nodeMajor: number;
+    readonly hostId: string;
+    readonly gateMode: string;
+    readonly hostedLinked: boolean;
+}
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Pick<Response, "ok" | "status">>;
+export declare const DEFAULT_TELEMETRY_ENDPOINT = "https://shield-agent.com/api/v1/telemetry/kya";
+export declare function telemetryStatePath(env: NodeJS.ProcessEnv): string;
+/** Tolerant read: a missing, corrupt or hand-edited file is "never asked", never an error. */
+export declare function readTelemetryState(env: NodeJS.ProcessEnv): TelemetryState;
+export declare function writeTelemetryState(env: NodeJS.ProcessEnv, state: TelemetryState): void;
+/** Why telemetry is forced off for THIS process regardless of the saved answer, or undefined. */
+export declare function telemetryDisabledReason(env: NodeJS.ProcessEnv): string | undefined;
+/** True only when the user opted in AND nothing overrides it for this process. */
+export declare function isTelemetryEnabled(env: NodeJS.ProcessEnv): boolean;
+/** https, or http on a loopback host (tests, self-hosting). Anything else falls back to the default. */
+export declare function telemetryEndpoint(env: NodeJS.ProcessEnv): string;
+/** Host registry slug from the session id `kya connect` writes (`mcp:<host>`), else "unknown". */
+export declare function telemetryHostId(env: NodeJS.ProcessEnv): string;
+/**
+ * The ONLY fields that ever leave the machine. A test pins this exact key set; adding a field here
+ * is a privacy change that needs the server validator, docs/telemetry.md and the privacy page updated.
+ */
+export declare function buildPayload(input: {
+    readonly installId: string;
+    readonly sessionId: string;
+    readonly event: TelemetryEventKind;
+    readonly surface: TelemetrySurface;
+    readonly env: NodeJS.ProcessEnv;
+    readonly cwd: string;
+}): TelemetryPayload;
+/**
+ * POST one JSON body. Returns whether the server accepted it. Never throws: telemetry must not be
+ * able to change what the CLI does, so every failure (network, timeout, redirect, non-2xx) is just
+ * `false`. The deliberate swallow is the whole point of this function.
+ */
+export declare function postTelemetry(url: string, body: unknown, fetchImpl?: FetchLike): Promise<boolean>;
+export interface SessionBeacon {
+    /** Sends `end` (bounded by the send timeout) and stops the heartbeat. Idempotent. */
+    stop(): Promise<void>;
+}
+/**
+ * Start reporting for one long-lived process. A no-op unless the user opted in and nothing overrides
+ * it. Writes NOTHING to stdout or stderr (an MCP stdio process owns stdout as its protocol channel).
+ */
+export declare function startSessionBeacon(surface: TelemetrySurface, deps: {
+    readonly env: NodeJS.ProcessEnv;
+    readonly cwd: string;
+    readonly fetchImpl?: FetchLike;
+    readonly intervalMs?: number;
+}): SessionBeacon;
+/** At most one ping per this window, however many tool calls fire the hook. */
+export declare const HOOK_PING_INTERVAL_MS: number;
+/** Its mtime is the time of the last ping attempt. Content is empty: nothing to leak or corrupt. */
+export declare function hookPingStampPath(env: NodeJS.ProcessEnv): string;
+type SpawnLike = (command: string, args: readonly string[], options: {
+    detached: boolean;
+    stdio: "ignore";
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    windowsHide: boolean;
+}) => {
+    unref(): void;
+    on(event: "error", listener: () => void): unknown;
+};
+/**
+ * Claims today's ping slot: true for exactly one caller per interval. A fresh stamp means someone
+ * already did; a stale one is removed and re-created with an exclusive create (`wx`), so of several
+ * hooks racing on a stale stamp only the one whose create succeeds gets the slot.
+ */
+export declare function claimHookPingSlot(env: NodeJS.ProcessEnv, nowMs?: number): boolean;
+/**
+ * Called by `kya hook` after it has produced its answer. Cheap on the hot path: when telemetry is off
+ * or a ping already went out today this is one file read and one stat. Otherwise it claims the day's
+ * slot (see {@link claimHookPingSlot}) and starts the helper detached with ignored stdio, so the
+ * hook's stdout, stderr and exit code are untouched and it never waits. `host` is the hook's `--host`
+ * (claude, grok, ...), handed to the helper so the host mix stays meaningful for hook-only installs.
+ * A failed ping is not retried until tomorrow: a spawn storm while offline would be worse than a gap.
+ * Never throws. Returns whether a helper was started.
+ */
+export declare function maybeSpawnHookPing(deps: {
+    readonly env: NodeJS.ProcessEnv;
+    readonly cwd: string;
+    readonly host?: string;
+    readonly entry?: string;
+    readonly spawnImpl?: SpawnLike;
+    readonly nowMs?: number;
+}): boolean;
+/** The helper's job (`kya telemetry ping`): one `ping` as surface `hook`, same gates as every beacon. */
+export declare function sendHookPing(env: NodeJS.ProcessEnv, cwd: string, fetchImpl?: FetchLike): Promise<boolean>;
+export interface ConsentIo {
+    readonly error: (msg: string) => void;
+    /** Test seam: force interactive / non-interactive. Defaults to "stdin and stderr are TTYs". */
+    readonly isTty?: boolean;
+    /** Test seam: returns the raw answer line. Defaults to a readline prompt on stdin/stderr. */
+    readonly ask?: (question: string) => Promise<string>;
+}
+export declare const CONSENT_NOTICE: string[];
+/**
+ * Ask once, on an interactive terminal, in the setup commands (`start`, `init`, `connect`). Strict
+ * opt-in: only an explicit `y` / `yes` enables; empty input, anything else, or closing the prompt is No.
+ * Skipped when already answered, when an override forces telemetry off, and when not interactive
+ * (nothing is saved then, so the next interactive run can ask).
+ */
+export declare function maybePromptConsent(io: ConsentIo, env: NodeJS.ProcessEnv): Promise<"yes" | "no" | "skipped">;
+export interface TelemetryCommandIo {
+    readonly log: (msg: string) => void;
+    readonly error: (msg: string) => void;
+}
+export declare function runTelemetryCommand(input: {
+    readonly sub: string | undefined;
+    readonly purge: boolean;
+    readonly json: boolean;
+}, io: TelemetryCommandIo, env: NodeJS.ProcessEnv, cwd: string, fetchImpl?: FetchLike): Promise<number>;
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

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