qlogicagent 2.13.4 → 2.13.5

package/dist/protocol/wire/gateway-contract.js

@@ -0,0 +1,236 @@
+import { randomUUID } from "node:crypto";
+import { AGENT_RPC_ERROR_CODES, } from "./agent-rpc.js";
+const QUERY_METHOD_PREFIXES = [
+    "settings.list",
+    "settings.get",
+    "settings.validate",
+    "provider.list",
+    "config.get",
+    "config.tunables",
+    "tools.list",
+    "todos.list",
+    "tasks.list",
+    "agents.list",
+    "agents.get",
+    "agents.processes",
+    "agents.scan",
+    "session.list",
+    "session.get",
+    "session.resolve",
+    "thread.list",
+    "project.list",
+    "files.list",
+    "files.gitStatus",
+    "instructions.list",
+    "instructions.read",
+    "skills.list",
+    "skills.stats",
+    "memory.atlas",
+    "memory.activity",
+    "memory.list",
+    "memory.read",
+    "memory.search",
+    "media.listModels",
+    "media.status",
+    "pet.status",
+    "agent.health",
+    "agent.metrics",
+];
+const LONG_TASK_METHODS = new Set([
+    "memory.dream",
+    "memory.propose",
+    "memory.consolidate",
+    "media.stt",
+    "pet.forge",
+    "pet.asset.import",
+    "solo.start",
+    "solo.evaluate",
+    "product.plan",
+    "product.create",
+    "product.message",
+]);
+const IDEMPOTENT_WRITE_PREFIXES = [
+    "memory.",
+    "pet.",
+    "usage.",
+];
+const IDEMPOTENT_WRITE_EXEMPTIONS = new Set([
+    "memory.atlas",
+    "memory.activity",
+    "memory.list",
+    "memory.read",
+    "memory.search",
+    "memory.attachment.locate",
+    "memory.attachment.adopt",
+    "pet.status",
+]);
+export function classifyGatewayRpcMethod(method) {
+    if (LONG_TASK_METHODS.has(method)) {
+        return { channel: "task", mutability: "write", defaultTimeoutMs: 120_000 };
+    }
+    if (QUERY_METHOD_PREFIXES.some((prefix) => method === prefix || method.startsWith(`${prefix}.`) || method.startsWith(prefix))) {
+        return { channel: "query", mutability: "read", defaultTimeoutMs: 10_000 };
+    }
+    return { channel: "task", mutability: "write", defaultTimeoutMs: 30_000 };
+}
+export function requiresIdempotencyKey(method) {
+    if (IDEMPOTENT_WRITE_EXEMPTIONS.has(method))
+        return false;
+    if (classifyGatewayRpcMethod(method).mutability === "read")
+        return false;
+    return IDEMPOTENT_WRITE_PREFIXES.some((prefix) => method.startsWith(prefix));
+}
+export function buildAgentRpcMeta(method, options = {}) {
+    const now = options.now ?? Date.now();
+    const classification = classifyGatewayRpcMethod(method);
+    const timeoutMs = options.timeoutMs ?? classification.defaultTimeoutMs;
+    return {
+        requestId: options.requestId ?? randomUUID(),
+        createdAt: now,
+        deadlineAt: now + timeoutMs,
+        channel: options.channel ?? classification.channel,
+        idempotencyKey: options.idempotencyKey,
+        traceId: options.traceId,
+    };
+}
+export function requireGatewayRpcMeta(request, now = Date.now()) {
+    const meta = request.meta;
+    if (!meta || typeof meta !== "object") {
+        return {
+            ok: false,
+            error: { code: AGENT_RPC_ERROR_CODES.INVALID_REQUEST, message: "RPC request meta is required." },
+        };
+    }
+    if (typeof meta.requestId !== "string" || meta.requestId.length === 0) {
+        return {
+            ok: false,
+            error: { code: AGENT_RPC_ERROR_CODES.INVALID_REQUEST, message: "RPC request meta.requestId is required." },
+        };
+    }
+    if (meta.channel !== "query" && meta.channel !== "task") {
+        return {
+            ok: false,
+            error: { code: AGENT_RPC_ERROR_CODES.INVALID_REQUEST, message: "RPC request meta.channel must be query or task." },
+        };
+    }
+    if (typeof meta.createdAt !== "number" || !Number.isFinite(meta.createdAt)) {
+        return {
+            ok: false,
+            error: { code: AGENT_RPC_ERROR_CODES.INVALID_REQUEST, message: "RPC request meta.createdAt is required." },
+        };
+    }
+    if (typeof meta.deadlineAt !== "number" || !Number.isFinite(meta.deadlineAt)) {
+        return {
+            ok: false,
+            error: { code: AGENT_RPC_ERROR_CODES.INVALID_REQUEST, message: "RPC request meta.deadlineAt is required." },
+        };
+    }
+    if (meta.deadlineAt <= now) {
+        return {
+            ok: false,
+            error: { code: AGENT_RPC_ERROR_CODES.REQUEST_DEADLINE_EXCEEDED, message: "RPC request deadline has already expired." },
+        };
+    }
+    const expected = classifyGatewayRpcMethod(request.method).channel;
+    if (meta.channel !== expected) {
+        return {
+            ok: false,
+            error: {
+                code: AGENT_RPC_ERROR_CODES.INVALID_REQUEST,
+                message: `RPC request channel mismatch: expected ${expected}, got ${meta.channel}.`,
+            },
+        };
+    }
+    if (requiresIdempotencyKey(request.method) && (typeof meta.idempotencyKey !== "string" || meta.idempotencyKey.length === 0)) {
+        return {
+            ok: false,
+            error: {
+                code: AGENT_RPC_ERROR_CODES.REQUEST_IDEMPOTENCY_REQUIRED,
+                message: `RPC method ${request.method} requires meta.idempotencyKey.`,
+            },
+        };
+    }
+    return { ok: true, meta };
+}
+export class GatewayRpcContract {
+    now;
+    active = new Map();
+    idempotency = new Map();
+    counters = {
+        completedRequests: 0,
+        cancelledRequests: 0,
+        deadlineExceededRequests: 0,
+        dedupedRequests: 0,
+        lateResponsesDropped: 0,
+        invalidRequests: 0,
+    };
+    constructor(options = {}) {
+        this.now = options.now ?? (() => Date.now());
+    }
+    begin(method, meta) {
+        const valid = requireGatewayRpcMeta({ method, meta }, this.now());
+        if (!valid.ok) {
+            this.counters.invalidRequests += 1;
+            return { status: "rejected", error: valid.error };
+        }
+        if (meta.idempotencyKey) {
+            const settled = this.idempotency.get(meta.idempotencyKey);
+            if (settled) {
+                this.counters.dedupedRequests += 1;
+                return settled.error
+                    ? { status: "deduped", error: settled.error }
+                    : { status: "deduped", result: settled.result };
+            }
+        }
+        this.active.set(meta.requestId, {
+            method,
+            meta,
+            cancelled: false,
+            startedAt: this.now(),
+        });
+        return { status: "started" };
+    }
+    cancel(requestId, reason = "cancelled") {
+        const record = this.active.get(requestId);
+        if (!record || record.cancelled)
+            return false;
+        record.cancelled = true;
+        record.cancelReason = reason;
+        this.counters.cancelledRequests += 1;
+        return true;
+    }
+    expire(requestId) {
+        const record = this.active.get(requestId);
+        if (!record)
+            return false;
+        this.active.delete(requestId);
+        this.counters.deadlineExceededRequests += 1;
+        return true;
+    }
+    settle(requestId, result, error) {
+        const record = this.active.get(requestId);
+        if (!record)
+            return { accepted: false, reason: "unknown" };
+        this.active.delete(requestId);
+        if (record.cancelled) {
+            this.counters.lateResponsesDropped += 1;
+            return { accepted: false, reason: "cancelled" };
+        }
+        if (record.meta.deadlineAt <= this.now()) {
+            this.counters.deadlineExceededRequests += 1;
+            this.counters.lateResponsesDropped += 1;
+            return { accepted: false, reason: "deadline_exceeded" };
+        }
+        this.counters.completedRequests += 1;
+        if (record.meta.idempotencyKey) {
+            this.idempotency.set(record.meta.idempotencyKey, { result, error, settledAt: this.now() });
+        }
+        return { accepted: true };
+    }
+    metrics() {
+        return {
+            activeRequests: this.active.size,
+            ...this.counters,
+        };
+    }
+}

