@vhyxvoid/agent 1.0.0

package/dist/AgentClient.d.ts

@@ -0,0 +1,70 @@
+export type AgentState = "IDLE" | "CONNECTING" | "AUTHENTICATING" | "CONNECTED" | "RECONNECTING" | "STOPPED";
+export interface AgentConfig {
+    /** Hub WebSocket URL e.g. wss://hub.yourplatform.com/agent */
+    hubUrl: string;
+    /** API key public ID e.g. vhyxvoid_dev_abc123 */
+    keyId: string;
+    /**
+     * secretHash = HMAC-SHA256(rawSecret, SERVER_HMAC_PEPPER).
+     * The CLI hashes the raw secret on startup so it's never kept in memory.
+     */
+    secretHash: string;
+    /** Tunnel label — identifies this agent if an account has multiple agents */
+    label: string;
+    /** Local backend port to forward requests to */
+    port: number;
+    /** npm package version — sent to hub for compatibility checking */
+    agentVersion: string;
+    /** SQLite queue file path (default: ~/.vhyxvoid/queue.db) */
+    queuePath?: string;
+    /** Enable local discovery HTTP server on port 4242 (default: true) */
+    localDiscovery?: boolean;
+    /** Called whenever the agent state changes */
+    onStateChange?: (state: AgentState) => void;
+    /** Called on each log event — defaults to console */
+    logger?: {
+        info: (obj: object, msg?: string) => void;
+        warn: (obj: object, msg?: string) => void;
+        error: (obj: object, msg?: string) => void;
+    };
+}
+export declare class AgentClient {
+    private readonly config;
+    private state;
+    private ws;
+    private agentId;
+    private reconnectDelay;
+    private reconnectTimer;
+    private stopped;
+    private readonly queue;
+    private readonly proxy;
+    private readonly batcher;
+    private readonly discovery;
+    private readonly log;
+    constructor(config: AgentConfig);
+    start(): void;
+    stop(): void;
+    getState(): AgentState;
+    getQueueStatus(): {
+        ready: number;
+        pending: number;
+        deadLetter: number;
+    };
+    getCacheStats(): {
+        size: number;
+        totalHits: number;
+    };
+    private connect;
+    private onOpen;
+    private onMessage;
+    private onRegistered;
+    private onPing;
+    private onHubError;
+    private onForward;
+    private onClose;
+    private onError;
+    private scheduleReconnect;
+    private sendRaw;
+    private setState;
+}
+//# sourceMappingURL=AgentClient.d.ts.map

package/dist/AgentClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentClient.d.ts","sourceRoot":"","sources":["../src/AgentClient.ts"],"names":[],"mappings":"AA+BA,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,YAAY,GACZ,gBAAgB,GAChB,WAAW,GACX,cAAc,GACd,SAAS,CAAC;AAId,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC5C,qDAAqD;IACrD,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;QAC1C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;QAC1C,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;KAC5C,CAAC;CACH;AAED,qBAAa,WAAW;IAcV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAbnC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,OAAO,CAAkB;IAEjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;gBAE5B,MAAM,EAAE,WAAW;IAqChD,KAAK,IAAI,IAAI;IAUb,IAAI,IAAI,IAAI;IAWZ,QAAQ,IAAI,UAAU;IAGtB,cAAc;;;;;IAGd,aAAa;;;;IAMb,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,MAAM;IAkCd,OAAO,CAAC,SAAS;YAkCH,YAAY;IA2B1B,OAAO,CAAC,MAAM;IAWd,OAAO,CAAC,UAAU;YAkBJ,SAAS;IA4BvB,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,QAAQ;CAKjB"}

package/dist/AgentClient.js

