@shield-agent/kya 0.1.29 → 0.1.31

package/dist/trail-summary.js

@@ -0,0 +1,254 @@
+/**
+ * Short human summary for trail/receipt.
+ * Picks safe fields (path / shell bin / size hint), runs redactEvidence, clips to 80 chars.
+ * Never serializes full args or body/content values.
+ */
+import { redactEvidence } from "./orr/agentshield.js";
+const MAX_LEN = 80;
+const PATH_KEYS = [
+    "path",
+    "file",
+    "filepath",
+    "file_path",
+    "filePath",
+    "target",
+    "uri",
+    "url",
+    "destination",
+    "dest",
+];
+const CMD_KEYS = ["command", "cmd", "script", "shell", "argv"];
+const OP_KEYS = ["op", "operation", "action", "method", "mode"];
+/** Exact keys we never surface as values (bodies + common secret names). */
+const SKIP_KEYS = new Set([
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "apikey",
+    "api_key",
+    "authorization",
+    "auth",
+    "cookie",
+    "content",
+    "body",
+    "data",
+    "text",
+    "code",
+    "diff",
+    "patch",
+    "payload",
+    "raw",
+    "accesstoken",
+    "access_token",
+    "refreshtoken",
+    "refresh_token",
+    "client_secret",
+    "clientsecret",
+    "private_key",
+    "privatekey",
+    "credential",
+    "credentials",
+]);
+const SENSITIVE_KEY_RE = /(secret|token|password|passwd|credential|authorization|apikey|api[_-]?key|private[_-]?key)/i;
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isSensitiveKey(key) {
+    const lower = key.toLowerCase();
+    return SKIP_KEYS.has(lower) || SENSITIVE_KEY_RE.test(lower);
+}
+function pickString(obj, keys) {
+    for (const k of keys) {
+        if (isSensitiveKey(k))
+            continue;
+        const v = obj[k];
+        if (typeof v === "string" && v.trim())
+            return v.trim();
+        if (Array.isArray(v) && v.every((x) => typeof x === "string")) {
+            const joined = v.filter(Boolean).join(" ").trim();
+            if (joined)
+                return joined;
+        }
+        // Nested { file: { path: "..." } }
+        if (isPlainObject(v)) {
+            const nested = pickString(v, PATH_KEYS);
+            if (nested)
+                return nested;
+        }
+    }
+    return undefined;
+}
+function toolVerb(toolId) {
+    const last = toolId.split(/[./]/).filter(Boolean).pop()?.toLowerCase() ?? "";
+    if (/^(write|edit|update|create|put|patch|delete|rm|remove|exec|run|shell|read|checkout)$/.test(last)) {
+        return last === "exec" || last === "run" ? "shell" : last;
+    }
+    const id = toolId.toLowerCase();
+    if (id.includes("shell") || id.includes("exec"))
+        return "shell";
+    if (id.includes("write") || id.includes("edit"))
+        return "write";
+    if (id.includes("delete") || /\.rm\b/.test(id))
+        return "delete";
+    if (id.includes("read"))
+        return "read";
+    return "";
+}
+function contentHint(obj) {
+    for (const k of ["content", "body", "text", "code", "diff", "patch", "data"]) {
+        const v = obj[k];
+        if (typeof v === "string" && v.length > 0)
+            return `${v.length} chars`;
+        if (Buffer.isBuffer(v))
+            return `${v.length} bytes`;
+    }
+    return undefined;
+}
+/** Strip query/fragment from URLs before they enter the summary. */
+export function scrubUrl(value) {
+    try {
+        if (/^[a-z][a-z0-9+.-]*:/i.test(value)) {
+            const u = new URL(value);
+            u.search = "";
+            u.hash = "";
+            // Drop userinfo (user:pass@host)
+            u.username = "";
+            u.password = "";
+            return u.toString();
+        }
+    }
+    catch {
+        /* not a URL */
+    }
+    return value.replace(/([?&#][^=\s]*=)[^&\s#]+/g, "$1[redacted]");
+}
+/**
+ * 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.
+    if (!/\s/.test(trimmed) && (/^[a-z][a-z0-9+.-]*:/i.test(trimmed) || /[?&#].*=/.test(trimmed))) {
+        return finalize([`shell`, pathLike(trimmed)]) ?? "shell";
+    }
+    const tokens = trimmed.split(/\s+/).filter(Boolean);
+    // Skip leading ENV=value assignments
+    let i = 0;
+    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]))
+        i++;
+    let bin = tokens[i] ?? "cmd";
+    if (/^[a-z][a-z0-9+.-]*:/i.test(bin) || /[?&#].*=/.test(bin)) {
+        bin = pathLike(bin);
+    }
+    const rest = Math.max(0, tokens.length - i - 1);
+    const shortBin = bin.length > 48 ? `${bin.slice(0, 47)}…` : bin;
+    return rest > 0 ? `shell ${shortBin} (+${rest} args)` : `shell ${shortBin}`;
+}
+function extraRedact(s) {
+    let out = redactEvidence(s);
+    out = out.replace(/\bBasic\s+[A-Za-z0-9+/=_-]{4,}/gi, "Basic [redacted]");
+    out = out.replace(/\bCookie:\s*[^\s;]+(?:;\s*[^\s;]+)*/gi, "Cookie: [redacted]");
+    out = out.replace(/\bsession=[^\s;&]+/gi, "session=[redacted]");
+    out = out.replace(/([?&#](?:access_token|api[_-]?key|token|secret|password|auth|sid)=)[^&\s#]+/gi, "$1[redacted]");
+    out = out.replace(/\b[A-Z][A-Z0-9_]{2,}=(('[^']*')|("[^"]*")|\S+)/g, (m) => {
+        const name = m.split("=")[0] ?? "";
+        if (SENSITIVE_KEY_RE.test(name) || /KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL/i.test(name)) {
+            return `${name}=[redacted]`;
+        }
+        return m;
+    });
+    out = out.replace(/(?:^|\s)(-p|--password|--passwd|--token|--secret|--api-key)(\s+|=)\S+/gi, " $1=[redacted]");
+    return out;
+}
+/** Keys allowed in the free-form string fallback (never header/env blobs). */
+const SAFE_FALLBACK_KEYS = new Set([
+    "name",
+    "title",
+    "label",
+    "id",
+    "ref",
+    "branch",
+    "repo",
+    "message",
+    "note",
+    "description",
+]);
+function finalize(parts) {
+    const raw = parts.filter(Boolean).join(" ").replace(/\s+/g, " ").trim();
+    if (!raw)
+        return undefined;
+    const redacted = extraRedact(raw).replace(/\r?\n/g, " ").trim();
+    if (!redacted)
+        return undefined;
+    if (redacted.length <= MAX_LEN)
+        return redacted;
+    return `${redacted.slice(0, MAX_LEN - 1)}…`;
+}
+function pathLike(value) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value) || /[?&#].*=/.test(value)) {
+        return scrubUrl(value);
+    }
+    return value;
+}
+/**
+ * Derive a one-line change summary for the activity feed.
+ * Returns undefined when there is nothing safe/useful to show.
+ */
+export function deriveTrailSummary(toolId, args) {
+    const verb = toolVerb(toolId);
+    if (args == null) {
+        return undefined;
+    }
+    if (typeof args === "string") {
+        // Treat bare strings as opaque — only length, avoid dumping secrets.
+        return finalize([verb || "args", `(${args.length} chars)`]);
+    }
+    if (typeof args === "number" || typeof args === "boolean") {
+        return finalize([verb || "args", String(args)]);
+    }
+    if (Array.isArray(args)) {
+        // Argv-style: summarize as shell bin + count
+        if (args.every((x) => typeof x === "string")) {
+            return finalize([summarizeShellCommand(args.join(" "))]);
+        }
+        return finalize([verb || "args", `(${args.length} items)`]);
+    }
+    if (!isPlainObject(args)) {
+        return undefined;
+    }
+    const path = pickString(args, PATH_KEYS);
+    const cmd = pickString(args, CMD_KEYS);
+    const op = pickString(args, OP_KEYS);
+    const hint = contentHint(args);
+    if (cmd) {
+        return finalize([summarizeShellCommand(cmd)]);
+    }
+    if (path) {
+        const head = op || verb || "touch";
+        const safePath = pathLike(path);
+        return finalize(hint ? [head, safePath, `(${hint})`] : [head, safePath]);
+    }
+    for (const [k, v] of Object.entries(args)) {
+        if (!SAFE_FALLBACK_KEYS.has(k.toLowerCase()))
+            continue;
+        if (isSensitiveKey(k))
+            continue;
+        if (typeof v === "string" && v.trim() && v.length <= 120) {
+            return finalize([verb || k, pathLike(v.trim())]);
+        }
+    }
+    if (hint) {
+        return finalize([verb || "args", hint]);
+    }
+    // Args present but nothing safe to show
+    const keys = Object.keys(args);
+    if (keys.length > 0) {
+        return finalize(["(no safe summary)"]);
+    }
+    return undefined;
+}
+//# sourceMappingURL=trail-summary.js.map

package/dist/trail-summary.js.map

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

package/dist/trail.d.ts

@@ -0,0 +1,28 @@
+export type TrailProduct = "cursor" | "claude" | "codex" | "grok" | "ide" | "runtime" | "other";
+export interface TrailEvent {
+    readonly ts: string;
+    readonly sessionId: string;
+    readonly host?: string;
+    /** Coding tool / product that produced the event. */
+    readonly product?: TrailProduct;
+    readonly toolId: string;
+    readonly verdict: string;
+    readonly reasonCode: string;
+    readonly mode: "observe" | "hold" | "offline";
+    readonly neverEvent?: boolean;
+    readonly packId?: string;
+    readonly argsHash?: string;
+    /** Short redacted change line for the activity feed (never raw args). */
+    readonly summary?: string;
+}
+export declare function trailPath(cwd: string): string;
+export declare function receiptsDir(cwd: string): string;
+/** Detect Cursor / Claude Code / Codex / Grok / host from env. */
+export declare function detectProduct(env?: NodeJS.ProcessEnv, host?: string): TrailProduct;
+export declare function productLabel(p: TrailProduct | undefined): string;
+export declare function appendTrail(cwd: string, event: TrailEvent): void;
+export declare function readTrail(cwd: string): TrailEvent[];
+/** Events with ts >= since (ISO or Date). Invalid ts kept if unparseable. */
+export declare function readTrailSince(cwd: string, since: Date): TrailEvent[];
+export declare function defaultSessionId(env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=trail.d.ts.map

package/dist/trail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail.d.ts","sourceRoot":"","sources":["../src/trail.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,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,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;CAC3B;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;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,CAiBhE;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAQhE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAanD;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,UAAU,EAAE,CAOrE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAO7E"}

package/dist/trail.js

@@ -0,0 +1,92 @@
+/**
+ * Local session trail (JSONL). Observe path — not a second PEP.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir } from "./config.js";
+export function trailPath(cwd) {
+    return join(configDir(cwd), "trail.jsonl");
+}
+export function receiptsDir(cwd) {
+    return join(configDir(cwd), "receipts");
+}
+/** Detect Cursor / Claude Code / Codex / Grok / host from env. */
+export function detectProduct(env = process.env, host) {
+    if (env.CURSOR_SESSION_ID || env.CURSOR_TRACE_ID || env.CURSOR_AGENT)
+        return "cursor";
+    if (env.CLAUDECODE ||
+        env.CLAUDE_CODE_ENTRYPOINT ||
+        env.CLAUDE_SESSION_ID ||
+        (env.TERM_PROGRAM && /claude/i.test(env.TERM_PROGRAM))) {
+        return "claude";
+    }
+    if (env.CODEX_HOME || env.CODEX_SESSION || env.OPENAI_CODEX)
+        return "codex";
+    if (env.GROK_SESSION || env.GROK_BUILD || env.XAI_GROK)
+        return "grok";
+    if (host === "ide")
+        return "ide";
+    if (host === "runtime")
+        return "runtime";
+    return "other";
+}
+export function productLabel(p) {
+    switch (p) {
+        case "cursor":
+            return "Cursor";
+        case "claude":
+            return "Claude Code";
+        case "codex":
+            return "Codex";
+        case "grok":
+            return "Grok";
+        case "ide":
+            return "IDE";
+        case "runtime":
+            return "Runtime";
+        default:
+            return "Other";
+    }
+}
+export function appendTrail(cwd, event) {
+    const dir = configDir(cwd);
+    mkdirSync(dir, { recursive: true });
+    const enriched = {
+        ...event,
+        product: event.product ?? detectProduct(process.env, event.host),
+    };
+    appendFileSync(trailPath(cwd), `${JSON.stringify(enriched)}\n`, "utf8");
+}
+export function readTrail(cwd) {
+    const path = trailPath(cwd);
+    if (!existsSync(path))
+        return [];
+    const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
+    const out = [];
+    for (const line of lines) {
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            /* skip bad lines */
+        }
+    }
+    return out;
+}
+/** Events with ts >= since (ISO or Date). Invalid ts kept if unparseable. */
+export function readTrailSince(cwd, since) {
+    const sinceMs = since.getTime();
+    return readTrail(cwd).filter((e) => {
+        const t = Date.parse(e.ts);
+        if (Number.isNaN(t))
+            return true;
+        return t >= sinceMs;
+    });
+}
+export function defaultSessionId(env = process.env) {
+    return (env.KYA_SESSION_ID?.trim() ||
+        env.CURSOR_SESSION_ID?.trim() ||
+        env.CLAUDE_SESSION_ID?.trim() ||
+        `local-${new Date().toISOString().slice(0, 10)}`);
+}
+//# sourceMappingURL=trail.js.map

package/dist/trail.js.map

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

package/gemini/settings.example.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.1.23", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.1.31", "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.1.23 serve-mcp --stdio
+npx --no-install @shield-agent/kya@0.1.31 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/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "shield-kya",
   "display_name": "Shield KYA",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Know Your Agent MCP gate: ALLOW / DENY / REQUIRE_APPROVE. Sole PEP is Shield.",
   "long_description": "Local Claude Desktop extension that runs the packaged `dist/cli.js serve-mcp --stdio` against your Shield control plane (local or https://shield-agent.com). Tools evaluate policy, ingest session risk, and open Hold tickets. They never execute irreversible side effects.",
   "author": {

package/mcp.json

@@ -3,7 +3,7 @@
     "shield-kya": {
       "description": "Know Your Agent local MCP gate: wrap-before-write, named-agent registry, Hold/Clear.",
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.1.23", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.1.31", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "${KYA_BASE_URL}",
         "KYA_API_KEY": "${KYA_API_KEY}",

package/openai/codex.config.example.toml

@@ -11,7 +11,7 @@
 # --- Local stdio (OSS) ---
 [mcp_servers.shield-kya]
 command = "npx"
-args = ["--no-install", "@shield-agent/kya@0.1.23", "serve-mcp", "--stdio"]
+args = ["--no-install", "@shield-agent/kya@0.1.31", "serve-mcp", "--stdio"]
 startup_timeout_sec = 20
 env_vars = ["KYA_BASE_URL", "KYA_API_KEY", "KYA_HOST", "KYA_AGENT_ID"]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shield-agent/kya",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Know Your Agent light CLI + local MCP gate (provider-agnostic, zero vertical packs required).",
   "license": "MIT",
   "type": "module",

package/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/The-Pixel-Boys/shield-kya",
     "source": "github"
   },
-  "version": "0.1.29",
+  "version": "0.1.31",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@shield-agent/kya",
-      "version": "0.1.29",
+      "version": "0.1.31",
       "transport": {
         "type": "stdio"
       },