avantgate 1.5.0 → 1.6.1

package/README.md

@@ -33,13 +33,54 @@ flowchart LR
 
 ---
 
-## ☁️ GateWall Platform — Enterprise AI-WAF & Corporate DLP *(Coming Soon)*
+## 🖥️ GateWall Cockpit — Self-Hosted AI-WAF & Governance Console (`gatewall/`)
 
-While the open-source **AvantGate SDK** provides lightweight, in-process control and PII redaction, **GateWall Platform** is the enterprise AI Application Firewall (AI-WAF) and Corporate DLP gateway engineered for regulated industries (Fintech, Banking, Legaltech, and Listed Scale-ups).
+While the **AvantGate SDK** provides zero-infrastructure, in-process control inside your application runtime, the included **GateWall Cockpit** (`gatewall/`) provides a full-featured, self-hosted visual control plane, real-time audit inspector, and Human-in-the-Loop approval.
 
-Available as a **Managed Cloud Control Plane** or an **Out-of-Process High-Availability Sidecar/Proxy**:
+```mermaid
+flowchart LR
+    Agent[🤖 AvantGate Agent / SDK] -- "POST /api/v1/ingest/events<br/>(Async Telemetry)" --> GateWall["🛡️ GateWall Cockpit<br/>(Next.js + SQLite)"]
+    GateWall -- "SSE /api/v1/realtime" --> Browser["💻 Web Dashboard<br/>(http://localhost:3000)"]
+    Browser -- "POST /api/v1/approvals<br/>(Approve / Reject)" --> GateWall
+```
+
+### 🚀 Quickstart: Run GateWall Cockpit
+
+#### Option 1: One-Line Docker Compose (Recommended)
+```bash
+docker compose up -d
+# or: npm run gatewall:docker
+```
+Open **`http://localhost:3000`** in your browser 🎉. Traces and audit sessions are automatically persisted.
+
+#### Option 2: Run with Bun or Node.js
+```bash
+cd gatewall
+bun install   # or npm install
+bun run dev   # or npm run dev
+```
+
+---
+
+### 🛡️ Cockpit Capabilities & Modules
+
+| Module | Description |
+|---|---|
+| **🔒 Dual-Channel PII Inspector** | Visually compare the sequestered local escrow (`rawPayload`) against the redacted summary dispatched to the model (`llmSummary`). Highlights detected PII (emails, API keys, IBANs, phone numbers). |
+| **🧑‍⚖️ Human-in-the-Loop (HITL) Queue** | Real-time queue intercepting high-impact tool executions (`WAITING_APPROVAL`) with an interactive dashboard to inspect parameters and click **Approve** or **Reject**. |
+| **⚡ Real-Time Streaming (SSE)** | Low-latency Server-Sent Events (`/api/v1/realtime`) updating session trees, metrics, and alerts dynamically without manual page refresh. |
+| **💰 FinOps & Token Tracking** | Automated token cost estimation and USD burn tracking across providers (GPT-4o, Claude 3.5 Sonnet, DeepSeek, etc.). |
+| **🛡️ Loop Shield (Anti-Cycle Guard)** | Early visual detection of recursive agent loops and aberrant repetitive tool execution cycles. |
+| **💾 Zero-External-DB SQLite Storage** | Zero setup overhead: persistent storage uses embedded SQLite (`gatewall/data/gatewall.db`) without requiring PostgreSQL, Redis, or ClickHouse. |
+
+> 💡 **Agent Integration Recipes:** See [Connecting an Agent to GateWall Cockpit](docs/examples.md#12-connecting-an-agent-to-gatewall-cockpit-gatewall) in `docs/examples.md` for complete code recipes using `HttpTelemetryExporter` (`avantgate/agent`), direct HTTP ingestion, and React front-end streaming (`avantgate/client`).
+
+---
+
+### ☁️ Enterprise & Managed Cloud
 
-> 🚀 **Interested in private preview, enterprise VPC, or On-Premise deployment?** Contact our team at [contact@gatewall.fr](mailto:contact@gatewall.fr) for early access.
+Looking for enterprise multi-tenant RBAC, SSO/SAML, managed VPC sidecars, or on-premise air-gapped compliance?  
+Contact our team at [contact@gatewall.fr](mailto:contact@gatewall.fr) for private previews and enterprise deployment options.
 
 ---
 
@@ -54,6 +95,7 @@ Available as a **Managed Cloud Control Plane** or an **Out-of-Process High-Avail
 - 🔀 **Zero-Downtime Multi-Model Failover**: Seamless client-side failover to fallback providers (or local zero-cost Ollama) when upstream APIs return HTTP 429/500 errors.
 - 🔧 **Self-Repairing Structured Outputs**: Strict Zod schema compliance with automated heuristic markdown/JSON repair if the model hallucinates formatting.
 - 📡 **Zero-Dependency Telemetry Bridge (`HttpTelemetryExporter`, `PlatformStorageAdapter`)**: Mirror execution audits and hierarchical tool traces asynchronously without adding heavy external dependencies.
+- 🌐 **Lightweight Front-End SDK & React Hook (`avantgate/client`)**: Micro-bundle (< 1.7 KB gzipped) for browser UIs. Captures client-side security alerts (blocked API keys, prompt injection attempts), UI render metrics, and user feedback, streaming them directly to gateWall via `fetch(keepalive)` without loading backend infrastructure.
 - 📦 **100% Framework Agnostic**: Works seamlessly in Next.js, Express, Fastify, NestJS, Cloudflare Workers, AWS Lambda, or CLI scripts.
 
 ---
@@ -93,6 +135,7 @@ yarn add avantgate zod
 | `avantgate/finance` | Financial data normalizer (accounting parentheses, EU/US/UK/CH currencies & magnitudes). |
 | `avantgate/agent` | *(Preview / Experimental)* Durable step runner, Human-in-the-Loop, dual-channel PII tool isolation & storage adapters. |
 | `avantgate/workflow` | Deterministic sequential state machine, automatic reverse Saga rollback, durable HITL checkpoints & agent tool conversion. |
+| `avantgate/client` | Lightweight front-end SDK (< 1.7 KB) & React hook to stream browser security alerts & metrics directly to GateWall. |
 
 ---
 

package/dist/client/browser-exporter.d.ts

@@ -0,0 +1,32 @@
+import type { BrowserTelemetryExporterConfig, ClientTelemetryEvent } from "./types";
+export declare class BrowserTelemetryExporter {
+    private readonly publicKey;
+    private readonly endpoint;
+    private agentName?;
+    private runId?;
+    private readonly batchIntervalMs;
+    private readonly maxBatchSize;
+    private readonly fetchFn?;
+    private readonly onError?;
+    private buffer;
+    private timer;
+    private isFlushing;
+    private isDestroyed;
+    private readonly handleVisibilityChange;
+    private readonly handleBeforeUnload;
+    constructor(config: BrowserTelemetryExporterConfig);
+    updateContext: (context: {
+        runId?: string;
+        agentName?: string;
+    }) => void;
+    getRunId: () => string | undefined;
+    getAgentName: () => string | undefined;
+    private startTimer;
+    private setupBrowserListeners;
+    emit: (event: ClientTelemetryEvent) => void;
+    flush: () => Promise<void>;
+    private dispatchPayload;
+    private handleFlushError;
+    destroy: () => void;
+}
+//# sourceMappingURL=browser-exporter.d.ts.map

package/dist/client/browser-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-exporter.d.ts","sourceRoot":"","sources":["../../src/client/browser-exporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC9B,oBAAoB,EAErB,MAAM,SAAS,CAAC;AAMjB,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAyB;IAElD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAIrC;IAEF,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAEjC;gBAEU,MAAM,EAAE,8BAA8B;IAc3C,aAAa,GAAI,SAAS;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAG,IAAI,CAO5E;IAEK,QAAQ,QAAO,MAAM,GAAG,SAAS,CAAe;IAEhD,YAAY,QAAO,MAAM,GAAG,SAAS,CAAmB;IAE/D,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,qBAAqB;IAStB,IAAI,GAAI,OAAO,oBAAoB,KAAG,IAAI,CAQ/C;IAEK,KAAK,QAAa,OAAO,CAAC,IAAI,CAAC,CAuBpC;IAEF,OAAO,CAAC,eAAe,CAkBrB;IAEF,OAAO,CAAC,gBAAgB,CAStB;IAEK,OAAO,QAAO,IAAI,CAavB;CACH"}

package/dist/client/client.d.ts

@@ -0,0 +1,37 @@
+import { BrowserTelemetryExporter } from "./browser-exporter";
+import type { BrowserTelemetryExporterConfig, ClientSecurityAlertEvent } from "./types";
+export interface TrackSecurityAlertDetails {
+    inputLength: number;
+    snippet?: string;
+    matchedPatternSnippet?: string;
+}
+export interface TrackDataRenderedOptions {
+    renderedItemCount?: number;
+    channel?: "SOCKET" | "STREAM" | "HTTP";
+}
+export interface TrackFeedbackOptions {
+    rating: "POSITIVE" | "NEGATIVE";
+    tag?: "HELPFUL" | "INACCURATE" | "UNSAFE" | "OFF_TOPIC";
+    comment?: string;
+}
+/**
+ * Public interface for the universal (framework-agnostic) avantGate telemetry client.
+ */
+export interface AvantGateClient {
+    trackSecurityAlert: (alertType: ClientSecurityAlertEvent["alertType"], details: TrackSecurityAlertDetails) => void;
+    trackClientDataRendered: (toolId: string, options?: TrackDataRenderedOptions) => void;
+    trackFeedback: (feedback: TrackFeedbackOptions) => void;
+    updateContext: (context: {
+        runId?: string;
+        agentName?: string;
+    }) => void;
+    flush: () => Promise<void>;
+    destroy: () => void;
+    exporter: BrowserTelemetryExporter;
+}
+/**
+ * Creates a universal, framework-agnostic avantGate client instance.
+ * Works seamlessly in Vite (Vanilla JS, Vue, Svelte, SolidJS), Next.js, or browser scripts.
+ */
+export declare const createAvantGateClient: (config: BrowserTelemetryExporterConfig) => AvantGateClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EACV,8BAA8B,EAC9B,wBAAwB,EACzB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,wBAAwB;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;IAChC,GAAG,CAAC,EAAE,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kBAAkB,EAAE,CAClB,SAAS,EAAE,wBAAwB,CAAC,WAAW,CAAC,EAChD,OAAO,EAAE,yBAAyB,KAC/B,IAAI,CAAC;IACV,uBAAuB,EAAE,CACvB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,wBAAwB,KAC/B,IAAI,CAAC;IACV,aAAa,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACzE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,EAAE,wBAAwB,CAAC;CACpC;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,8BAA8B,KACrC,eAkDF,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+export { BrowserTelemetryExporter } from "./browser-exporter";
+export { createAvantGateClient, type AvantGateClient, type TrackSecurityAlertDetails, type TrackDataRenderedOptions, type TrackFeedbackOptions, } from "./client";
+export { useAvantGateTelemetry } from "./useAvantGateTelemetry";
+export type { ClientSecurityAlertEvent, ClientDataRenderedEvent, UserFeedbackEvent, ClientTelemetryEvent, BrowserTelemetryExporterConfig, ClientTelemetryIngestPayload, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,GAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,SAAS,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,259 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  BrowserTelemetryExporter: () => BrowserTelemetryExporter,
+  createAvantGateClient: () => createAvantGateClient,
+  useAvantGateTelemetry: () => useAvantGateTelemetry
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/client/browser-exporter.ts
+var DEFAULT_ENDPOINT = "http://localhost:3000/api/v1/ingest/events";
+var DEFAULT_INTERVAL_MS = 3e3;
+var DEFAULT_MAX_BATCH_SIZE = 20;
+var BrowserTelemetryExporter = class {
+  publicKey;
+  endpoint;
+  agentName;
+  runId;
+  batchIntervalMs;
+  maxBatchSize;
+  fetchFn;
+  onError;
+  buffer = [];
+  timer = null;
+  isFlushing = false;
+  isDestroyed = false;
+  handleVisibilityChange = () => {
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+      void this.flush();
+    }
+  };
+  handleBeforeUnload = () => {
+    void this.flush();
+  };
+  constructor(config) {
+    this.publicKey = config.publicKey;
+    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    this.agentName = config.agentName;
+    this.runId = config.runId;
+    this.batchIntervalMs = config.batchIntervalMs ?? DEFAULT_INTERVAL_MS;
+    this.maxBatchSize = config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
+    this.fetchFn = config.fetchFn ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : void 0);
+    this.onError = config.onError;
+    this.startTimer();
+    this.setupBrowserListeners();
+  }
+  updateContext = (context) => {
+    if (context.runId !== void 0) {
+      this.runId = context.runId;
+    }
+    if (context.agentName !== void 0) {
+      this.agentName = context.agentName;
+    }
+  };
+  getRunId = () => this.runId;
+  getAgentName = () => this.agentName;
+  startTimer() {
+    if (this.batchIntervalMs <= 0 || typeof setInterval === "undefined") {
+      return;
+    }
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.batchIntervalMs);
+  }
+  setupBrowserListeners() {
+    if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
+      document.addEventListener("visibilitychange", this.handleVisibilityChange);
+    }
+    if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+      window.addEventListener("beforeunload", this.handleBeforeUnload);
+    }
+  }
+  emit = (event) => {
+    if (this.isDestroyed) {
+      return;
+    }
+    this.buffer.push(event);
+    if (this.buffer.length >= this.maxBatchSize) {
+      void this.flush();
+    }
+  };
+  flush = async () => {
+    if (this.isFlushing || this.buffer.length === 0 || !this.fetchFn) {
+      return;
+    }
+    this.isFlushing = true;
+    const batch = [...this.buffer];
+    this.buffer = [];
+    const payload = {
+      runId: this.runId,
+      agentName: this.agentName,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      events: batch
+    };
+    try {
+      await this.dispatchPayload(payload);
+    } catch (err) {
+      this.handleFlushError(err, batch);
+    } finally {
+      this.isFlushing = false;
+    }
+  };
+  dispatchPayload = async (payload) => {
+    if (!this.fetchFn) {
+      throw new Error("No fetch implementation available in current environment");
+    }
+    const response = await this.fetchFn(this.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.publicKey}`
+      },
+      body: JSON.stringify(payload),
+      keepalive: true
+    });
+    if (!response.ok) {
+      throw new Error(`Browser telemetry ingestion failed: ${response.status} ${response.statusText}`);
+    }
+  };
+  handleFlushError = (err, failedBatch) => {
+    if (!this.isDestroyed && this.buffer.length < this.maxBatchSize * 2) {
+      this.buffer.unshift(...failedBatch);
+    }
+    const error = err instanceof Error ? err : new Error(String(err));
+    if (this.onError) {
+      this.onError(error);
+    }
+  };
+  destroy = () => {
+    this.isDestroyed = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (typeof document !== "undefined" && typeof document.removeEventListener === "function") {
+      document.removeEventListener("visibilitychange", this.handleVisibilityChange);
+    }
+    if (typeof window !== "undefined" && typeof window.removeEventListener === "function") {
+      window.removeEventListener("beforeunload", this.handleBeforeUnload);
+    }
+    void this.flush();
+  };
+};
+
+// src/client/client.ts
+var createAvantGateClient = (config) => {
+  const exporter = new BrowserTelemetryExporter(config);
+  const trackSecurityAlert = (alertType, details) => {
+    const snippet = details.snippet ?? details.matchedPatternSnippet;
+    exporter.emit({
+      type: "CLIENT_SECURITY_ALERT",
+      alertType,
+      inputLength: details.inputLength,
+      snippet,
+      matchedPatternSnippet: snippet,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  };
+  const trackClientDataRendered = (toolId, options) => {
+    exporter.emit({
+      type: "CLIENT_DATA_RENDERED",
+      toolId,
+      channel: options?.channel,
+      renderedItemCount: options?.renderedItemCount,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  };
+  const trackFeedback = (feedback) => {
+    exporter.emit({
+      type: "USER_FEEDBACK",
+      rating: feedback.rating,
+      feedbackTag: feedback.tag,
+      userComment: feedback.comment,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  };
+  return {
+    trackSecurityAlert,
+    trackClientDataRendered,
+    trackFeedback,
+    updateContext: exporter.updateContext,
+    flush: exporter.flush,
+    destroy: exporter.destroy,
+    exporter
+  };
+};
+
+// src/client/useAvantGateTelemetry.ts
+var import_react = require("react");
+var useAvantGateTelemetry = (config) => {
+  const clientRef = (0, import_react.useRef)(null);
+  if (!clientRef.current) {
+    clientRef.current = createAvantGateClient(config);
+  }
+  (0, import_react.useEffect)(() => {
+    clientRef.current?.updateContext({
+      runId: config.runId,
+      agentName: config.agentName
+    });
+  }, [config.runId, config.agentName]);
+  (0, import_react.useEffect)(() => {
+    return () => {
+      clientRef.current?.destroy();
+      clientRef.current = null;
+    };
+  }, []);
+  const trackSecurityAlert = (0, import_react.useCallback)(
+    (alertType, details) => {
+      clientRef.current?.trackSecurityAlert(alertType, details);
+    },
+    []
+  );
+  const trackClientDataRendered = (0, import_react.useCallback)(
+    (toolId, options) => {
+      clientRef.current?.trackClientDataRendered(toolId, options);
+    },
+    []
+  );
+  const trackFeedback = (0, import_react.useCallback)(
+    (feedback) => {
+      clientRef.current?.trackFeedback(feedback);
+    },
+    []
+  );
+  return (0, import_react.useMemo)(
+    () => ({
+      trackSecurityAlert,
+      trackClientDataRendered,
+      trackFeedback,
+      exporter: clientRef.current?.exporter
+    }),
+    [trackSecurityAlert, trackClientDataRendered, trackFeedback]
+  );
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BrowserTelemetryExporter,
+  createAvantGateClient,
+  useAvantGateTelemetry
+});

package/dist/client/index.mjs

@@ -0,0 +1,230 @@
+// src/client/browser-exporter.ts
+var DEFAULT_ENDPOINT = "http://localhost:3000/api/v1/ingest/events";
+var DEFAULT_INTERVAL_MS = 3e3;
+var DEFAULT_MAX_BATCH_SIZE = 20;
+var BrowserTelemetryExporter = class {
+  publicKey;
+  endpoint;
+  agentName;
+  runId;
+  batchIntervalMs;
+  maxBatchSize;
+  fetchFn;
+  onError;
+  buffer = [];
+  timer = null;
+  isFlushing = false;
+  isDestroyed = false;
+  handleVisibilityChange = () => {
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+      void this.flush();
+    }
+  };
+  handleBeforeUnload = () => {
+    void this.flush();
+  };
+  constructor(config) {
+    this.publicKey = config.publicKey;
+    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    this.agentName = config.agentName;
+    this.runId = config.runId;
+    this.batchIntervalMs = config.batchIntervalMs ?? DEFAULT_INTERVAL_MS;
+    this.maxBatchSize = config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
+    this.fetchFn = config.fetchFn ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : void 0);
+    this.onError = config.onError;
+    this.startTimer();
+    this.setupBrowserListeners();
+  }
+  updateContext = (context) => {
+    if (context.runId !== void 0) {
+      this.runId = context.runId;
+    }
+    if (context.agentName !== void 0) {
+      this.agentName = context.agentName;
+    }
+  };
+  getRunId = () => this.runId;
+  getAgentName = () => this.agentName;
+  startTimer() {
+    if (this.batchIntervalMs <= 0 || typeof setInterval === "undefined") {
+      return;
+    }
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.batchIntervalMs);
+  }
+  setupBrowserListeners() {
+    if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
+      document.addEventListener("visibilitychange", this.handleVisibilityChange);
+    }
+    if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+      window.addEventListener("beforeunload", this.handleBeforeUnload);
+    }
+  }
+  emit = (event) => {
+    if (this.isDestroyed) {
+      return;
+    }
+    this.buffer.push(event);
+    if (this.buffer.length >= this.maxBatchSize) {
+      void this.flush();
+    }
+  };
+  flush = async () => {
+    if (this.isFlushing || this.buffer.length === 0 || !this.fetchFn) {
+      return;
+    }
+    this.isFlushing = true;
+    const batch = [...this.buffer];
+    this.buffer = [];
+    const payload = {
+      runId: this.runId,
+      agentName: this.agentName,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      events: batch
+    };
+    try {
+      await this.dispatchPayload(payload);
+    } catch (err) {
+      this.handleFlushError(err, batch);
+    } finally {
+      this.isFlushing = false;
+    }
+  };
+  dispatchPayload = async (payload) => {
+    if (!this.fetchFn) {
+      throw new Error("No fetch implementation available in current environment");
+    }
+    const response = await this.fetchFn(this.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.publicKey}`
+      },
+      body: JSON.stringify(payload),
+      keepalive: true
+    });
+    if (!response.ok) {
+      throw new Error(`Browser telemetry ingestion failed: ${response.status} ${response.statusText}`);
+    }
+  };
+  handleFlushError = (err, failedBatch) => {
+    if (!this.isDestroyed && this.buffer.length < this.maxBatchSize * 2) {
+      this.buffer.unshift(...failedBatch);
+    }
+    const error = err instanceof Error ? err : new Error(String(err));
+    if (this.onError) {
+      this.onError(error);
+    }
+  };
+  destroy = () => {
+    this.isDestroyed = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (typeof document !== "undefined" && typeof document.removeEventListener === "function") {
+      document.removeEventListener("visibilitychange", this.handleVisibilityChange);
+    }
+    if (typeof window !== "undefined" && typeof window.removeEventListener === "function") {
+      window.removeEventListener("beforeunload", this.handleBeforeUnload);
+    }
+    void this.flush();
+  };
+};
+
+// src/client/client.ts
+var createAvantGateClient = (config) => {
+  const exporter = new BrowserTelemetryExporter(config);
+  const trackSecurityAlert = (alertType, details) => {
+    const snippet = details.snippet ?? details.matchedPatternSnippet;
+    exporter.emit({
+      type: "CLIENT_SECURITY_ALERT",
+      alertType,
+      inputLength: details.inputLength,
+      snippet,
+      matchedPatternSnippet: snippet,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  };
+  const trackClientDataRendered = (toolId, options) => {
+    exporter.emit({
+      type: "CLIENT_DATA_RENDERED",
+      toolId,
+      channel: options?.channel,
+      renderedItemCount: options?.renderedItemCount,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  };
+  const trackFeedback = (feedback) => {
+    exporter.emit({
+      type: "USER_FEEDBACK",
+      rating: feedback.rating,
+      feedbackTag: feedback.tag,
+      userComment: feedback.comment,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  };
+  return {
+    trackSecurityAlert,
+    trackClientDataRendered,
+    trackFeedback,
+    updateContext: exporter.updateContext,
+    flush: exporter.flush,
+    destroy: exporter.destroy,
+    exporter
+  };
+};
+
+// src/client/useAvantGateTelemetry.ts
+import { useRef, useEffect, useCallback, useMemo } from "react";
+var useAvantGateTelemetry = (config) => {
+  const clientRef = useRef(null);
+  if (!clientRef.current) {
+    clientRef.current = createAvantGateClient(config);
+  }
+  useEffect(() => {
+    clientRef.current?.updateContext({
+      runId: config.runId,
+      agentName: config.agentName
+    });
+  }, [config.runId, config.agentName]);
+  useEffect(() => {
+    return () => {
+      clientRef.current?.destroy();
+      clientRef.current = null;
+    };
+  }, []);
+  const trackSecurityAlert = useCallback(
+    (alertType, details) => {
+      clientRef.current?.trackSecurityAlert(alertType, details);
+    },
+    []
+  );
+  const trackClientDataRendered = useCallback(
+    (toolId, options) => {
+      clientRef.current?.trackClientDataRendered(toolId, options);
+    },
+    []
+  );
+  const trackFeedback = useCallback(
+    (feedback) => {
+      clientRef.current?.trackFeedback(feedback);
+    },
+    []
+  );
+  return useMemo(
+    () => ({
+      trackSecurityAlert,
+      trackClientDataRendered,
+      trackFeedback,
+      exporter: clientRef.current?.exporter
+    }),
+    [trackSecurityAlert, trackClientDataRendered, trackFeedback]
+  );
+};
+export {
+  BrowserTelemetryExporter,
+  createAvantGateClient,
+  useAvantGateTelemetry
+};

package/dist/client/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Client Security Alert Event emitted when a local pre-flight guardrail detects an anomaly
+ * (prompt injection attempt, hardcoded API key, unredacted PII) before network egress.
+ */
+export interface ClientSecurityAlertEvent {
+    type: "CLIENT_SECURITY_ALERT";
+    alertType: "POTENTIAL_PROMPT_INJECTION" | "SUSPECTED_SECRET_INPUT" | "SUSPECTED_PII_INPUT";
+    inputLength: number;
+    snippet?: string;
+    matchedPatternSnippet?: string;
+    timestamp: string;
+}
+/**
+ * Client Data Rendered Event emitted when tool output or stream chunks are rendered in UI.
+ */
+export interface ClientDataRenderedEvent {
+    type: "CLIENT_DATA_RENDERED";
+    toolId: string;
+    channel?: "SOCKET" | "STREAM" | "HTTP";
+    renderedItemCount?: number;
+    timestamp: string;
+}
+/**
+ * User Feedback Event emitted when a user rates or comments on an agent response.
+ */
+export interface UserFeedbackEvent {
+    type: "USER_FEEDBACK";
+    rating: "POSITIVE" | "NEGATIVE";
+    feedbackTag?: "HELPFUL" | "INACCURATE" | "UNSAFE" | "OFF_TOPIC";
+    userComment?: string;
+    timestamp: string;
+}
+/**
+ * Union of all supported front-end client telemetry events.
+ */
+export type ClientTelemetryEvent = ClientSecurityAlertEvent | ClientDataRenderedEvent | UserFeedbackEvent;
+/**
+ * Configuration options for BrowserTelemetryExporter.
+ */
+export interface BrowserTelemetryExporterConfig {
+    publicKey: string;
+    endpoint?: string;
+    agentName?: string;
+    runId?: string;
+    batchIntervalMs?: number;
+    maxBatchSize?: number;
+    fetchFn?: typeof fetch;
+    onError?: (error: Error) => void;
+}
+/**
+ * Ingest payload format expected by POST /api/v1/ingest/events according to DESIGN-019.
+ */
+export interface ClientTelemetryIngestPayload {
+    runId?: string;
+    agentName?: string;
+    timestamp: string;
+    events: ClientTelemetryEvent[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,SAAS,EAAE,4BAA4B,GAAG,wBAAwB,GAAG,qBAAqB,CAAC;IAC3F,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;IAChC,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC5B,wBAAwB,GACxB,uBAAuB,GACvB,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC"}

package/dist/client/useAvantGateTelemetry.d.ts

@@ -0,0 +1,14 @@
+import { type TrackSecurityAlertDetails, type TrackDataRenderedOptions, type TrackFeedbackOptions } from "./client";
+import type { BrowserTelemetryExporterConfig, ClientSecurityAlertEvent } from "./types";
+export type { TrackSecurityAlertDetails, TrackDataRenderedOptions, TrackFeedbackOptions, };
+/**
+ * Lightweight React Hook for front-end telemetry and client-side security event tracking.
+ * Encapsulates lifecycle management, useRef persistence, useCallback and useMemo optimization.
+ */
+export declare const useAvantGateTelemetry: (config: BrowserTelemetryExporterConfig) => {
+    trackSecurityAlert: (alertType: ClientSecurityAlertEvent["alertType"], details: TrackSecurityAlertDetails) => void;
+    trackClientDataRendered: (toolId: string, options?: TrackDataRenderedOptions) => void;
+    trackFeedback: (feedback: TrackFeedbackOptions) => void;
+    exporter: import("./browser-exporter").BrowserTelemetryExporter | undefined;
+};
+//# sourceMappingURL=useAvantGateTelemetry.d.ts.map

package/dist/client/useAvantGateTelemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAvantGateTelemetry.d.ts","sourceRoot":"","sources":["../../src/client/useAvantGateTelemetry.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACV,8BAA8B,EAC9B,wBAAwB,EACzB,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,yBAAyB,EACzB,wBAAwB,EACxB,oBAAoB,GACrB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,8BAA8B;oCAuB3D,wBAAwB,CAAC,WAAW,CAAC,WACvC,yBAAyB,KACjC,IAAI;sCAQG,MAAM,YACJ,wBAAwB,KACjC,IAAI;8BAOI,oBAAoB,KAAG,IAAI;;CAezC,CAAC"}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "avantgate",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Zero-infrastructure, in-process AI Application Firewall (AI-WAF) & privacy control plane for TypeScript: real-time prompt guardrails, zero-egress PII redaction, agent tool isolation, anti-IDOR defense, pre-flight token budgets, and multi-model failover.",
-  "author": "Antigravity & LexTalk Team",
+  "author": "Gatewall Team",
   "license": "MIT",
   "keywords": [
     "avantgate",
+    "gatewall",
     "ai-waf",
     "guardrails",
     "prompt-injection",
@@ -59,21 +60,41 @@
       "import": "./dist/workflow/index.mjs",
       "require": "./dist/workflow/index.js"
     },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.mjs",
+      "require": "./dist/client/index.js"
+    },
     "./package.json": "./package.json"
   },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/finance/index.ts src/agent/index.ts src/workflow/index.ts --format cjs --format esm --clean && tsc --emitDeclarationOnly --outDir dist",
-    "test": "tsx tests/avantgate.test.ts && tsx tests/preflight-budget.test.ts && tsx tests/financial-normalizer.test.ts && tsx tests/prompt-builder.test.ts && tsx tests/pii-extended.test.ts && npm run test:agent && npm run test:workflow",
+    "build": "tsup src/index.ts src/finance/index.ts src/agent/index.ts src/workflow/index.ts src/client/index.ts --format cjs --format esm --clean && tsc --emitDeclarationOnly --outDir dist",
+    "test": "tsx tests/avantgate.test.ts && tsx tests/preflight-budget.test.ts && tsx tests/financial-normalizer.test.ts && tsx tests/prompt-builder.test.ts && tsx tests/pii-extended.test.ts && npm run test:agent && npm run test:workflow && npm run test:client",
     "test:finance": "tsx tests/financial-normalizer.test.ts",
     "test:prompts": "tsx tests/prompt-builder.test.ts",
     "test:pii": "tsx tests/pii-extended.test.ts",
     "test:agent": "tsx tests/agent/step-runner.test.ts && tsx tests/agent/isolated-tool.test.ts && tsx tests/agent/dto-pattern.test.ts && tsx tests/agent/tool-patterns.test.ts && tsx tests/agent/storage-adapters.test.ts && tsx tests/agent/tool-aliasing.test.ts && tsx tests/agent/tool-chaining.test.ts && tsx tests/agent/tool-storage.test.ts && tsx tests/agent/telemetry-exporter.test.ts && tsx tests/agent/platform-adapter.test.ts && tsx tests/agent/tool-governance.test.ts && tsx tests/agent/tool-impact.test.ts",
     "test:workflow": "tsx tests/workflow/workflow-saga.test.ts && tsx tests/workflow/workflow-abort.test.ts",
+    "test:client": "tsx tests/client/browser-exporter.test.ts",
+    "test:demo": "tsx tests/agent/prospect-ai-demo-scenario.test.ts",
+    "gatewall": "npm --prefix gatewall run dev",
+    "gatewall:dev": "npm --prefix gatewall run dev",
+    "gatewall:build": "npm --prefix gatewall run build",
+    "gatewall:start": "npm --prefix gatewall run start",
+    "gatewall:docker": "docker compose up -d",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build && npm test"
   },
@@ -81,11 +102,21 @@
     "zod": "^3.23.0 || ^4.0.0"
   },
   "devDependencies": {
+    "@types/react": "^18.3.18",
+    "react": "^18.3.1",
     "tsup": "^8.3.5",
     "tsx": "^4.19.0",
     "typescript": "^5.4.0"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thienban/avantGate.git"
+  },
+  "homepage": "https://github.com/thienban/avantGate#readme",
+  "bugs": {
+    "url": "https://github.com/thienban/avantGate/issues"
   }
 }