@@ -0,0 +1,261 @@
+"use strict";
+// packages/agent/src/AgentClient.ts
+// Main agent class. State machine with reconnect. Single WS connection.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentClient = void 0;
+const ws_1 = __importDefault(require("ws"));
+const crypto_1 = require("crypto");
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const fs_1 = __importDefault(require("fs"));
+const protocol_1 = require("@vhyxvoid/protocol");
+const DurableQueue_1 = require("./queue/DurableQueue");
+const BackendProxy_1 = require("./proxy/BackendProxy");
+const MessageBatcher_1 = require("./batcher/MessageBatcher");
+const replayQueue_1 = require("./replay/replayQueue");
+const LocalDiscoveryServer_1 = require("./discovery/LocalDiscoveryServer");
+class AgentClient {
+    config;
+    state = "IDLE";
+    ws = null;
+    agentId = null;
+    reconnectDelay = protocol_1.TIMING.RECONNECT_INITIAL_MS;
+    reconnectTimer = null;
+    stopped = false;
+    queue;
+    proxy;
+    batcher;
+    discovery;
+    log;
+    constructor(config) {
+        this.config = config;
+        this.log = config.logger ?? {
+            info: (obj, msg) => console.info(msg ?? "", obj),
+            warn: (obj, msg) => console.warn(msg ?? "", obj),
+            error: (obj, msg) => console.error(msg ?? "", obj),
+        };
+        // Ensure queue directory exists
+        const queuePath = config.queuePath ?? path_1.default.join(os_1.default.homedir(), ".vhyxvoid", "queue.db");
+        fs_1.default.mkdirSync(path_1.default.dirname(queuePath), { recursive: true });
+        this.queue = new DurableQueue_1.DurableQueue(queuePath);
+        this.proxy = new BackendProxy_1.BackendProxy(config.port);
+        this.batcher = new MessageBatcher_1.MessageBatcher(
+        // onFlush: send over WS
+        (data) => this.sendRaw(data), 
+        // onQueueFallback: WS is down, persist to durable queue
+        (msg) => this.queue.enqueueOutbound(msg), 
+        // isConnected: checked before every flush
+        () => this.state === "CONNECTED");
+        const useDiscovery = config.localDiscovery !== false;
+        this.discovery = useDiscovery
+            ? new LocalDiscoveryServer_1.LocalDiscoveryServer({
+                agentVersion: config.agentVersion,
+                label: config.label,
+                port: config.port,
+                accountIdHash: "", // populated after hub:registered
+            })
+            : null;
+    }
+    // ── Public API ──────────────────────────────────────────────────────────────
+    start() {
+        if (this.state !== "IDLE") {
+            throw new Error("AgentClient already started. Create a new instance to restart.");
+        }
+        this.discovery?.start();
+        this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        this.setState("STOPPED");
+        this.batcher.flushToQueue(); // save buffered messages to disk
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.ws?.close(1000, "agent_stopped");
+        this.proxy.stop();
+        this.discovery?.stop();
+        this.queue.close();
+    }
+    getState() {
+        return this.state;
+    }
+    getQueueStatus() {
+        return this.queue.count();
+    }
+    getCacheStats() {
+        return this.proxy.getCacheStats();
+    }
+    // ── WS connection lifecycle ─────────────────────────────────────────────────
+    connect() {
+        if (this.stopped)
+            return;
+        this.setState("CONNECTING");
+        const ws = new ws_1.default(this.config.hubUrl, {
+            perMessageDeflate: true,
+            handshakeTimeout: 10_000,
+        });
+        this.ws = ws;
+        ws.on("open", () => this.onOpen());
+        ws.on("message", (data) => this.onMessage(data));
+        ws.on("close", (code, reason) => this.onClose(code, reason.toString()));
+        ws.on("error", (err) => this.onError(err));
+    }
+    onOpen() {
+        this.setState("AUTHENTICATING");
+        this.reconnectDelay = protocol_1.TIMING.RECONNECT_INITIAL_MS; // reset backoff on success
+        const now = Date.now();
+        const requestId = (0, crypto_1.randomUUID)();
+        const canonical = (0, protocol_1.buildCanonical)({
+            method: "AGENT_REGISTER",
+            path: "/agent/register",
+            query: "",
+            body: this.config.label,
+            requestId,
+            ts: now,
+        });
+        const msg = {
+            v: protocol_1.PROTOCOL_VERSION,
+            type: "agent:register",
+            keyId: this.config.keyId,
+            label: this.config.label,
+            requestId,
+            ts: now,
+            signature: (0, protocol_1.signCanonical)(canonical, this.config.secretHash),
+            agentVersion: this.config.agentVersion,
+        };
+        this.sendRaw((0, protocol_1.serialize)(msg));
+        this.log.info({ label: this.config.label, keyId: this.config.keyId }, "[agent] authenticating with hub");
+    }
+    onMessage(data) {
+        let msg;
+        try {
+            msg = (0, protocol_1.parseMessage)(data);
+        }
+        catch (err) {
+            if (err instanceof protocol_1.ProtocolError) {
+                this.log.warn({
+                    code: err.code,
+                    message: `Local backend on port ${this.config.port} is not responding: ${err.message}`,
+                }, // ← this is fine, err IS ProtocolError here
+                "[agent] protocol error from hub");
+            }
+            return;
+        }
+        switch (msg.type) {
+            case "hub:registered":
+                return void this.onRegistered(msg);
+            case "hub:ping":
+                return this.onPing(msg);
+            case "hub:error":
+                return this.onHubError(msg);
+            case "tunnel:forward":
+                return void this.onForward(msg);
+            default:
+                this.log.warn({ type: msg.type }, "[agent] unknown message type from hub");
+        }
+    }
+    async onRegistered(msg) {
+        this.agentId = msg.agentId;
+        this.setState("CONNECTED");
+        this.log.info({
+            agentId: msg.agentId,
+            accountId: msg.accountId,
+            label: this.config.label,
+            port: this.config.port,
+        }, "[agent] ✅ tunnel is live");
+        // Replay durable queue AFTER state = CONNECTED so sendRaw works
+        const counts = this.queue.count();
+        if (counts.ready > 0) {
+            this.log.info({ items: counts.ready }, "[agent] replaying queue");
+            const result = await (0, replayQueue_1.replayQueue)(this.queue, (data) => this.sendRaw(data), this.proxy);
+            this.log.info(result, "[agent] queue replay complete");
+        }
+    }
+    onPing(msg) {
+        if (!this.agentId)
+            return;
+        const pong = {
+            v: protocol_1.PROTOCOL_VERSION,
+            type: "agent:pong",
+            agentId: this.agentId,
+            ts: Date.now(),
+        };
+        this.batcher.add(pong);
+    }
+    onHubError(msg) {
+        this.log.error({ code: msg.code, message: msg.message, fatal: msg.fatal }, "[agent] hub error");
+        if (msg.fatal) {
+            if (msg.code === "AUTH_FAILED" || msg.code === "VERSION_UNSUPPORTED") {
+                console.error(`\n❌ Fatal error: ${msg.message}\n` +
+                    `   Check your API key and agent version, then restart.\n`);
+                this.stop();
+            }
+            // AGENT_LIMIT_REACHED → allow reconnect — user may free up a slot
+        }
+    }
+    async onForward(msg) {
+        // Invalidate related cache entries on mutating requests
+        this.proxy.invalidateCacheFor(msg.method, msg.path);
+        try {
+            const result = await this.proxy.forward(msg);
+            const response = {
+                v: protocol_1.PROTOCOL_VERSION,
+                type: "tunnel:response",
+                requestId: msg.requestId,
+                ...result,
+            };
+            this.batcher.add(response);
+        }
+        catch (err) {
+            // Never leave a request unanswered — always send an error back
+            const agentError = {
+                v: protocol_1.PROTOCOL_VERSION,
+                type: "tunnel:agent-error",
+                requestId: msg.requestId,
+                code: "BACKEND_UNAVAILABLE",
+                message: `Local backend on port ${this.config.port} is not responding: ${err.message}`,
+            };
+            // If WS is up, batcher sends it; if down, it goes to durable queue
+            this.batcher.add(agentError);
+        }
+    }
+    onClose(code, reason) {
+        if (this.stopped)
+            return;
+        this.log.warn({ code, reason }, "[agent] WS closed — scheduling reconnect");
+        this.batcher.flushToQueue(); // save in-memory buffer to SQLite
+        this.setState("RECONNECTING");
+        this.scheduleReconnect();
+    }
+    onError(err) {
+        // WS error is always followed by close — just log
+        this.log.warn({ message: err.message }, "[agent] WS error");
+    }
+    scheduleReconnect() {
+        if (this.stopped)
+            return;
+        const delay = this.reconnectDelay;
+        this.reconnectDelay = Math.min(delay * 2, protocol_1.TIMING.RECONNECT_MAX_MS);
+        this.log.info({ delayMs: delay }, "[agent] reconnecting");
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    // ── Helpers ─────────────────────────────────────────────────────────────────
+    sendRaw(data) {
+        if (this.ws?.readyState === ws_1.default.OPEN) {
+            this.ws.send(data);
+        }
+    }
+    setState(state) {
+        if (this.state === state)
+            return;
+        this.state = state;
+        this.config.onStateChange?.(state);
+    }
+}
+exports.AgentClient = AgentClient;
+//# sourceMappingURL=AgentClient.js.map

package/dist/AgentClient.js.map

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

package/dist/batcher/MessageBatcher.d.ts

@@ -0,0 +1,40 @@
+import { TunnelResponseMsg, TunnelAgentErrorMsg, AgentPongMsg } from "@vhyxvoid/protocol";
+export type BatchableMsg = TunnelResponseMsg | TunnelAgentErrorMsg | AgentPongMsg;
+type FlushFn = (data: string) => void;
+type QueueFallback = (msg: TunnelResponseMsg | TunnelAgentErrorMsg) => void;
+type IsConnected = () => boolean;
+export declare class MessageBatcher {
+    /** Called with serialized data when WS is available */
+    private readonly onFlush;
+    /** Called with individual messages when WS is down — routes to DurableQueue */
+    private readonly onQueueFallback;
+    /** Returns true when WS connection is CONNECTED */
+    private readonly isConnected;
+    private buffer;
+    private timer;
+    constructor(
+    /** Called with serialized data when WS is available */
+    onFlush: FlushFn, 
+    /** Called with individual messages when WS is down — routes to DurableQueue */
+    onQueueFallback: QueueFallback, 
+    /** Returns true when WS connection is CONNECTED */
+    isConnected: IsConnected);
+    /** Add a message to the batch. Flushes immediately if MAX_BATCH_SIZE reached. */
+    add(msg: BatchableMsg): void;
+    /**
+     * Flush the buffer.
+     * - If WS is connected: send as batch (or single message if only one item)
+     * - If WS is down: route non-pong messages to DurableQueue
+     */
+    flush(): void;
+    /**
+     * Called on WS close BEFORE reconnect starts.
+     * Moves everything currently in the buffer to DurableQueue.
+     * Pongs are discarded (they are point-in-time, not meaningful after disconnect).
+     */
+    flushToQueue(): void;
+    /** Number of messages currently buffered (for diagnostics). */
+    size(): number;
+}
+export {};
+//# sourceMappingURL=MessageBatcher.d.ts.map

package/dist/batcher/MessageBatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageBatcher.d.ts","sourceRoot":"","sources":["../../src/batcher/MessageBatcher.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EAIb,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,mBAAmB,GACnB,YAAY,CAAC;AAEjB,KAAK,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AACtC,KAAK,aAAa,GAAG,CAAC,GAAG,EAAE,iBAAiB,GAAG,mBAAmB,KAAK,IAAI,CAAC;AAC5E,KAAK,WAAW,GAAG,MAAM,OAAO,CAAC;AAEjC,qBAAa,cAAc;IAKvB,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,WAAW;IAT9B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,KAAK,CAA+B;;IAG1C,uDAAuD;IACtC,OAAO,EAAE,OAAO;IACjC,+EAA+E;IAC9D,eAAe,EAAE,aAAa;IAC/C,mDAAmD;IAClC,WAAW,EAAE,WAAW;IAG3C,iFAAiF;IACjF,GAAG,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAU5B;;;;OAIG;IACH,KAAK,IAAI,IAAI;IA6Bb;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAcpB,+DAA+D;IAC/D,IAAI,IAAI,MAAM;CAGf"}

package/dist/batcher/MessageBatcher.js

@@ -0,0 +1,86 @@
+"use strict";
+// packages/agent/src/batcher/MessageBatcher.ts
+// In-memory only. Never written to disk. Never persisted.
+// If WS drops while items are buffered → flush() routes to DurableQueue.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageBatcher = void 0;
+const protocol_1 = require("@vhyxvoid/protocol");
+class MessageBatcher {
+    onFlush;
+    onQueueFallback;
+    isConnected;
+    buffer = [];
+    timer = null;
+    constructor(
+    /** Called with serialized data when WS is available */
+    onFlush, 
+    /** Called with individual messages when WS is down — routes to DurableQueue */
+    onQueueFallback, 
+    /** Returns true when WS connection is CONNECTED */
+    isConnected) {
+        this.onFlush = onFlush;
+        this.onQueueFallback = onQueueFallback;
+        this.isConnected = isConnected;
+    }
+    /** Add a message to the batch. Flushes immediately if MAX_BATCH_SIZE reached. */
+    add(msg) {
+        this.buffer.push(msg);
+        if (this.buffer.length >= protocol_1.TIMING.BATCH_MAX_SIZE) {
+            this.flush();
+        }
+        else if (!this.timer) {
+            this.timer = setTimeout(() => this.flush(), protocol_1.TIMING.BATCH_WINDOW_MS);
+        }
+    }
+    /**
+     * Flush the buffer.
+     * - If WS is connected: send as batch (or single message if only one item)
+     * - If WS is down: route non-pong messages to DurableQueue
+     */
+    flush() {
+        if (this.buffer.length === 0)
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const messages = this.buffer.splice(0);
+        if (!this.isConnected()) {
+            // WS is down — persist responses/errors, discard pongs (ephemeral)
+            for (const msg of messages) {
+                if (msg.type !== "agent:pong") {
+                    this.onQueueFallback(msg);
+                }
+            }
+            return;
+        }
+        // WS is up — send
+        const serialized = messages.length === 1
+            ? (0, protocol_1.serialize)(messages[0])
+            : (0, protocol_1.serialize)({ v: "1", type: "agent:batch", messages });
+        this.onFlush(serialized);
+    }
+    /**
+     * Called on WS close BEFORE reconnect starts.
+     * Moves everything currently in the buffer to DurableQueue.
+     * Pongs are discarded (they are point-in-time, not meaningful after disconnect).
+     */
+    flushToQueue() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const messages = this.buffer.splice(0);
+        for (const msg of messages) {
+            if (msg.type !== "agent:pong") {
+                this.onQueueFallback(msg);
+            }
+        }
+    }
+    /** Number of messages currently buffered (for diagnostics). */
+    size() {
+        return this.buffer.length;
+    }
+}
+exports.MessageBatcher = MessageBatcher;
+//# sourceMappingURL=MessageBatcher.js.map

