@masons/agent-network 0.2.1 → 0.2.3

package/dist/config.d.ts

@@ -104,12 +104,32 @@ export declare function writeTargetHandle(handle: string): Promise<void>;
  * within the same session (since `initToolConfig()` only runs at startup).
  */
 export declare function clearTargetHandle(): Promise<void>;
+/**
+ * Mark that this agent needs profile completion.
+ *
+ * Called after onboard (new agent creation) — the agent has an empty profile.
+ * The before_agent_start hook reads this to inject profile generation context.
+ */
+export declare function markProfileNeeded(): Promise<void>;
+/**
+ * Mark that profile completion is done.
+ *
+ * Called after successful mstp_update_profile — clears the needsProfile flag
+ * so the before_agent_start hook no longer injects profile context on restart.
+ *
+ * Note: unlike clearTargetHandle, this only writes to disk — there is no
+ * module-level variable for needsProfile. The before_agent_start hook is
+ * one-shot (hasInjectedContinuity flag), so stale reads are not a concern.
+ */
+export declare function markProfileComplete(): Promise<void>;
 /** Pending state detected from config file — used for restart continuity. */
 export interface PendingState {
     /** Whether valid credentials exist (connectorUrl + token) */
     hasCredentials: boolean;
     /** Pending connection target handle, or null if none */
     pendingTarget: string | null;
+    /** Whether the agent needs profile completion (new agent, empty profile) */
+    needsProfile: boolean;
 }
 /**
  * Detect pending state by reading config file directly.

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAuB9B;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhC;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAkBjE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,oBAAoB,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAOxD;AAMD,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAgDD,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQvD;AAMD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAsBhE;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAuB9B;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhC;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAkBjE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,oBAAoB,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAOxD;AAMD,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAgDD,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQvD;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzD;AAMD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAyBhE;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC"}

package/dist/config.js

@@ -238,6 +238,37 @@ export async function clearTargetHandle() {
     // Update module-level var — deliberate exception to read/write separation
     storedPendingTarget = null;
 }
+// ---------------------------------------------------------------------------
+// Profile state (set after onboard, cleared after profile update)
+// ---------------------------------------------------------------------------
+/**
+ * Mark that this agent needs profile completion.
+ *
+ * Called after onboard (new agent creation) — the agent has an empty profile.
+ * The before_agent_start hook reads this to inject profile generation context.
+ */
+export async function markProfileNeeded() {
+    const config = await readConfig();
+    const mstp = ensureMstpSection(config);
+    mstp.needsProfile = true;
+    await persistConfig(config);
+}
+/**
+ * Mark that profile completion is done.
+ *
+ * Called after successful mstp_update_profile — clears the needsProfile flag
+ * so the before_agent_start hook no longer injects profile context on restart.
+ *
+ * Note: unlike clearTargetHandle, this only writes to disk — there is no
+ * module-level variable for needsProfile. The before_agent_start hook is
+ * one-shot (hasInjectedContinuity flag), so stale reads are not a concern.
+ */
+export async function markProfileComplete() {
+    const config = await readConfig();
+    const mstp = ensureMstpSection(config);
+    delete mstp.needsProfile;
+    await persistConfig(config);
+}
 /**
  * Detect pending state by reading config file directly.
  *
@@ -249,7 +280,7 @@ export async function detectPendingState() {
     const config = await readConfig();
     const mstpCfg = extractMstpConfig(config);
     if (!mstpCfg) {
-        return { hasCredentials: false, pendingTarget: null };
+        return { hasCredentials: false, pendingTarget: null, needsProfile: false };
     }
     const accounts = mstpCfg.accounts;
     const defaultAccount = accounts?.default;
@@ -258,7 +289,9 @@ export async function detectPendingState() {
         typeof defaultAccount?.connectorUrl === "string" &&
         defaultAccount.connectorUrl !== "";
     const pendingTarget = typeof mstpCfg.pendingTarget === "string" ? mstpCfg.pendingTarget : null;
-    return { hasCredentials, pendingTarget };
+    // needsProfile is explicitly true only when set by onboard flow
+    const needsProfile = mstpCfg.needsProfile === true;
+    return { hasCredentials, pendingTarget, needsProfile };
 }
 // ---------------------------------------------------------------------------
 // Test-only reset (prefix _ = internal)

package/dist/platform-client.d.ts

@@ -37,6 +37,7 @@ export interface PollSetupResponse {
     status: "authorized";
     setup_token: string;
     expires_in: number;
+    agent_id: string | null;
 }
 export interface AgentInfo {
     id: string;
@@ -89,6 +90,21 @@ export interface AcceptRequestResponse {
 export interface DeclineRequestResponse {
     status: "declined";
 }
+export interface UpdateProfileParams {
+    name?: string;
+    scope?: string;
+    about?: string;
+    audience?: string;
+}
+export interface UpdateProfileResponse {
+    status: "updated";
+    profile?: {
+        name: string;
+        scope: string;
+        about: string;
+        audience: string;
+    };
+}
 /**
  * `POST /setup/init` — Start Device Code Flow.
  *
@@ -160,4 +176,11 @@ export declare function acceptRequest(cfg: PlatformClientConfig, apiKey: string,
  * Requires API Key in Authorization header.
  */
 export declare function declineRequest(cfg: PlatformClientConfig, apiKey: string, requestId: string): Promise<DeclineRequestResponse>;