package/dist/protocol/wire/gateway-contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/protocol/wire/gateway-contract.test.js

@@ -0,0 +1,123 @@
+import { describe, expect, it, vi } from "vitest";
+import { AGENT_RPC_ERROR_CODES, GATEWAY_RPC_METHODS, GatewayRpcContract, buildAgentRpcMeta, classifyGatewayRpcMethod, requireGatewayRpcMeta, requiresIdempotencyKey, } from "./index.js";
+describe("gateway-agent RPC contract", () => {
+    it("requires an explicit deadline, request id, and channel on every RPC request", () => {
+        const now = 1_000;
+        const valid = requireGatewayRpcMeta({
+            method: "memory.atlas",
+            meta: {
+                requestId: "req-1",
+                deadlineAt: now + 1_000,
+                channel: "query",
+                createdAt: now,
+            },
+        }, now);
+        expect(valid.ok).toBe(true);
+        const missing = requireGatewayRpcMeta({ method: "memory.atlas" }, now);
+        expect(missing).toMatchObject({
+            ok: false,
+            error: {
+                code: AGENT_RPC_ERROR_CODES.INVALID_REQUEST,
+                message: "RPC request meta is required.",
+            },
+        });
+        const expired = requireGatewayRpcMeta({
+            method: "memory.atlas",
+            meta: {
+                requestId: "req-expired",
+                deadlineAt: now - 1,
+                channel: "query",
+                createdAt: now - 5_000,
+            },
+        }, now);
+        expect(expired).toMatchObject({
+            ok: false,
+            error: {
+                code: AGENT_RPC_ERROR_CODES.REQUEST_DEADLINE_EXCEEDED,
+                message: "RPC request deadline has already expired.",
+            },
+        });
+    });
+    it("classifies read queries and long tasks onto separate channels", () => {
+        expect(classifyGatewayRpcMethod("memory.atlas")).toEqual({
+            channel: "query",
+            mutability: "read",
+            defaultTimeoutMs: 10_000,
+        });
+        expect(classifyGatewayRpcMethod("agent.health")).toEqual({
+            channel: "query",
+            mutability: "read",
+            defaultTimeoutMs: 10_000,
+        });
+        expect(classifyGatewayRpcMethod("agent.metrics")).toEqual({
+            channel: "query",
+            mutability: "read",
+            defaultTimeoutMs: 10_000,
+        });
+        // Default classification (not a long-task, not a query prefix) → task/write/30s.
+        expect(classifyGatewayRpcMethod("config.update")).toEqual({
+            channel: "task",
+            mutability: "write",
+            defaultTimeoutMs: 30_000,
+        });
+        expect(classifyGatewayRpcMethod("config.updateTunable")).toEqual({
+            channel: "task",
+            mutability: "write",
+            defaultTimeoutMs: 30_000,
+        });
+        expect(classifyGatewayRpcMethod("media.stt")).toEqual({
+            channel: "task",
+            mutability: "write",
+            defaultTimeoutMs: 120_000,
+        });
+    });
+    it("requires idempotency keys for memory, usage, and pet writes", () => {
+        expect(requiresIdempotencyKey("memory.observe")).toBe(true);
+        expect(requiresIdempotencyKey("memory.consolidate")).toBe(true);
+        expect(requiresIdempotencyKey("pet.forge")).toBe(true);
+        expect(requiresIdempotencyKey("usage.record")).toBe(true);
+        expect(requiresIdempotencyKey("memory.atlas")).toBe(false);
+    });
+    it("does not expose the removed pet activation RPC", () => {
+        const removedRpc = ["pet", ["ha", "tch"].join("")].join(".");
+        expect(GATEWAY_RPC_METHODS).not.toContain(removedRpc);
+    });
+    it("deduplicates same idempotency key and returns the settled result", async () => {
+        vi.useFakeTimers();
+        const contract = new GatewayRpcContract({ now: () => Date.now() });
+        const meta = buildAgentRpcMeta("memory.consolidate", {
+            now: Date.now(),
+            idempotencyKey: "memory:user-1:abc",
+        });
+        const first = contract.begin("memory.consolidate", meta);
+        expect(first.status).toBe("started");
+        contract.settle(meta.requestId, { ok: true, memoriesAdded: 1 });
+        const duplicate = contract.begin("memory.consolidate", {
+            ...buildAgentRpcMeta("memory.consolidate", {
+                now: Date.now(),
+                idempotencyKey: "memory:user-1:abc",
+            }),
+            requestId: "retry-request",
+        });
+        expect(duplicate).toEqual({
+            status: "deduped",
+            result: { ok: true, memoriesAdded: 1 },
+        });
+        expect(contract.metrics().dedupedRequests).toBe(1);
+        vi.useRealTimers();
+    });
+    it("cancels requests and drops late responses after deadline", () => {
+        const contract = new GatewayRpcContract({ now: () => 1_000 });
+        const meta = buildAgentRpcMeta("memory.atlas", { now: 1_000, timeoutMs: 200 });
+        expect(contract.begin("memory.atlas", meta).status).toBe("started");
+        expect(contract.cancel(meta.requestId, "user-cancelled")).toBe(true);
+        expect(contract.settle(meta.requestId, { ok: true })).toEqual({ accepted: false, reason: "cancelled" });
+        let now = 1_000;
+        const late = new GatewayRpcContract({ now: () => now });
+        const lateMeta = buildAgentRpcMeta("memory.atlas", { now: 1_000, timeoutMs: 200 });
+        expect(late.begin("memory.atlas", lateMeta).status).toBe("started");
+        now = 5_000;
+        expect(late.settle(lateMeta.requestId, { ok: true })).toEqual({ accepted: false, reason: "deadline_exceeded" });
+        expect(late.metrics().lateResponsesDropped).toBe(1);
+    });
+});