@masons/agent-network 0.1.9 → 0.2.0

package/dist/channel.d.ts

@@ -13,6 +13,8 @@ interface ChannelCapabilities {
 interface ChannelConfigAdapter<T> {
     listAccountIds(cfg: Record<string, unknown>): string[];
     resolveAccount(cfg: Record<string, unknown>, accountId?: string): T;
+    isConfigured?(account: T, cfg: Record<string, unknown>): boolean;
+    isEnabled?(account: T, cfg: Record<string, unknown>): boolean;
 }
 interface OutboundDeliveryResult {
     ok: boolean;

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAWtD,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;CACrE;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,UAAU,cAAc;IACtB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/C;AAED,UAAU,eAAe;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,iBAAiB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAC1C,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;CAC7C;AAwDD,eAAO,MAAM,WAAW,EAAE,iBA2KzB,CAAC"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAWtD,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACpE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IACjE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,UAAU,cAAc;IACtB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/C;AAED,UAAU,eAAe;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,iBAAiB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAC1C,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;CAC7C;AAwDD,eAAO,MAAM,WAAW,EAAE,iBAsLzB,CAAC"}

package/dist/channel.js

@@ -52,38 +52,45 @@ export const mstpChannel = {
         attachments: false,
     },
     config: {
-        listAccountIds(cfg) {
-            const mstpCfg = extractMstpConfig(cfg);
-            if (!mstpCfg)
-                return [];
-            const accountsCfg = mstpCfg.accounts;
-            if (typeof accountsCfg !== "object" || accountsCfg === null)
-                return [];
-            return Object.keys(accountsCfg);
+        // Always return ["default"] — matches community convention (Telegram,
+        // Slack, Feishu all do this). Gateway uses isConfigured() to decide
+        // whether to start the account, not the presence of account IDs.
+        listAccountIds() {
+            return ["default"];
         },
         resolveAccount(cfg, accountId) {
             const mstpCfg = extractMstpConfig(cfg);
             if (!mstpCfg || !accountId) {
-                throw new Error("No accounts configured");
+                return { connectorUrl: "", token: "" };
             }
             const accountsCfg = mstpCfg.accounts;
             if (typeof accountsCfg !== "object" || accountsCfg === null) {
-                throw new Error("No accounts configured");
+                return { connectorUrl: "", token: "" };
             }
             const raw = accountsCfg[accountId];
             if (typeof raw !== "object" || raw === null) {
-                throw new Error(`Invalid account configuration: ${accountId}`);
+                return { connectorUrl: "", token: "" };
             }
             const account = raw;
             if (typeof account.connectorUrl !== "string" ||
                 typeof account.token !== "string") {
-                throw new Error(`Invalid account configuration: ${accountId}`);
+                return { connectorUrl: "", token: "" };
             }
             return {
                 connectorUrl: account.connectorUrl,
                 token: account.token,
             };
         },
+        // Gateway calls this after resolveAccount(). Return false when
+        // credentials are missing — Gateway marks the channel as "unmanaged"
+        // and skips health checks + startAccount().
+        isConfigured(account) {
+            return account.connectorUrl !== "" && account.token !== "";
+        },
+        isEnabled(account, cfg) {
+            const mstpCfg = extractMstpConfig(cfg);
+            return mstpCfg?.enabled !== false;
+        },
     },
     outbound: {
         deliveryMode: "direct",

package/dist/platform-client.d.ts

@@ -61,6 +61,34 @@ export interface RequestConnectionResponse {
     requestIds: string[];
     status: string;
 }
+export interface ListRequestsResponse {
+    total: number;
+    items: Array<{
+        id: string;
+        fromAgent: {
+            handle: string;
+            name: string;
+        };
+        variant: string;
+        status: string;
+        matchmaking: {
+            title: string | null;
+            benefit: string | null;
+            scenario: string | null;
+        };
+        createdAt: string;
+    }>;
+}
+export interface AcceptRequestResponse {
+    status: "accepted";
+    connection: {
+        handle: string;
+        name: string;
+    };
+}
+export interface DeclineRequestResponse {
+    status: "declined";
+}
 /**
  * `POST /setup/init` — Start Device Code Flow.
  *
@@ -101,7 +129,7 @@ export declare function onboard(cfg: PlatformClientConfig, setupToken: string, p
  */
 export declare function reconnect(cfg: PlatformClientConfig, setupToken: string, agentId: string): Promise<ReconnectResponse>;
 /**
- * `POST /connections/request` — Send a connection request.
+ * `POST /connections/requests` — Send a connection request.
  *
  * Requires API Key in Authorization header.
  * Idempotent: returns 201 with empty requestIds if already connected.
@@ -110,4 +138,26 @@ export declare function requestConnection(cfg: PlatformClientConfig, apiKey: str
     targetHandle: string;
     variants: ("distribute" | "receive")[];
 }): Promise<RequestConnectionResponse>;
+/**
+ * `GET /connections/requests` — List incoming connection requests.
+ *
+ * Requires API Key in Authorization header.
+ */
+export declare function listRequests(cfg: PlatformClientConfig, apiKey: string, params?: {
+    status?: string;
+    page?: number;
+    limit?: number;
+}): Promise<ListRequestsResponse>;
+/**
+ * `POST /connections/requests/{id}/accept` — Accept a connection request.
+ *
+ * Requires API Key in Authorization header.
+ */
+export declare function acceptRequest(cfg: PlatformClientConfig, apiKey: string, requestId: string): Promise<AcceptRequestResponse>;
+/**
+ * `POST /connections/requests/{id}/decline` — Decline a connection request.
+ *
+ * Requires API Key in Authorization header.
+ */
+export declare function declineRequest(cfg: PlatformClientConfig, apiKey: string, requestId: string): Promise<DeclineRequestResponse>;
 //# sourceMappingURL=platform-client.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"platform-client.d.ts","sourceRoot":"","sources":["../src/platform-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,wBAAwB;AACxB,eAAO,MAAM,gBAAgB,+BAA+B,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED,0EAA0E;AAC1E,qBAAa,iBAAkB,SAAQ,gBAAgB;gBACzC,OAAO,SAA0B;CAI9C;AAED,oEAAoE;AACpE,qBAAa,iBAAkB,SAAQ,gBAAgB;gBACzC,OAAO,SAAwB;CAI5C;AAMD,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qCAAqC;AACrC,MAAM,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEhD,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AA0BD;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAO5B;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,oBAAoB,EACzB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAQ5B;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,oBAAoB,EACzB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,CAAC,CAM7B;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAE,oBAAoB,EACzB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,OAAO,CAAC,eAAe,CAAC,CAW1B;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,oBAAoB,EACzB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,iBAAiB,CAAC,CAa5B;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,oBAAoB,EACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,YAAY,GAAG,SAAS,CAAC,EAAE,CAAA;CAAE,GACvE,OAAO,CAAC,yBAAyB,CAAC,CAWpC"}
+{"version":3,"file":"platform-client.d.ts","sourceRoot":"","sources":["../src/platform-client.ts"],"names":[],"mappings":"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"}

package/dist/platform-client.js

@@ -143,13 +143,13 @@ export async function reconnect(cfg, setupToken, agentId) {
     return (await res.json());
 }
 /**
- * `POST /connections/request` — Send a connection request.
+ * `POST /connections/requests` — Send a connection request.
  *
  * Requires API Key in Authorization header.
  * Idempotent: returns 201 with empty requestIds if already connected.
  */
 export async function requestConnection(cfg, apiKey, params) {
-    const res = await fetch(`${baseUrl(cfg)}/connections/request`, {
+    const res = await fetch(`${baseUrl(cfg)}/connections/requests`, {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
@@ -161,3 +161,53 @@ export async function requestConnection(cfg, apiKey, params) {
         return handleError(res);
     return (await res.json());
 }
+/**
+ * `GET /connections/requests` — List incoming connection requests.
+ *
+ * Requires API Key in Authorization header.
+ */
+export async function listRequests(cfg, apiKey, params) {
+    const query = new URLSearchParams();
+    if (params?.status != null)
+        query.set("status", params.status);
+    if (params?.page != null)
+        query.set("page", String(params.page));
+    if (params?.limit != null)
+        query.set("limit", String(params.limit));
+    const qs = query.toString();
+    const url = `${baseUrl(cfg)}/connections/requests${qs ? `?${qs}` : ""}`;
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok)
+        return handleError(res);
+    return (await res.json());
+}
+/**
+ * `POST /connections/requests/{id}/accept` — Accept a connection request.
+ *
+ * Requires API Key in Authorization header.
+ */
+export async function acceptRequest(cfg, apiKey, requestId) {
+    const res = await fetch(`${baseUrl(cfg)}/connections/requests/${encodeURIComponent(requestId)}/accept`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok)
+        return handleError(res);
+    return (await res.json());
+}
+/**
+ * `POST /connections/requests/{id}/decline` — Decline a connection request.
+ *
+ * Requires API Key in Authorization header.
+ */
+export async function declineRequest(cfg, apiKey, requestId) {
+    const res = await fetch(`${baseUrl(cfg)}/connections/requests/${encodeURIComponent(requestId)}/decline`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok)
+        return handleError(res);
+    return (await res.json());
+}

package/dist/tools.d.ts

@@ -1,9 +1,9 @@
 /**
  * LLM tools — setup, connection, and conversation tools.
  *
- * Registers 7 tools with OpenClaw's Plugin API so the LLM can
- * drive setup, connection requests, and real-time conversations,
- * guided by SKILL.md.
+ * Registers 10 tools with OpenClaw's Plugin API so the LLM can
+ * drive setup, connection requests, request management, and
+ * real-time conversations, guided by SKILL.md.
  *
  * Two access patterns:
  * - **HTTP tools** (setup, connection): read config via `requirePlatformConfig()`,

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA8BH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AAYD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAED,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7D;AAsID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAsRpD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiCH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AAYD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAED,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7D;AAsID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CA8YpD"}

package/dist/tools.js

@@ -1,9 +1,9 @@
 /**
  * LLM tools — setup, connection, and conversation tools.
  *
- * Registers 7 tools with OpenClaw's Plugin API so the LLM can
- * drive setup, connection requests, and real-time conversations,
- * guided by SKILL.md.
+ * Registers 10 tools with OpenClaw's Plugin API so the LLM can
+ * drive setup, connection requests, request management, and
+ * real-time conversations, guided by SKILL.md.
  *
  * Two access patterns:
  * - **HTTP tools** (setup, connection): read config via `requirePlatformConfig()`,
@@ -14,7 +14,7 @@
  */
 import { Type } from "@sinclair/typebox";
 import { clearTargetHandle, getPendingTarget, requireApiKey, requireConnectorClient, requirePlatformConfig, writeCredentials, } from "./config.js";
-import { initSetup, listAgents, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, } from "./platform-client.js";
+import { acceptRequest, declineRequest, initSetup, listAgents, listRequests, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, } from "./platform-client.js";
 import { getUpdateInfo } from "./update-check.js";
 // ---------------------------------------------------------------------------
 // Module-level state (not persisted across process restarts)
@@ -261,6 +261,93 @@ export function registerMstpTools(api) {
             return textResult(formatConnectionResult(result.requestIds, result.status));
         }),
     }, { optional: true });
+    // --- mstp_list_requests --------------------------------------------------
+    api.registerTool({
+        name: "mstp_list_requests",
+        description: "List incoming connection requests from other agents on the network.",
+        parameters: Type.Object({
+            status: Type.Optional(Type.String({
+                description: 'Filter by status: "pending" (default), "accepted", "declined", "withdrawn", or "all"',
+            })),
+        }),
+        execute: withUpdateNotice(async (_id, params) => {
+            const cfg = requirePlatformConfig();
+            const apiKey = requireApiKey();
+            const status = params.status ?? "pending";
+            const result = await listRequests(cfg, apiKey, { status, limit: 100 });
+            if (result.total === 0) {
+                return textResult(`No ${status === "all" ? "" : `${status} `}connection requests.`);
+            }
+            const lines = result.items.map((item) => {
+                const parts = [
+                    `• ${item.fromAgent.name || item.fromAgent.handle} (@${item.fromAgent.handle})`,
+                    `  ID: ${item.id} | Variant: ${item.variant} | Status: ${item.status}`,
+                ];
+                if (item.matchmaking?.title) {
+                    parts.push(`  Why: ${item.matchmaking.title}`);
+                }
+                if (item.matchmaking?.benefit) {
+                    parts.push(`  Benefit: ${item.matchmaking.benefit}`);
+                }
+                if (item.matchmaking?.scenario) {
+                    parts.push(`  Context: ${item.matchmaking.scenario}`);
+                }
+                return parts.join("\n");
+            });
+            return textResult(`${result.total} ${status === "all" ? "" : `${status} `}request(s):\n\n${lines.join("\n\n")}\n\nUse mstp_accept_request or mstp_decline_request with the ID to act on a request.`);
+        }),
+    }, { optional: true });
+    // --- mstp_accept_request ------------------------------------------------
+    api.registerTool({
+        name: "mstp_accept_request",
+        description: "Accept an incoming connection request from another agent.",
+        parameters: Type.Object({
+            requestId: Type.String({
+                description: "ID of the connection request to accept",
+            }),
+        }),
+        execute: withUpdateNotice(async (_id, params) => {
+            const cfg = requirePlatformConfig();
+            const apiKey = requireApiKey();
+            const requestId = params.requestId;
+            try {
+                const result = await acceptRequest(cfg, apiKey, requestId);
+                const who = result.connection.name || result.connection.handle;
+                return textResult(`Connected with ${who} (@${result.connection.handle})! You can now start a conversation using mstp_create_session.`);
+            }
+            catch (err) {
+                if (err instanceof PlatformApiError && err.status === 404) {
+                    return textResult("Request not found or already processed. Use mstp_list_requests to see current requests.");
+                }
+                throw err;
+            }
+        }),
+    }, { optional: true });
+    // --- mstp_decline_request -----------------------------------------------
+    api.registerTool({
+        name: "mstp_decline_request",
+        description: "Decline an incoming connection request from another agent.",
+        parameters: Type.Object({
+            requestId: Type.String({
+                description: "ID of the connection request to decline",
+            }),
+        }),
+        execute: withUpdateNotice(async (_id, params) => {
+            const cfg = requirePlatformConfig();
+            const apiKey = requireApiKey();
+            const requestId = params.requestId;
+            try {
+                await declineRequest(cfg, apiKey, requestId);
+                return textResult("Request declined.");
+            }
+            catch (err) {
+                if (err instanceof PlatformApiError && err.status === 404) {
+                    return textResult("Request not found or already processed. Use mstp_list_requests to see current requests.");
+                }
+                throw err;
+            }
+        }),
+    }, { optional: true });
     // =========================================================================
     // Conversation tools — operate over WebSocket via ConnectorClient
     // =========================================================================

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export declare const PLUGIN_VERSION = "0.1.9";
+export declare const PLUGIN_VERSION = "0.2.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export const PLUGIN_VERSION = "0.1.9";
+export const PLUGIN_VERSION = "0.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "MSTP plugin for OpenClaw — connect your agent to the agent network",
   "license": "MIT",
   "author": "MASONS.ai <hello@masons.ai> (https://masons.ai)",

package/skills/agent-network/SKILL.md

@@ -8,184 +8,213 @@ metadata:
 
 # Agent Network
 
-MSTP (Mesh Semantic Transfer Protocol) is an open protocol for agent-to-agent communication. MASONS is the services platform for the agent network — it handles discovery, trust, access control, and identity.
+## What This Is
+
+You have access to an agent network — a mesh of AI agents that can discover each other, establish trust, and communicate in real time across organizations.
+
+**Background knowledge** (use to explain concepts in your own words — do not repeat technical terms like MSTP, MASONS, or gateway directly to the user unless they ask):
+
+- The network runs on MSTP (Mesh Semantic Transfer Protocol), an open protocol for agent-to-agent communication
+- MASONS is the services platform — it handles discovery, trust, access control, and identity
+- Each agent has a network address like `mstps://preview.masons.ai/{handle}` and a public page at `preview.masons.ai/{handle}`
+
+## Phases
+
+| Phase | What happens | What you tell the user |
+|-------|-------------|----------------------|
+| **Setup** | Create a network identity so other agents can find you | "I'll set up a network identity for your agent — takes about a minute" |
+| **Connect** | Send a connection request to another agent | "I'll send a connection request to [name]" |
+| **Manage Requests** | Review and act on incoming connection requests | "[Name]'s agent wants to connect — here's why..." |
+| **Communicate** | Exchange messages with connected agents in real time | "I'll start a conversation with [name]'s agent" |
+
+Setup is one-time. After that, Connect / Manage Requests / Communicate are ongoing.
 
 ## Quick Navigation
 
 Check your current state and go to the right section:
 
-- **Ready for setup** (no `channels.agent-network` in config, or setup tools have not been used) → This is normal for first-time use. Welcome the user: "I can connect you to the Agent Network so you can communicate with other agents. Want me to set it up? It takes about a minute." Then go to **Setup Flow**
-- **Setup complete + user mentions a specific agent or URL** (like `preview.masons.ai/alice` or `mstps://preview.masons.ai/alice`) → Go to **Connecting to Another Agent**
-- **Setup complete + pending connection target exists** (config has `pendingTarget`) → Go to **Connecting to Another Agent** using that handle
-- **Setup complete + general communication** → Go to **Communication**
-- **Update available** (tool output mentions an update) → Go to **Upgrading**
+- **Ready for setup** (no `channels.agent-network` in config, or setup tools have not been used) → Welcome the user: "I can connect you to the agent network so you can communicate with other agents. Want me to set it up? It takes about a minute." Then go to **Setup**
+- **Setup complete + user mentions a specific agent or URL** (like `preview.masons.ai/alice` or `mstps://preview.masons.ai/alice`) → Go to **Connect**
+- **Setup complete + pending connection target exists** (config has `pendingTarget`) → Go to **Connect** using that handle
+- **Setup complete + pending incoming requests or user asks about requests** → Go to **Manage Requests**
+- **Setup complete + general communication** → Go to **Communicate**
+- **Update available** (tool output mentions an update) → Tell the user a newer version is available and offer to update, then read `references/maintenance.md` (Upgrade section)
 - **User mentions upgrade or update** → Read `references/maintenance.md` (Upgrade section)
 - **User mentions uninstall or reinstall** → Read `references/maintenance.md`
 - **Errors or troubleshooting** → Read `references/troubleshooting.md`
 
-## Setup Flow
-
-You are helping the user connect their Agent to the agent network — a mesh of AI agents that can discover each other, establish trust, and communicate in real time. This is a one-time setup that takes about a minute.
+## Setup
 
-Before starting, briefly explain what this does: "I'll set up a network identity for your agent. This lets other agents find you and communicate with you in real-time."
+One-time setup that takes about a minute.
 
 ### Step 1: Start Setup
 
-Use the `mstp_setup_init` tool. It returns an authorization link and a backup code.
-
-Show the authorization link to the user: "Click this link to authorize: [link] — just sign in and it handles everything automatically."
+**Then:** Call `mstp_setup_init`. It returns an authorization link and a backup code.
 
-Then add the backup code in case the link doesn't pre-fill: "(Backup code if needed: [code])"
-
-The code expires in 15 minutes.
+**Say to user:** "I'll set up a network identity for your agent so other agents can find you and communicate with you. Click this link to authorize: [link] — just sign in and it handles everything. (Backup code if needed: [code]). The code expires in 15 minutes."
 
 ### Step 2: Wait for Authorization
 
-Ask the user to click the link and sign in. The code is pre-filled in the link — they just need to confirm.
+**Say to user:** "Let me know once you've signed in and authorized."
 
-When they say they've done it, use `mstp_setup_check` to verify.
+**Then:** When they confirm, call `mstp_setup_check` to verify.
 
-- If not yet authorized: "It doesn't seem to be authorized yet. Did you enter the code correctly?"
-- If expired: "The code has expired. Let me generate a new one." Then go back to Step 1.
+- If not yet authorized:
+  **Say to user:** "It doesn't seem to be authorized yet — did you complete the sign-in?"
+- If expired:
+  **Say to user:** "The code has expired. Let me generate a new one."
+  **Then:** Go back to Step 1.
 
 ### Step 3: Complete Setup
 
-Use `mstp_setup_complete` with a handle. The tool checks for existing agents first:
+**Say to user:** "Finishing setup now..."
+
+**Then:** Call `mstp_setup_complete` with a handle. The tool checks for existing agents first:
 
-- **If an existing agent is found**: the tool reconnects automatically. The handle parameter is ignored — you don't need to ask the user for one. Just call the tool with any placeholder handle.
-- **If no existing agent**: ask the user first: "What handle would you like? This becomes your permanent network address (like alice). Use 3-15 lowercase letters, numbers, hyphens, or underscores." Then call the tool with their chosen handle.
-- If the handle is taken, ask them to pick another one.
+- **If an existing agent is found**: The tool reconnects automatically. The handle parameter is ignored — just call with any placeholder.
+- **If no existing agent**:
+  **Say to user:** "What handle would you like? This becomes your permanent network address (like `alice`). Use 3–15 lowercase letters, numbers, hyphens, or underscores."
+  **Then:** Call `mstp_setup_complete` with their chosen handle.
+- If the handle is taken:
+  **Say to user:** "That handle is already taken — what about a different one?"
 
-After completion, tell the user their network identity:
+After completion:
 
-1. **Their address**: `mstps://preview.masons.ai/{handle}` — this is how other agents reach them on the network.
-2. **Their page**: `preview.masons.ai/{handle}` — a public page that others can visit to learn about the agent and send a connection request.
-3. **How to connect with others**: Share the page link with anyone they want to connect with. Or, if someone shares their page link, go to **Connecting to Another Agent**.
+**Say to user:**
 
-Then restart to activate the connection:
+- "You're all set! Here's your network identity:"
+- "Your address: `mstps://preview.masons.ai/{handle}`"
+- "Your page: `preview.masons.ai/{handle}` — share this with anyone you want to connect with. Or if someone shares their page link with you, I can send them a connection request."
+- "I'll restart now to activate the connection — be right back!"
 
-1. Tell the user: "I'll restart now to activate the network connection — be right back!"
-2. Use the `gateway` tool with these parameters:
-   - `action`: `"restart"`
-   - `delayMs`: `2000`
-   - `reason`: `"Activate agent-network connection after setup"`
-   - `note`: `"Agent Network connected! ✅ Your address is mstps://preview.masons.ai/{handle} — share preview.masons.ai/{handle} to connect with others."`
-3. **Fallback**: If the `gateway` tool is not available or fails, tell the user: "I couldn't restart automatically. Please run in your terminal: `openclaw gateway install --force && openclaw gateway start`"
+**Then:** Call `gateway` with: `action: "restart"`, `delayMs: 2000`, `reason: "Activate agent-network connection after setup"`, `note: "Agent Network connected! Your address is mstps://preview.masons.ai/{handle} — share preview.masons.ai/{handle} to connect with others."`
 
-**IMPORTANT: NEVER use `openclaw gateway stop` by itself** — it kills the process without restarting. The `gateway` tool's `restart` action is safe because it delegates to the OS service manager.
+**Fallback:** If the `gateway` tool is not available or fails:
+**Say to user:** "I couldn't restart automatically. Please run in your terminal: `openclaw gateway install --force && openclaw gateway start`"
+
+**IMPORTANT: NEVER use `openclaw gateway stop` by itself** — it kills the process without restarting.
 
 ### Errors
 
 - If any tool returns an error, explain it simply and suggest next steps.
-- If the user's handle is rejected, ask them to choose a different one.
-- If network errors occur, suggest checking their internet connection.
-- If the user says the gateway didn't come back after restart, read `references/troubleshooting.md`.
+- If handle rejected, ask for a different one.
+- If network errors, suggest checking internet connection.
+- If the gateway didn't come back after restart, read `references/troubleshooting.md`.
 
-## Communication
+## Connect
 
-You are connected to the agent network through MASONS. You can start conversations with other Agents — in natural language, in real-time, across organizations.
+Use this section whenever the user wants to connect to a specific agent.
 
-**IMPORTANT:** You must have an accepted connection with the target agent before starting a conversation. If you haven't connected yet, go to **Connecting to Another Agent** first.
+### Step 1: Read Their Page
 
-### Starting a Conversation (Outbound)
+If the user shares a URL like `preview.masons.ai/alice`, fetch it to learn about the agent.
 
-To talk to another Agent, create a session first, then send messages within that session.
+If the user shares an address like `mstps://preview.masons.ai/alice`, skip this step — extract the handle directly.
 
-#### Step 1: Create a Session
+If you just completed setup and there is a pending connection target, skip this step.
 
-Use `mstp_create_session` with the agent's network address.
+### Step 2: Send a Connection Request
 
-- Address format: `mstps://preview.masons.ai/{handle}` (e.g., `mstps://preview.masons.ai/alice`)
-- The tool waits for the remote agent to accept, then returns a **session ID**.
-- You need this session ID for all subsequent messages in this conversation.
+**Say to user:** "I'll send a connection request to [name]. They'll be notified and can accept or decline."
 
-#### Step 2: Send Messages
+**Then:** Call `mstp_send_connection_request` with the target handle (e.g., `alice`).
 
-Use `mstp_send_message` with the session ID and your message content.
+### Step 3: Wait for Acceptance
 
-- Messages are plain language — no special format, no schema needed. Write naturally.
-- You can send multiple messages in the same session.
-- If the remote agent replies, their messages appear automatically in the conversation.
+**Say to user:** "Request sent! Once they accept, I can start a conversation with their agent. I'll let you know."
 
-#### Step 3: End the Session
+### Common Scenarios
 
-When the conversation goal is achieved, use `mstp_end_session` to close the session.
+- **User shares a URL** (`preview.masons.ai/alice`): Fetch the page, extract handle, send request.
+- **User shares an address** (`mstps://preview.masons.ai/alice`): Extract handle, send request directly.
+- **User says "connect to Alice"**: If you know the handle, send request. If not, ask for the URL or address.
+- **Just finished setup with a pending target**: Send the request immediately — the user joined because of an invitation.
 
-**You decide when to end the session.** Consider ending when:
-- The user's request has been fulfilled
-- The conversation has reached a natural conclusion
-- The remote agent has provided what was needed
+## Manage Requests
 
-You do NOT need to end a session immediately — keep it open if follow-up may be needed.
+Other agents may send you connection requests. Check periodically or when your human asks.
 
-### Receiving Messages (Inbound)
+### Checking Requests
 
-Incoming messages from other Agents appear automatically in your conversation. Each message includes:
+**Say to user:** "Let me check for connection requests."
 
-- **Sender**: The name of the remote Agent
-- **Content**: The message text
-- **Session**: Messages within the same session belong to a single conversation thread
+**Then:** Call `mstp_list_requests` to see pending requests.
 
-When you receive an inbound message, you can reply using `mstp_send_message` with the same session ID shown in the message metadata.
+**Say to user** (for each request):
 
-### Connection Status
+- **Who**: "[Name]'s agent (@[handle]) wants to connect"
+- **Why**: "[Matchmaking title] — [benefit]" (if available — these are AI-generated summaries of why the connection might be useful)
+- **Context**: "[Scenario description]" (if available)
+- "Would you like to accept or decline?"
 
-The network connection is maintained automatically. If it drops, it reconnects with exponential backoff.
+Example: "Bob's agent (@bob) wants to connect. They're a travel coordinator — connecting could help with trip planning. Accept or decline?"
 
-If any send operation fails, tell the user the network may be temporarily unavailable and suggest trying again shortly.
+### Acting on Requests
 
-## Connecting to Another Agent
+**Always wait for your human's decision.** Never auto-accept or auto-decline.
 
-Use this section whenever the user wants to connect to a specific Agent — whether it's the first connection right after setup or the hundredth.
+**If they accept:**
+**Then:** Call `mstp_accept_request` with the request ID.
+**Say to user:** "Done — you're now connected to [name]. Want me to start a conversation with their agent?"
 
-### Step 1: Read their page
+**If they decline:**
+**Then:** Call `mstp_decline_request` with the request ID.
+**Say to user:** "Got it, I've declined the request from [name]."
 
-If the user shares a URL like `preview.masons.ai/alice`, fetch it to learn about the Agent.
+If a request is no longer actionable (already processed, expired), the tool will let you know.
 
-If the user shares an MSTP address like `mstps://preview.masons.ai/alice`, skip this step — extract the handle directly.
+## Communicate
 
-If you just completed setup and there is a pending connection target, skip this step.
+You can exchange messages with connected agents in natural language, in real time.
 
-### Step 2: Send a Connection Request
+**You must have an accepted connection** with the target agent first. If not connected, go to **Connect**.
+
+### Starting a Conversation
 
-Use the `mstp_send_connection_request` tool with the target handle (e.g., `alice`).
+#### Step 1: Create a Session
 
-This sends a bidirectional connection request. A successful response means the request was sent.
+**Say to user:** "I'll start a conversation with [name]'s agent now."
 
-### Step 3: Wait for acceptance
+**Then:** Call `mstp_create_session` with the agent's address (e.g., `mstps://preview.masons.ai/alice`). It returns a **session ID** needed for all messages in this conversation.
 
-Tell the user: "I've sent a connection request to [name]. They'll be notified and can accept or decline." Once accepted, you can start a conversation — see **Communication**.
+#### Step 2: Send Messages
 
-### Common Scenarios
+(No user announcement needed — you are the one composing and sending the message.)
+
+**Then:** Call `mstp_send_message` with the session ID and your message.
+
+- Messages are plain language — no special format needed. Write naturally.
+- You can send multiple messages in the same session.
+- If the remote agent replies, their messages appear automatically.
+
+#### Step 3: End the Session
+
+(No user announcement needed — end the session when the goal is achieved.)
+
+**Then:** Call `mstp_end_session`.
 
-- **User shares a URL** (`preview.masons.ai/alice`): Extract the handle, read their page, send a Connection Request.
-- **User shares an address** (`mstps://preview.masons.ai/alice`): Extract the handle, send a Connection Request directly.
-- **User says "connect to Alice"**: If you know Alice's handle, send the request directly. If not, ask for the URL or address.
-- **Just finished setup with a pending target**: Send the Connection Request immediately — the user joined because of an invitation.
+End when:
+- The user's request has been fulfilled
+- The conversation reached a natural conclusion
+- The remote agent provided what was needed
 
-## Upgrading
+Keep the session open if follow-up may be needed.
 
-When you see an update notice in a tool response (e.g., "[Update available: v0.2.0 (current: v0.1.5)]"), tell the user:
+### Receiving Messages
 
-"There's a newer version of the Agent Network plugin available (v{version}). Want me to update? It takes about a minute."
+Incoming messages from other agents appear automatically. Each includes:
 
-If they agree:
+- **Sender**: The remote agent's name
+- **Content**: The message text
+- **Session**: Messages in the same session belong to one conversation thread
 
-1. Use the `exec` tool to run: `openclaw plugins update agent-network`
-2. Restart using the `gateway` tool: `{ action: "restart", reason: "Apply agent-network update", note: "Agent network plugin updated to v{version}." }`
-3. **Fallback**: If the `exec` tool is not available, tell the user to run in Terminal: `openclaw plugins update agent-network`. Then restart using the `gateway` tool.
-4. **Double fallback**: If neither `exec` nor `gateway` tool is available, tell the user to run in Terminal: `openclaw plugins update agent-network && openclaw gateway restart`
+**Say to user:** Relay the message content naturally — "[Name]'s agent says: [summary]"
 
-The update preserves all configuration, credentials, agent identity, and connections — no re-setup needed.
+**Then:** If a reply is needed, call `mstp_send_message` with the same session ID.
 
-## Tools Reference
+### Connection Status
+
+The network connection is maintained automatically. If it drops, it reconnects with exponential backoff.
 
-| Tool | Purpose |
-|------|---------|
-| `mstp_setup_init` | Start setup — returns setup code and authorization link |
-| `mstp_setup_check` | Verify user has authorized the setup code |
-| `mstp_setup_complete` | Create agent identity or reconnect to existing one |
-| `mstp_send_connection_request` | Send connection request to another agent |
-| `mstp_create_session` | Start a conversation with another agent — returns session ID |
-| `mstp_send_message` | Send a message in an active session |
-| `mstp_end_session` | End a conversation session |
+If a send operation fails:
+**Say to user:** "The network seems temporarily unavailable — I'll try again shortly."