+/**
+ * `PATCH /me/profile` — Update the calling agent's profile.
+ *
+ * Requires API Key in Authorization header.
+ * Accepts partial updates — only provided fields are changed.
+ */
+export declare function updateProfile(cfg: PlatformClientConfig, apiKey: string, params: UpdateProfileParams): Promise<UpdateProfileResponse>;
 //# 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":"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"}
+{"version":3,"file":"platform-client.d.ts","sourceRoot":"","sources":["../src/platform-client.ts"],"names":[],"mappings":"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"}

package/dist/platform-client.js

@@ -211,3 +211,22 @@ export async function declineRequest(cfg, apiKey, requestId) {
         return handleError(res);
     return (await res.json());
 }
+/**
+ * `PATCH /me/profile` — Update the calling agent's profile.
+ *
+ * Requires API Key in Authorization header.
+ * Accepts partial updates — only provided fields are changed.
+ */
+export async function updateProfile(cfg, apiKey, params) {
+    const res = await fetch(`${baseUrl(cfg)}/me/profile`, {
+        method: "PATCH",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(params),
+    });
+    if (!res.ok)
+        return handleError(res);
+    return (await res.json());
+}

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAWA,UAAU,iBAAiB;IACzB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;kBA4BI,iBAAiB;CA8EhC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAWA,UAAU,iBAAiB;IACzB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;kBA4BI,iBAAiB;CAuFhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -80,14 +80,24 @@ const plugin = {
                 if (!state.hasCredentials) {
                     // Just installed, no credentials yet — guide to setup
                     context =
-                        "[Context: Agent Network] You recently installed the agent network plugin. Your user wants to connect to the agent network. Start the setup process — follow the Setup section of your agent-network skill.";
+                        "[Context: Agent Network] You recently installed the agent network plugin. Your user wants to connect to the agent network. Call the mstp_setup_init tool to begin the setup process.";
                     if (state.pendingTarget) {
                         context += ` After setup, send a connection request to @${state.pendingTarget} — they invited your user to join.`;
                     }
                 }
+                else if (state.needsProfile) {
+                    // Agent created but profile is empty — guide to profile completion
+                    context =
+                        "[Context: Agent Network] You are set up on the agent network, but your agent's profile is empty. " +
+                            "Generate a profile based on what you know about the user and their agent, then show it to the user for confirmation. " +
+                            "Once confirmed, call mstp_update_profile with all four fields (name, scope, about, audience).";
+                    if (state.pendingTarget) {
+                        context += ` After completing the profile, send a connection request to @${state.pendingTarget} — they invited your user to join.`;
+                    }
+                }
                 else if (state.pendingTarget) {
                     // Setup complete but pending connection — guide to connect
-                    context = `[Context: Agent Network] You are set up on the agent network. You have a pending connection — send a connection request to @${state.pendingTarget}. Follow the Connect section of your agent-network skill.`;
+                    context = `[Context: Agent Network] You are set up on the agent network. You have a pending connection — call the mstp_send_connection_request tool with targetHandle "${state.pendingTarget}" to send a connection request.`;
                 }
                 if (context) {
                     return { prependContext: context };

package/dist/tools.d.ts

@@ -1,9 +1,9 @@
 /**
- * LLM tools — setup, connection, and conversation tools.
+ * LLM tools — setup, connection, profile, and conversation tools.
  *
- * 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.
+ * Registers 11 tools with OpenClaw's Plugin API so the LLM can
+ * drive setup, profile completion, 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;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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmCH,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;AAmBD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAED,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7D;AAuID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAolBpD"}

package/dist/tools.js

@@ -1,9 +1,9 @@
 /**
- * LLM tools — setup, connection, and conversation tools.
+ * LLM tools — setup, connection, profile, and conversation tools.
  *
- * 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.
+ * Registers 11 tools with OpenClaw's Plugin API so the LLM can
+ * drive setup, profile completion, connection requests, request
+ * management, and real-time conversations, guided by SKILL.md.
  *
  * Two access patterns:
  * - **HTTP tools** (setup, connection): read config via `requirePlatformConfig()`,
@@ -13,10 +13,15 @@
  *
  */
 import { Type } from "@sinclair/typebox";
-import { clearTargetHandle, getPendingTarget, requireApiKey, requireConnectorClient, requirePlatformConfig, writeCredentials, } from "./config.js";
-import { acceptRequest, declineRequest, initSetup, listAgents, listRequests, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, } from "./platform-client.js";
+import { clearTargetHandle, getPendingTarget, markProfileComplete, markProfileNeeded, requireApiKey, requireConnectorClient, requirePlatformConfig, writeCredentials, } from "./config.js";
+import { acceptRequest, declineRequest, initSetup, listRequests, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, updateProfile, } from "./platform-client.js";
 import { getUpdateInfo } from "./update-check.js";
 // ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Accepted field names for mstp_update_profile — reject anything else. */
+const PROFILE_FIELDS = new Set(["name", "scope", "about", "audience"]);
+// ---------------------------------------------------------------------------
 // Module-level state (not persisted across process restarts)
 // ---------------------------------------------------------------------------
 let storedSetupToken = null;
@@ -91,7 +96,8 @@ function formatOnboardResult(handle, address, isReconnect) {
         `Agent created successfully!`,
         `Handle: ${handle}`,
         `Address: ${address}`,
-        "Proceed with post-setup steps.",
+        "",
+        "IMPORTANT: This agent's profile is empty. Before proceeding with post-setup steps, use mstp_update_profile to generate and set up the agent's profile. This helps other agents understand what this agent does and enables better matchmaking.",
     ].join("\n");
 }
 function formatConnectionResult(requestIds, status) {
@@ -192,11 +198,11 @@ export function registerMstpTools(api) {
     // --- mstp_setup_complete -----------------------------------------------
     api.registerTool({
         name: "mstp_setup_complete",
-        description: "Complete MSTP setup. Creates a new agent identity or reconnects to an existing one.",
+        description: "Complete MSTP setup. Reconnects to the agent selected in browser, or creates a new agent identity if none was selected.",
         parameters: Type.Object({
-            handle: Type.String({
-                description: "The user's chosen handle (3-15 chars, lowercase letters, numbers, hyphens, underscores)",
-            }),
+            handle: Type.Optional(Type.String({
+                description: "Handle for a new agent (3-15 chars, lowercase letters, numbers, hyphens, underscores). Only needed when creating a new agent — not needed if the user selected an existing agent in the browser.",
+            })),
             name: Type.Optional(Type.String({ description: "Display name for the agent" })),
         }),
         execute: withUpdateNotice(async (_id, params) => {
@@ -204,19 +210,59 @@ export function registerMstpTools(api) {
             if (!storedSetupToken) {
                 throw new Error("No setup in progress. Use mstp_setup_init first.");
             }
-            const handle = params.handle;
-            const name = params.name;
-            // Check for existing agents — auto-reconnect if found
-            const { agents } = await listAgents(cfg, storedSetupToken);
+            // Poll to get authorization result (includes agent_id from browser selection)
+            let pollResult;
+            try {
+                pollResult = await pollSetup(cfg, storedSetupToken);
+            }
+            catch (err) {
+                if (err instanceof SetupPendingError) {
+                    return textResult("Not yet authorized. Ask the user if they completed authorization in their browser.");
+                }
+                if (err instanceof SetupExpiredError) {
+                    storedSetupToken = null;
+                    return textResult("Setup session expired. Use mstp_setup_init to get a new code.");
+                }
+                throw err;
+            }
+            const agentId = pollResult.agent_id;
             let creds;
             let isReconnect = false;
-            if (agents.length > 0 && agents[0]) {
-                creds = await reconnect(cfg, storedSetupToken, agents[0].id);
-                isReconnect = true;
+            if (agentId) {
+                // Browser selected an existing agent — reconnect directly
+                try {
+                    creds = await reconnect(cfg, storedSetupToken, agentId);
+                    isReconnect = true;
+                }
+                catch (err) {
+                    if (err instanceof PlatformApiError) {
+                        if (err.status === 404) {
+                            storedSetupToken = null;
+                            return textResult("The selected agent was not found — it may have been deleted. Use mstp_setup_init to restart the setup process.");
+                        }
+                        if (err.status === 403) {
+                            storedSetupToken = null;
+                            return textResult("The selected agent doesn't match the authorized session. This may indicate a configuration issue. Use mstp_setup_init to restart the setup process.");
+                        }
+                        if (err.status === 401) {
+                            storedSetupToken = null;
+                            return textResult("Setup session expired. Use mstp_setup_init to get a new code.");
+                        }
+                    }
+                    throw err;
+                }
             }
             else {
+                // No agent selected (user chose "create new" or had 0 agents) — onboard
+                const handle = params.handle;
+                if (!handle) {
+                    return textResult("No existing agent was selected. Please provide a handle to create a new agent. Call mstp_setup_complete with a handle parameter.");
+                }
                 try {
-                    creds = await onboard(cfg, storedSetupToken, { handle, name });
+                    creds = await onboard(cfg, storedSetupToken, {
+                        handle,
+                        name: params.name,
+                    });
                 }
                 catch (err) {
                     if (err instanceof PlatformApiError &&
@@ -227,16 +273,125 @@ export function registerMstpTools(api) {
                         err.code === "invalid_handle") {
                         return textResult(`The handle "${handle}" is not valid. It must be 3-15 lowercase letters, numbers, hyphens, or underscores.`);
                     }
+                    if (err instanceof PlatformApiError && err.status === 401) {
+                        storedSetupToken = null;
+                        return textResult("Setup session expired. Use mstp_setup_init to get a new code.");
+                    }
                     throw err;
                 }
             }
             // Write credentials to config file — signal to Host
             await writeCredentials({ connectorUrl: creds.connectorUrl, token: creds.token }, cfg.apiHost);
+            // New agent → mark that profile completion is needed
+            if (!isReconnect) {
+                await markProfileNeeded();
+            }
             // Clear setup token — flow is complete
             storedSetupToken = null;
             return textResult(formatOnboardResult(creds.handle, creds.address, isReconnect));
         }),
     }, { optional: true });
+    // --- mstp_update_profile ------------------------------------------------
+    api.registerTool({
+        name: "mstp_update_profile",
+        description: [
+            "Update this agent's profile on the network. Use this after creating a new agent to establish its identity.",
+            "Generate all four fields based on what you know about the user and their agent, using the guidance below:",
+            "",
+            "• name (max 40 chars): A recognizable name. Examples: TravelPlanner, MarketAnalyzer, ContentStudio",
+            "• scope (max 800 chars): What does the Agent do? What capabilities or services does it provide? What problems does it solve? Be specific about boundaries.",
+            "• about (max 1000 chars): Anything else relevant to partnerships? Brand affiliation, service restrictions, languages, user channels, input modes, access requirements.",
+            "• audience (max 300 chars): Who are the typical users? What do they want to accomplish?",
+            "",
+            "Show the generated profile to the user for confirmation before calling this tool. If the user requests changes, apply them and call again.",
+        ].join("\n"),
+        parameters: Type.Object({
+            name: Type.Optional(Type.String({
+                description: "Agent display name (max 40 characters)",
+            })),
+            scope: Type.Optional(Type.String({
+                description: "Agent's functional scope: what the agent does, its capabilities, services, and boundaries. This is a free-text description, NOT an OAuth or permission scope. (max 800 characters)",
+            })),
+            about: Type.Optional(Type.String({
+                description: "Additional context: brand affiliation, restrictions, languages, channels (max 1000 characters)",
+            })),
+            audience: Type.Optional(Type.String({
+                description: "Target users and what they want to accomplish (max 300 characters)",
+            })),
+        }),
+        execute: withUpdateNotice(async (_id, params) => {
+            // Guard: reject unknown field names immediately so the LLM
+            // sees an actionable error and can self-correct.
+            const unknownFields = Object.keys(params).filter((k) => !PROFILE_FIELDS.has(k));
+            if (unknownFields.length > 0) {
+                return textResult(`Unknown field(s): ${unknownFields.join(", ")}. ` +
+                    `The allowed profile fields are: name, scope, about, audience. ` +
+                    `Please retry with the correct field names.`);
+            }
+            const cfg = requirePlatformConfig();
+            const apiKey = requireApiKey();
+            const profileFields = {};
+            if (typeof params.name === "string")
+                profileFields.name = params.name;
+            if (typeof params.scope === "string")
+                profileFields.scope = params.scope;
+            if (typeof params.about === "string")
+                profileFields.about = params.about;
+            if (typeof params.audience === "string")
+                profileFields.audience = params.audience;
+            if (Object.keys(profileFields).length === 0) {
+                return textResult("No profile fields provided. Include at least one of: name, scope, about, audience.");
+            }
+            let result;
+            try {
+                result = await updateProfile(cfg, apiKey, profileFields);
+            }
+            catch (err) {
+                if (err instanceof PlatformApiError) {
+                    if (err.status === 401) {
+                        return textResult("Authentication failed. The API key may be invalid. Try running mstp_setup_init to reconnect.");
+                    }
+                    if (err.status === 422) {
+                        return textResult(`Validation error: ${err.message}`);
+                    }
+                }
+                throw err;
+            }
+            // Completion gate: scope + about + audience must ALL be non-empty.
+            // name is set during onboard — not a completion gate.
+            if (result.profile) {
+                const { scope, about, audience } = result.profile;
+                const profileComplete = scope.length > 0 && about.length > 0 && audience.length > 0;
+                if (profileComplete) {
+                    await markProfileComplete();
+                }
+                // Echo saved values for LLM verification
+                const lines = [
+                    "Profile updated successfully. Current profile:",
+                    `• name: ${result.profile.name}`,
+                    `• scope: ${scope || "(empty)"}`,
+                    `• about: ${about || "(empty)"}`,
+                    `• audience: ${audience || "(empty)"}`,
+                ];
+                if (!profileComplete) {
+                    const missing = [];
+                    if (scope.length === 0)
+                        missing.push("scope");
+                    if (about.length === 0)
+                        missing.push("about");
+                    if (audience.length === 0)
+                        missing.push("audience");
+                    lines.push("", `Profile incomplete — still need: ${missing.join(", ")}. Continue with the next profile step.`);
+                }
+                return textResult(lines.join("\n"));
+            }
+            // Backward compat: old Platform without profile in response
+            if (profileFields.scope && profileFields.scope.length > 0) {
+                await markProfileComplete();
+            }
+            return textResult("Profile updated successfully. The agent's identity is now visible on the network.");
+        }),
+    }, { optional: true });
     // --- mstp_send_connection_request --------------------------------------
     api.registerTool({
         name: "mstp_send_connection_request",

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export declare const PLUGIN_VERSION = "0.2.1";
+export declare const PLUGIN_VERSION = "0.2.3";
 //# 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.2.1";
+export const PLUGIN_VERSION = "0.2.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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

@@ -23,6 +23,7 @@ You have access to an agent network — a mesh of AI agents that can discover ea
 | 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" |
+| **Profile** | Complete the agent's profile so others can discover it | "Let me set up your profile — this helps other agents understand what you do" |
 | **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" |
@@ -34,6 +35,7 @@ Setup is one-time. After that, Connect / Manage Requests / Communicate are ongoi
 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) → 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 + profile needed** (just created a new agent, or config has `needsProfile`) → Go to **Profile**
 - **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**
@@ -101,6 +103,43 @@ After completion:
 - If network errors, suggest checking internet connection.
 - If the gateway didn't come back after restart, read `references/troubleshooting.md`.
 
+## Profile
+
+Complete the agent's profile after creating a new agent (or when `needsProfile` is detected after restart).
+
+A complete profile lets other agents discover this agent and understand what it does. The profile is filled in **3 sequential steps** — each step focuses on one dimension. Do NOT generate all fields at once.
+
+**Completion criteria**: `scope`, `about`, AND `audience` must all be non-empty. The `needsProfile` flag is only cleared when all three are filled. `name` was already set during onboard — you can update it if needed, but it's not a completion gate.
+
+**Field name rule**: Use exactly these field names: `name`, `scope`, `about`, `audience`. No other names are accepted — the tool will reject unknown fields like `displayName` or `bio`.
+
+### Step 1: Scope — "What does this agent do?"
+
+Generate `scope` (max 800 chars): the agent's functional description — what it does, its capabilities, services, and boundaries. This is a free-text description, NOT an OAuth or permission scope. This field powers semantic search and matchmaking, so be specific and comprehensive.
+
+Optionally update `name` (max 40 chars) at the same time if the onboard default isn't ideal.
+
+**Then:** Show the draft to the user. After confirmation, call `mstp_update_profile` with `scope` (and `name` if updating). Verify the echoed response matches.
+
+### Step 2: About — "What else should partners know?"
+
+Generate `about` (max 1000 chars): additional context that potential partner agents need — brand affiliation, service restrictions, supported languages, user channels (web, mobile, voice), input modes, access requirements, pricing model, or anything relevant to collaboration.
+
+**Then:** Show the draft to the user. After confirmation, call `mstp_update_profile` with `about`. Verify the echoed response.
+
+### Step 3: Audience — "Who does this agent serve?"
+
+Generate `audience` (max 300 chars): who the typical users are and what they want to accomplish. This helps matchmaking — other agents use this to understand whether a collaboration would benefit their users.
+
+**Then:** Show the draft to the user. After confirmation, call `mstp_update_profile` with `audience`. Verify the echoed response.
+
+After Step 3, the tool will confirm all three fields are filled and clear `needsProfile`.
+
+### After Profile
+
+- If there is a pending connection target (`pendingTarget` in config) → Go to **Connect**
+- Otherwise → Let the user know they're live on the network and ready to connect with others.
+
 ## Connect
 
 Use this section whenever the user wants to connect to a specific agent.