package/dist/batcher/MessageBatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageBatcher.js","sourceRoot":"","sources":["../../src/batcher/MessageBatcher.ts"],"names":[],"mappings":";AAAA,+CAA+C;AAC/C,0DAA0D;AAC1D,yEAAyE;;;AAEzE,iDAO4B;AAW5B,MAAa,cAAc;IAMN;IAEA;IAEA;IATX,MAAM,GAAmB,EAAE,CAAC;IAC5B,KAAK,GAA0B,IAAI,CAAC;IAE5C;IACE,uDAAuD;IACtC,OAAgB;IACjC,+EAA+E;IAC9D,eAA8B;IAC/C,mDAAmD;IAClC,WAAwB;QAJxB,YAAO,GAAP,OAAO,CAAS;QAEhB,oBAAe,GAAf,eAAe,CAAe;QAE9B,gBAAW,GAAX,WAAW,CAAa;IACxC,CAAC;IAEJ,iFAAiF;IACjF,GAAG,CAAC,GAAiB;QACnB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEtB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,iBAAM,CAAC,cAAc,EAAE,CAAC;YAChD,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;aAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACvB,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,iBAAM,CAAC,eAAe,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAErC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAEvC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,mEAAmE;YACnE,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;gBAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;oBAC9B,IAAI,CAAC,eAAe,CAAC,GAA8C,CAAC,CAAC;gBACvE,CAAC;YACH,CAAC;YACD,OAAO;QACT,CAAC;QAED,kBAAkB;QAClB,MAAM,UAAU,GACd,QAAQ,CAAC,MAAM,KAAK,CAAC;YACnB,CAAC,CAAC,IAAA,oBAAS,EAAC,QAAQ,CAAC,CAAC,CAAiB,CAAC;YACxC,CAAC,CAAC,IAAA,oBAAS,EAAC,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAmB,CAAC,CAAC;QAE5E,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC9B,IAAI,CAAC,eAAe,CAAC,GAA8C,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;IACH,CAAC;IAED,+DAA+D;IAC/D,IAAI;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF;AAjFD,wCAiFC"}

