@clawcrony/claw-crony 1.0.1

package/dist/src/hub-match.js

@@ -0,0 +1,120 @@
+/**
+ * Hub Match API client for openclaw-a2a-gateway.
+ *
+ * Provides a typed client for the hub's /api/matches endpoints:
+ * - POST   /api/matches              createMatch
+ * - GET    /api/matches/{id}         getMatch
+ * - GET    /api/matches/pending       getPendingMatches
+ * - POST   /api/matches/{id}/token   submitToken
+ * - POST   /api/matches/{id}/complete completeMatch
+ * - POST   /api/matches/{id}/cancel  cancelMatch
+ */
+import { loadRegistration } from "./hub-registration.js";
+// ---------------------------------------------------------------------------
+// HubMatchClient
+// ---------------------------------------------------------------------------
+export class HubMatchClient {
+    hubUrl;
+    registration;
+    constructor(hubUrl, registration) {
+        this.hubUrl = hubUrl.replace(/\/$/, "");
+        this.registration = registration;
+    }
+    static async create() {
+        const registration = loadRegistration();
+        if (!registration) {
+            throw new Error("No hub registration found. Run the gateway first to register with the hub.");
+        }
+        const configUrl = registration.hubUrl;
+        return new HubMatchClient(configUrl, registration);
+    }
+    async request(path, options = {}) {
+        const url = `${this.hubUrl}${path}`;
+        const res = await fetch(url, {
+            ...options,
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${this.registration.token}`,
+                ...(options.headers ?? {}),
+            },
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({}));
+            throw new Error(`Hub match API error ${res.status}: ${JSON.stringify(body)}`);
+        }
+        return res.json();
+    }
+    /**
+     * Create a new match request.
+     * @param params.skills - Skills to search for in a provider
+     * @param params.description - Optional description of the match request
+     * @param params.token - Optional bearer token to include for this agent
+     */
+    async createMatch(params) {
+        return this.request("/api/matches", {
+            method: "POST",
+            body: JSON.stringify({
+                agentId: this.registration.agentId,
+                requiredSkills: params.skills,
+                description: params.description ?? "",
+                token: params.token,
+            }),
+        });
+    }
+    /**
+     * Get a match result by ID.
+     * @param matchId - The match ID
+     * @param callerId - Optional agent ID to set callerId query param (affects yourToken)
+     */
+    async getMatch(matchId, callerId) {
+        const path = callerId != null ? `/api/matches/${matchId}?callerId=${callerId}` : `/api/matches/${matchId}`;
+        return this.request(path);
+    }
+    /**
+     * Get all pending matches for this agent.
+     */
+    async getPendingMatches() {
+        return this.request(`/api/matches/pending?agentId=${this.registration.agentId}`);
+    }
+    /**
+     * Submit this agent's token for a match.
+     * @param matchId - The match ID
+     * @param token - This agent's bearer token
+     */
+    async submitToken(matchId, token) {
+        return this.request(`/api/matches/${matchId}/token`, {
+            method: "POST",
+            body: JSON.stringify({
+                agentId: this.registration.agentId,
+                token,
+            }),
+        });
+    }
+    /**
+     * Mark a match as completed (both parties have submitted tokens).
+     * @param matchId - The match ID
+     * @param token - This agent's bearer token (for authorization)
+     */
+    async completeMatch(matchId, token) {
+        return this.request(`/api/matches/${matchId}/complete`, {
+            method: "POST",
+            body: JSON.stringify({
+                agentId: this.registration.agentId,
+            }),
+        });
+    }
+    /**
+     * Cancel a pending or token_exchange match.
+     * @param matchId - The match ID
+     * @param token - This agent's bearer token (for authorization)
+     */
+    async cancelMatch(matchId, token) {
+        return this.request(`/api/matches/${matchId}/cancel`, {
+            method: "POST",
+            body: JSON.stringify({
+                agentId: this.registration.agentId,
+            }),
+        });
+    }
+}
+//# sourceMappingURL=hub-match.js.map

package/dist/src/hub-match.js.map

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

package/dist/src/hub-registration.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Hub registration module for openclaw-a2a-gateway.
+ *
+ * Handles automatic registration of the gateway with the hub server on first startup,
+ * token generation, and idempotent re-registration.
+ */
+import type { GatewayConfig, HubConfig, HubRegistrationData, OpenClawPluginApi, RegistrationConfig } from "./types.js";
+export declare function loadRegistration(configDir?: string): HubRegistrationData | null;
+export declare function saveRegistration(configDir: string, data: HubRegistrationData): void;
+export interface HubRegistration {
+    agentId: number;
+    token: string;
+    address: string;
+    name: string;
+}
+/**
+ * Run the full hub registration flow:
+ * 1. Load existing registration (if any)
+ * 2. Validate existing token with hub
+ * 3. If no valid registration, create new one (handling 409 conflicts)
+ * 4. Save registration file atomically
+ */
+export declare function runHubRegistration(api: OpenClawPluginApi, config: GatewayConfig, hubConfig: HubConfig, registrationConfig: RegistrationConfig): Promise<HubRegistration | null>;
+//# sourceMappingURL=hub-registration.d.ts.map

package/dist/src/hub-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-registration.d.ts","sourceRoot":"","sources":["../../src/hub-registration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAwBpB,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAQ/E;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,mBAAmB,GACxB,IAAI,CAKN;AAiGD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,EACpB,kBAAkB,EAAE,kBAAkB,GACrC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAyJjC"}

package/dist/src/hub-registration.js

@@ -0,0 +1,242 @@
+/**
+ * Hub registration module for openclaw-a2a-gateway.
+ *
+ * Handles automatic registration of the gateway with the hub server on first startup,
+ * token generation, and idempotent re-registration.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// Token generation
+// ---------------------------------------------------------------------------
+function generateToken() {
+    return crypto.randomBytes(32).toString("hex");
+}
+// ---------------------------------------------------------------------------
+// Registration file path & I/O
+// ---------------------------------------------------------------------------
+const REGISTRATION_FILENAME = "a2a-registration.json";
+function getRegistrationPath(configDir) {
+    return path.join(configDir, REGISTRATION_FILENAME);
+}
+function getConfigDir() {
+    return path.join(os.homedir(), ".openclaw");
+}
+export function loadRegistration(configDir) {
+    const regPath = getRegistrationPath(configDir ?? getConfigDir());
+    try {
+        const raw = fs.readFileSync(regPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveRegistration(configDir, data) {
+    const regPath = path.join(configDir, REGISTRATION_FILENAME);
+    const tmpPath = `${regPath}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+    fs.renameSync(tmpPath, regPath);
+}
+async function registerWithHub(hubUrl, payload) {
+    const url = `${hubUrl.replace(/\/$/, "")}/api/agents`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    if (res.status === 409) {
+        const err = await res.json().catch(() => ({}));
+        throw Object.assign(new Error("Agent address already registered"), { status: 409, body: err });
+    }
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        throw Object.assign(new Error(`Hub rejected registration: ${JSON.stringify(err)}`), { status: res.status });
+    }
+    return res.json();
+}
+async function lookupAgentByAddress(hubUrl, address) {
+    const url = `${hubUrl.replace(/\/$/, "")}/api/agents?address=${encodeURIComponent(address)}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw Object.assign(new Error(`Hub lookup failed: ${res.status}`), { status: res.status });
+    }
+    const agents = await res.json();
+    return agents.length > 0 ? agents[0] : null;
+}
+// ---------------------------------------------------------------------------
+// Retry with exponential backoff
+// ---------------------------------------------------------------------------
+async function retryWithBackoff(fn, maxRetries, baseDelayMs, maxDelayMs) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < maxRetries) {
+                const delay = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+                await new Promise((r) => setTimeout(r, delay));
+            }
+        }
+    }
+    throw lastError;
+}
+// ---------------------------------------------------------------------------
+// Flatten skills from agent card config
+// ---------------------------------------------------------------------------
+function flattenSkills(skills) {
+    return skills.map((s) => (typeof s === "string" ? s : s.name));
+}
+/**
+ * Run the full hub registration flow:
+ * 1. Load existing registration (if any)
+ * 2. Validate existing token with hub
+ * 3. If no valid registration, create new one (handling 409 conflicts)
+ * 4. Save registration file atomically
+ */
+export async function runHubRegistration(api, config, hubConfig, registrationConfig) {
+    const configDir = getConfigDir();
+    const hubUrl = hubConfig.url;
+    // Derive address from agentCard.url (the externally reachable address), not server.bind
+    // e.g. "http://100.10.10.1:18800/a2a/jsonrpc" -> "100.10.10.1:18800"
+    let address;
+    if (config.agentCard.url) {
+        try {
+            const urlObj = new URL(config.agentCard.url);
+            address = `${urlObj.hostname}:${urlObj.port || (urlObj.protocol === "https:" ? 443 : 80)}`;
+        }
+        catch {
+            address = `${config.server.host}:${config.server.port}`;
+        }
+    }
+    else {
+        address = `${config.server.host}:${config.server.port}`;
+    }
+    // Ensure config directory exists
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    // Load existing registration
+    const existing = loadRegistration(configDir);
+    // If we have a registration with a matching address and token, validate it
+    if (existing && existing.address === address && existing.hubUrl === hubUrl && existing.token) {
+        try {
+            const agent = await lookupAgentByAddress(hubUrl, address);
+            if (agent && agent.id === existing.agentId) {
+                api.logger.info(`a2a-gateway: using existing hub registration (agentId=${existing.agentId})`);
+                return {
+                    agentId: existing.agentId,
+                    token: existing.token,
+                    address: existing.address,
+                    name: existing.name,
+                };
+            }
+        }
+        catch {
+            // Hub unreachable or agent not found — try re-registering with existing token first
+            api.logger.warn("a2a-gateway: existing registration invalid, trying with existing token");
+            const existingToken = existing.token;
+            try {
+                const existingPayload = {
+                    name: config.agentCard.name,
+                    description: config.agentCard.description ?? "",
+                    skills: flattenSkills(config.agentCard.skills),
+                    address,
+                    token: existingToken,
+                    username: registrationConfig.username ?? config.agentCard.name,
+                    email: registrationConfig.email ?? "",
+                };
+                const agent = await retryWithBackoff(() => registerWithHub(hubUrl, existingPayload), 3, 1000, 10000);
+                api.logger.info(`a2a-gateway: re-registered with hub using existing token (agentId=${agent.id})`);
+                // Re-save to update registration file
+                const updatedData = {
+                    ...existing,
+                    registeredAt: new Date().toISOString(),
+                };
+                saveRegistration(configDir, updatedData);
+                return { agentId: agent.id, token: existingToken, address, name: config.agentCard.name };
+            }
+            catch (err) {
+                // Existing token also failed (409 means address conflict from elsewhere)
+                const status = typeof err === "object" && err !== null ? err.status : undefined;
+                if (status === 409) {
+                    api.logger.warn("a2a-gateway: existing token rejected, generating new token");
+                }
+                else {
+                    api.logger.warn(`a2a-gateway: re-registration with existing token failed — ${err instanceof Error ? err.message : String(err)}`);
+                }
+                // fall through to generate new token
+            }
+        }
+    }
+    // Generate new token
+    const token = generateToken();
+    const name = config.agentCard.name;
+    const description = config.agentCard.description ?? "";
+    const skills = flattenSkills(config.agentCard.skills);
+    const username = registrationConfig.username ?? name;
+    const email = registrationConfig.email ?? "";
+    const payload = {
+        name,
+        description,
+        skills,
+        address,
+        token,
+        username,
+        email,
+    };
+    let agentId;
+    try {
+        const agent = await retryWithBackoff(() => registerWithHub(hubUrl, payload), 3, 1000, 10000);
+        agentId = agent.id;
+        api.logger.info(`a2a-gateway: registered with hub (agentId=${agentId})`);
+    }
+    catch (err) {
+        // 409 Conflict: address already registered by someone else — try to find our agentId
+        if (typeof err === "object" && err !== null && err.status === 409) {
+            try {
+                const existingAgent = await lookupAgentByAddress(hubUrl, address);
+                if (existingAgent) {
+                    agentId = existingAgent.id;
+                    api.logger.info(`a2a-gateway: found existing registration (agentId=${agentId})`);
+                }
+                else {
+                    api.logger.error("a2a-gateway: address conflict but could not find existing agent");
+                    return null;
+                }
+            }
+            catch {
+                api.logger.error("a2a-gateway: address conflict and hub lookup failed");
+                return null;
+            }
+        }
+        else {
+            api.logger.warn(`a2a-gateway: hub registration failed — ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    // Save registration file
+    const registrationData = {
+        version: 1,
+        hubUrl,
+        agentId,
+        address,
+        token,
+        registeredAt: new Date().toISOString(),
+        name,
+        description,
+        skills,
+    };
+    try {
+        saveRegistration(configDir, registrationData);
+    }
+    catch (saveErr) {
+        api.logger.warn(`a2a-gateway: failed to save registration file — ${saveErr instanceof Error ? saveErr.message : String(saveErr)}`);
+    }
+    return { agentId, token, address, name };
+}
+//# sourceMappingURL=hub-registration.js.map

package/dist/src/hub-registration.js.map

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

package/dist/src/internal/envelope.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A2A Gateway — Envelope creation and validation
+ *
+ * OpenClaw gateway-internal module — NOT part of the A2A spec.
+ */
+import type { A2AEnvelope, A2AAck, A2AConfig, A2ASource, A2ADestination, MessageType } from "./types-internal.js";
+export type EnvelopeErrorCode = "INVALID_VERSION" | "MISSING_FIELD" | "INVALID_TYPE" | "EXPIRED" | "LOOP_DETECTED" | "HOP_LIMIT" | "PAYLOAD_TOO_LARGE";
+export interface EnvelopeError {
+    code: EnvelopeErrorCode;
+    message: string;
+}
+/** Generate a ULID-like time-ordered unique ID: `{timestamp_hex}-{uuid_last12}` */
+export declare function generateId(): string;
+export interface CreateEnvelopeOpts {
+    source: A2ASource;
+    destination: A2ADestination;
+    message_type: MessageType;
+    payload: unknown;
+    ttl_seconds?: number;
+    correlation_id?: string;
+    trace_id?: string;
+    span_id?: string;
+    idempotency_key?: string;
+    hop_count?: number;
+    route_path?: string[];
+}
+/** Build a valid A2AEnvelope with sensible defaults. */
+export declare function createEnvelope(opts: CreateEnvelopeOpts): A2AEnvelope;
+/** Validate an incoming envelope. Returns null on success or an EnvelopeError. */
+export declare function validateEnvelope(envelope: A2AEnvelope, config: A2AConfig): EnvelopeError | null;
+/** Create an A2AAck in response to an envelope. */
+export declare function createAck(envelope: A2AEnvelope, gatewayId: string, status: "accepted" | "rejected", reason?: string): A2AAck;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/src/internal/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../src/internal/envelope.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,MAAM,EACN,SAAS,EACT,SAAS,EACT,cAAc,EACd,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAM7B,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,eAAe,GACf,cAAc,GACd,SAAS,GACT,eAAe,GACf,WAAW,GACX,mBAAmB,CAAC;AAExB,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAkBD,mFAAmF;AACnF,wBAAgB,UAAU,IAAI,MAAM,CAKnC;AAMD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,CAAC;IAClB,WAAW,EAAE,cAAc,CAAC;IAC5B,YAAY,EAAE,WAAW,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,WAAW,CAiBpE;AAMD,kFAAkF;AAClF,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,SAAS,GAChB,aAAa,GAAG,IAAI,CAsGtB;AAMD,mDAAmD;AACnD,wBAAgB,SAAS,CACvB,QAAQ,EAAE,WAAW,EACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,GAAG,UAAU,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAWR"}

package/dist/src/internal/envelope.js

@@ -0,0 +1,152 @@
+/**
+ * A2A Gateway — Envelope creation and validation
+ *
+ * OpenClaw gateway-internal module — NOT part of the A2A spec.
+ */
+import crypto from "node:crypto";
+// ---------------------------------------------------------------------------
+// Valid message types
+// ---------------------------------------------------------------------------
+const VALID_MESSAGE_TYPES = new Set([
+    "command",
+    "event",
+    "response",
+    "error",
+    "ack",
+]);
+// ---------------------------------------------------------------------------
+// ID generation
+// ---------------------------------------------------------------------------
+/** Generate a ULID-like time-ordered unique ID: `{timestamp_hex}-{uuid_last12}` */
+export function generateId() {
+    const timestampHex = Date.now().toString(16);
+    const uuid = crypto.randomUUID().replace(/-/g, "");
+    const last12 = uuid.slice(-12);
+    return `${timestampHex}-${last12}`;
+}
+/** Build a valid A2AEnvelope with sensible defaults. */
+export function createEnvelope(opts) {
+    return {
+        protocol_version: "a2a/v1",
+        message_id: generateId(),
+        idempotency_key: opts.idempotency_key ?? generateId(),
+        correlation_id: opts.correlation_id,
+        timestamp: new Date().toISOString(),
+        ttl_seconds: opts.ttl_seconds ?? 300,
+        trace_id: opts.trace_id,
+        span_id: opts.span_id,
+        source: opts.source,
+        destination: opts.destination,
+        message_type: opts.message_type,
+        hop_count: opts.hop_count ?? 0,
+        route_path: opts.route_path ?? [],
+        payload: opts.payload,
+    };
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/** Validate an incoming envelope. Returns null on success or an EnvelopeError. */
+export function validateEnvelope(envelope, config) {
+    // Protocol version
+    if (envelope.protocol_version !== "a2a/v1") {
+        return {
+            code: "INVALID_VERSION",
+            message: `Unsupported protocol version: ${envelope.protocol_version}`,
+        };
+    }
+    // Required fields
+    const requiredFields = [
+        { key: "message_id", value: envelope.message_id },
+        { key: "idempotency_key", value: envelope.idempotency_key },
+        { key: "timestamp", value: envelope.timestamp },
+        { key: "source.gateway_id", value: envelope.source?.gateway_id },
+        { key: "destination", value: envelope.destination },
+        { key: "message_type", value: envelope.message_type },
+    ];
+    for (const { key, value } of requiredFields) {
+        if (value === undefined || value === null || value === "") {
+            return { code: "MISSING_FIELD", message: `Missing required field: ${key}` };
+        }
+    }
+    // Message type
+    if (!VALID_MESSAGE_TYPES.has(envelope.message_type)) {
+        return {
+            code: "INVALID_TYPE",
+            message: `Invalid message_type: ${envelope.message_type}`,
+        };
+    }
+    // Field type validation
+    if (typeof envelope.ttl_seconds !== "number" ||
+        !Number.isFinite(envelope.ttl_seconds) ||
+        envelope.ttl_seconds <= 0) {
+        return {
+            code: "MISSING_FIELD",
+            message: "ttl_seconds must be a finite positive number",
+        };
+    }
+    if (typeof envelope.hop_count !== "number" ||
+        !Number.isFinite(envelope.hop_count) ||
+        !Number.isInteger(envelope.hop_count) ||
+        envelope.hop_count < 0) {
+        return {
+            code: "MISSING_FIELD",
+            message: "hop_count must be a finite non-negative integer",
+        };
+    }
+    if (!Array.isArray(envelope.route_path) ||
+        !envelope.route_path.every((p) => typeof p === "string")) {
+        return {
+            code: "MISSING_FIELD",
+            message: "route_path must be an array of strings",
+        };
+    }
+    // TTL expiry
+    const envelopeTime = Date.parse(envelope.timestamp);
+    if (isNaN(envelopeTime)) {
+        return { code: "MISSING_FIELD", message: "Invalid timestamp format" };
+    }
+    if (envelopeTime + envelope.ttl_seconds * 1000 <= Date.now()) {
+        return { code: "EXPIRED", message: "Envelope TTL has expired" };
+    }
+    // Anti-loop: reject if our own gateway is already in route_path
+    if (envelope.route_path.includes(config.gatewayId)) {
+        return {
+            code: "LOOP_DETECTED",
+            message: `Loop detected: ${config.gatewayId} already in route_path`,
+        };
+    }
+    // Hop limit
+    if (envelope.hop_count >= config.limits.maxHops) {
+        return {
+            code: "HOP_LIMIT",
+            message: `Hop count ${envelope.hop_count} exceeds limit ${config.limits.maxHops}`,
+        };
+    }
+    // Payload size
+    const payloadSize = Buffer.byteLength(JSON.stringify(envelope.payload), "utf8");
+    if (payloadSize > config.limits.maxPayloadBytes) {
+        return {
+            code: "PAYLOAD_TOO_LARGE",
+            message: `Payload size ${payloadSize} exceeds limit ${config.limits.maxPayloadBytes}`,
+        };
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// ACK creation
+// ---------------------------------------------------------------------------
+/** Create an A2AAck in response to an envelope. */
+export function createAck(envelope, gatewayId, status, reason) {
+    return {
+        protocol_version: "a2a/v1",
+        message_id: generateId(),
+        correlation_id: envelope.message_id,
+        source: { gateway_id: gatewayId },
+        message_type: "ack",
+        timestamp: new Date().toISOString(),
+        status,
+        reason,
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/src/internal/envelope.js.map

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

package/dist/src/internal/idempotency.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A2A Gateway Plugin — Idempotency Store
+ *
+ * OpenClaw gateway-internal module — NOT part of the A2A spec.
+ * SHA-256 payload fingerprinting and in-memory deduplication
+ * with configurable TTL and periodic cleanup.
+ */
+/** Create a SHA-256 hex fingerprint of the given payload string. */
+export declare function createFingerprint(payload: string): string;
+export type CheckResult = {
+    status: "new";
+} | {
+    status: "duplicate";
+    response: string;
+} | {
+    status: "conflict";
+};
+export interface IdempotencyStoreConfig {
+    defaultTtlSeconds: number;
+}
+export declare class IdempotencyStore {
+    private entries;
+    private timer;
+    private config;
+    private expiredCleaned;
+    constructor(config: IdempotencyStoreConfig);
+    /**
+     * Check whether a key has been seen before.
+     * - Not found -> `{ status: 'new' }`
+     * - Found with same fingerprint -> `{ status: 'duplicate', response }`
+     * - Found with different fingerprint -> `{ status: 'conflict' }`
+     */
+    check(key: string, payloadFingerprint: string): CheckResult;
+    /** Store a response keyed by idempotency key with optional TTL override. */
+    store(key: string, payloadFingerprint: string, response: string, ttlSeconds?: number): void;
+    /** Remove all expired entries. */
+    cleanup(): void;
+    /** Return summary stats. */
+    getStats(): {
+        total: number;
+        expired_cleaned: number;
+    };
+    /** Start periodic cleanup. Default interval is 60 000 ms. */
+    startCleanup(intervalMs?: number): void;
+    /** Stop periodic cleanup. */
+    stopCleanup(): void;
+}
+//# sourceMappingURL=idempotency.d.ts.map