package/dist/cache/ResponseCache.d.ts

@@ -0,0 +1,50 @@
+export interface CachedResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string | null;
+    durationMs: number;
+    cachedAt: number;
+    expiresAt: number;
+    hits: number;
+}
+export declare class ResponseCache {
+    private readonly store;
+    private readonly MAX_ENTRIES;
+    /**
+     * Try to get a cached response.
+     * Returns null on miss or if method is not GET.
+     */
+    get(method: string, path: string, query: string): CachedResponse | null;
+    /**
+     * Store a response if the backend's Cache-Control header allows it.
+     * Does nothing for non-GET methods or non-cacheable responses.
+     */
+    set(method: string, path: string, query: string, response: Omit<CachedResponse, "cachedAt" | "expiresAt" | "hits">): void;
+    /**
+     * Invalidate all cached entries for a path prefix.
+     * Call after any POST/PUT/PATCH/DELETE to related resources.
+     */
+    invalidatePrefix(pathPrefix: string): number;
+    /** Remove all expired entries. Called periodically. */
+    evictExpired(): number;
+    stats(): {
+        size: number;
+        totalHits: number;
+    };
+    clear(): void;
+    private buildKey;
+    /**
+     * Parse max-age seconds from a Cache-Control header value.
+     * Returns 0 if no caching is allowed.
+     *
+     * Examples:
+     *   "max-age=300"                   → 300
+     *   "public, max-age=60"            → 60
+     *   "no-cache"                      → 0
+     *   "no-store"                      → 0
+     *   "private, max-age=120"          → 0  (private = don't cache in shared proxy)
+     *   ""                              → 0
+     */
+    private parseMaxAge;
+}
+//# sourceMappingURL=ResponseCache.d.ts.map

package/dist/cache/ResponseCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponseCache.d.ts","sourceRoot":"","sources":["../../src/cache/ResponseCache.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAG3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAO;IAEnC;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAkBvE;;;OAGG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC,GAChE,IAAI;IA0BP;;;OAGG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAW5C,uDAAuD;IACvD,YAAY,IAAI,MAAM;IAYtB,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAM5C,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,QAAQ;IAIhB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,WAAW;CAmBpB"}

package/dist/cache/ResponseCache.js

@@ -0,0 +1,127 @@
+"use strict";
+// packages/agent/src/cache/ResponseCache.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponseCache = void 0;
+class ResponseCache {
+    store = new Map();
+    // Evict entries when cache exceeds this size (LRU-lite: evict oldest)
+    MAX_ENTRIES = 500;
+    /**
+     * Try to get a cached response.
+     * Returns null on miss or if method is not GET.
+     */
+    get(method, path, query) {
+        // Only cache GET requests — POST/PUT/DELETE are never safe to cache
+        if (method.toUpperCase() !== "GET")
+            return null;
+        const key = this.buildKey(path, query);
+        const cached = this.store.get(key);
+        if (!cached)
+            return null;
+        if (Date.now() > cached.expiresAt) {
+            this.store.delete(key);
+            return null;
+        }
+        cached.hits += 1;
+        return cached;
+    }
+    /**
+     * Store a response if the backend's Cache-Control header allows it.
+     * Does nothing for non-GET methods or non-cacheable responses.
+     */
+    set(method, path, query, response) {
+        if (method.toUpperCase() !== "GET")
+            return;
+        // Only cache 2xx responses
+        if (response.status < 200 || response.status >= 300)
+            return;
+        const maxAge = this.parseMaxAge(response.headers["cache-control"] ?? "");
+        if (maxAge <= 0)
+            return; // no-cache, no-store, or no max-age directive
+        const now = Date.now();
+        const key = this.buildKey(path, query);
+        // Evict oldest entry if at capacity
+        if (this.store.size >= this.MAX_ENTRIES && !this.store.has(key)) {
+            const oldest = this.store.keys().next().value;
+            if (oldest)
+                this.store.delete(oldest);
+        }
+        this.store.set(key, {
+            ...response,
+            cachedAt: now,
+            expiresAt: now + maxAge * 1_000,
+            hits: 0,
+        });
+    }
+    /**
+     * Invalidate all cached entries for a path prefix.
+     * Call after any POST/PUT/PATCH/DELETE to related resources.
+     */
+    invalidatePrefix(pathPrefix) {
+        let count = 0;
+        for (const key of this.store.keys()) {
+            if (key.startsWith(pathPrefix)) {
+                this.store.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    /** Remove all expired entries. Called periodically. */
+    evictExpired() {
+        const now = Date.now();
+        let count = 0;
+        for (const [key, entry] of this.store) {
+            if (now > entry.expiresAt) {
+                this.store.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    stats() {
+        let totalHits = 0;
+        for (const entry of this.store.values())
+            totalHits += entry.hits;
+        return { size: this.store.size, totalHits };
+    }
+    clear() {
+        this.store.clear();
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    buildKey(path, query) {
+        return query ? `${path}?${query}` : path;
+    }
+    /**
+     * Parse max-age seconds from a Cache-Control header value.
+     * Returns 0 if no caching is allowed.
+     *
+     * Examples:
+     *   "max-age=300"                   → 300
+     *   "public, max-age=60"            → 60
+     *   "no-cache"                      → 0
+     *   "no-store"                      → 0
+     *   "private, max-age=120"          → 0  (private = don't cache in shared proxy)
+     *   ""                              → 0
+     */
+    parseMaxAge(cacheControl) {
+        if (!cacheControl)
+            return 0;
+        const lower = cacheControl.toLowerCase();
+        // Directives that mean "do not cache"
+        if (lower.includes("no-store") || lower.includes("no-cache"))
+            return 0;
+        // Private responses should not be cached at the agent level
+        // (agent acts as a shared intermediary)
+        if (lower.includes("private"))
+            return 0;
+        // Extract max-age=N
+        const match = lower.match(/max-age\s*=\s*(\d+)/);
+        if (!match)
+            return 0;
+        const seconds = parseInt(match[1], 10);
+        return isNaN(seconds) ? 0 : seconds;
+    }
+}
+exports.ResponseCache = ResponseCache;
+//# sourceMappingURL=ResponseCache.js.map