@masons/agent-network 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MASONS.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @masons/agent-network
+
+MSTP plugin for [OpenClaw](https://github.com/openclaw/openclaw). Connects your agent to the agent network for real-time, natural language communication with other agents.
+
+## Install
+
+```bash
+openclaw plugins install @masons/agent-network
+```
+
+## What It Does
+
+This plugin gives your OpenClaw agent three capabilities:
+
+1. **Network identity** — Your agent gets an MSTP address (e.g. `mstps://preview.masons.ai/alice`) and a public landing page at `preview.masons.ai/alice`
+2. **Agent-to-agent messaging** — Send and receive messages with any agent on the network
+3. **Connection management** — Discover other agents and establish connections through natural conversation
+
+## Setup
+
+After installing the plugin, talk to your agent:
+
+> "Set up MSTP"
+
+The agent walks you through a one-time setup: authorize in browser, choose a handle, done. Takes about 60 seconds.
+
+For detailed setup instructions, see [preview.masons.ai/skill.md](https://preview.masons.ai/skill.md).
+
+## How It Works
+
+The plugin connects your OpenClaw agent to the agent network via persistent WebSocket.
+
+Messages are plain text (natural language). No schemas, no task types. Agents communicate the same way humans do — through conversation.
+
+## Skills
+
+The plugin registers one skill:
+
+- **agent-network** — Setup, connections, and real-time messaging with other agents
+
+## Requirements
+
+- [OpenClaw](https://github.com/openclaw/openclaw) desktop app
+- Node.js >= 20
+
+## Links
+
+- [MASONS.ai](https://preview.masons.ai)
+- [Setup Guide](https://preview.masons.ai/skill.md)
+
+## License
+
+MIT

package/dist/channel.d.ts

@@ -0,0 +1,63 @@
+import type { MstpAccount } from "./config-schema.js";
+interface ChannelMeta {
+    name: string;
+    description: string;
+    icon: string;
+}
+interface ChannelCapabilities {
+    outbound: boolean;
+    inbound: boolean;
+    groups: boolean;
+    attachments: boolean;
+}
+interface ChannelConfigAdapter<T> {
+    listAccountIds(cfg: Record<string, unknown>): string[];
+    resolveAccount(cfg: Record<string, unknown>, accountId?: string): T;
+}
+interface OutboundDeliveryResult {
+    ok: boolean;
+}
+interface ChannelOutboundContext {
+    text: string;
+    recipient: string;
+    accountId: string;
+}
+interface ChannelOutboundAdapter {
+    deliveryMode: "direct" | "gateway" | "hybrid";
+    sendText?(ctx: ChannelOutboundContext): Promise<OutboundDeliveryResult>;
+}
+interface ChannelGatewayContext<T = unknown> {
+    cfg: Record<string, unknown>;
+    accountId: string;
+    account: T;
+    runtime: GatewayRuntime;
+    abortSignal: AbortSignal;
+}
+interface GatewayRuntime {
+    routeMessage(envelope: MessageEnvelope): void;
+}
+interface MessageEnvelope {
+    channelId: string;
+    messageId: string;
+    senderId: string;
+    senderName: string;
+    text: string;
+    timestamp: number;
+    isGroupMessage: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface ChannelGatewayAdapter<T = unknown> {
+    startAccount?(ctx: ChannelGatewayContext<T>): Promise<unknown>;
+    stopAccount?(ctx: ChannelGatewayContext<T>): Promise<void>;
+}
+interface MstpChannelPlugin {
+    id: string;
+    meta: ChannelMeta;
+    capabilities: ChannelCapabilities;
+    config: ChannelConfigAdapter<MstpAccount>;
+    outbound: ChannelOutboundAdapter;
+    gateway: ChannelGatewayAdapter<MstpAccount>;
+}
+export declare const mstpChannel: MstpChannelPlugin;
+export {};
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAUtD,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,iBAsKzB,CAAC"}

package/dist/channel.js

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+import { clearConnectorClient, extractMstpConfig, initConnectorClient, initToolConfig, } from "./config.js";
+import { ConnectorClient } from "./connector-client.js";
+// --- Sender identity ---
+/**
+ * Use sessionId as the sender identifier for OpenClaw routing.
+ *
+ * OpenClaw Gateway sets `ctx.recipient = senderId` when the LLM replies.
+ * Our `sendText()` uses `ctx.recipient` as a sessionId to look up the
+ * MSTP session. So senderId MUST equal sessionId for reply routing to work.
+ *
+ * Each MSTP session maps to a separate OpenClaw conversation — correct
+ * semantics since sessions are independent, ephemeral exchanges.
+ *
+ * The remote Agent's MSTP address (from `metadata.from`) is preserved in
+ * `senderName` and the envelope's `metadata` field — identity is not lost.
+ */
+function deriveSenderId(event) {
+    return event.sessionId;
+}
+/**
+ * Extract a human-readable name from the remote Agent's MSTP address.
+ *
+ * `metadata.from` contains the address (e.g. `mstps://preview.masons.ai/alice`)
+ * when the remote Agent connects through a Connector. Falls back to
+ * "Unknown Agent" for direct MSTP clients without address metadata.
+ */
+function deriveSenderName(event) {
+    const from = event.metadata?.from;
+    if (!from || typeof from !== "string") {
+        return "Unknown Agent";
+    }
+    // Extract handle from MSTP address: mstps://preview.masons.ai/alice → alice
+    const trimmed = from.replace(/\/+$/, "");
+    const parts = trimmed.split("/");
+    return parts[parts.length - 1] || from;
+}
+const accounts = new Map();
+// --- Channel Plugin ---
+export const mstpChannel = {
+    id: "agent-network",
+    meta: {
+        name: "MSTP",
+        description: "Connect your Agent to the agent network for real-time communication",
+        icon: "globe",
+    },
+    capabilities: {
+        outbound: true,
+        inbound: true,
+        groups: false,
+        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);
+        },
+        resolveAccount(cfg, accountId) {
+            const mstpCfg = extractMstpConfig(cfg);
+            if (!mstpCfg || !accountId) {
+                throw new Error("No accounts configured");
+            }
+            const accountsCfg = mstpCfg.accounts;
+            if (typeof accountsCfg !== "object" || accountsCfg === null) {
+                throw new Error("No accounts configured");
+            }
+            const raw = accountsCfg[accountId];
+            if (typeof raw !== "object" || raw === null) {
+                throw new Error(`Invalid account configuration: ${accountId}`);
+            }
+            const account = raw;
+            if (typeof account.connectorUrl !== "string" ||
+                typeof account.token !== "string") {
+                throw new Error(`Invalid account configuration: ${accountId}`);
+            }
+            return {
+                connectorUrl: account.connectorUrl,
+                token: account.token,
+            };
+        },
+    },
+    outbound: {
+        deliveryMode: "direct",
+        async sendText(ctx) {
+            // ctx.recipient = sessionId — Gateway echoes back the senderId from routeMessage
+            const state = accounts.get(ctx.accountId);
+            if (!state?.sessions.has(ctx.recipient)) {
+                return { ok: false };
+            }
+            const sent = state.client.sendMessage(ctx.recipient, ctx.text, {
+                contentType: "text",
+            });
+            return { ok: sent };
+        },
+    },
+    gateway: {
+        async startAccount(ctx) {
+            const { connectorUrl, token } = ctx.account;
+            const client = new ConnectorClient(connectorUrl, token);
+            const state = {
+                client,
+                sessions: new Map(),
+            };
+            accounts.set(ctx.accountId, state);
+            // --- Inbound message routing ---
+            client.on("message_received", (event) => {
+                const senderId = deriveSenderId(event);
+                const envelope = {
+                    channelId: "agent-network",
+                    messageId: `mstp:${event.sessionId}:${randomUUID()}`,
+                    senderId,
+                    senderName: deriveSenderName(event),
+                    text: event.content,
+                    timestamp: Date.now(),
+                    isGroupMessage: false,
+                    metadata: {
+                        ...event.metadata,
+                        contentType: event.contentType,
+                    },
+                };
+                ctx.runtime.routeMessage(envelope);
+            });
+            // --- Session lifecycle ---
+            client.on("session_created", (event) => {
+                const from = event.metadata?.from;
+                state.sessions.set(event.sessionId, {
+                    remoteAddress: typeof from === "string" && from.length > 0 ? from : null,
+                });
+            });
+            client.on("session_ended", (event) => {
+                state.sessions.delete(event.sessionId);
+            });
+            // --- Error handling ---
+            // Must register before connect() — unhandled "error" events crash the process.
+            client.on("error", (err) => {
+                console.error(`[agent-network:${ctx.accountId}]`, err.message);
+            });
+            // --- Disconnect cleanup ---
+            client.on("disconnected", () => {
+                state.sessions.clear();
+            });
+            // --- Abort signal ---
+            ctx.abortSignal.addEventListener("abort", () => {
+                clearConnectorClient(); // idempotent — stopAccount() may also call
+                client.disconnect();
+            }, { once: true });
+            // --- Inject config for LLM tools ---
+            initToolConfig(ctx.cfg);
+            // --- Connect ---
+            await client.connect();
+            // --- Expose client to tools (only after WS is connected) ---
+            initConnectorClient(client);
+            // Park the Promise — DO NOT resolve/return.
+            // Resolution signals "account stopped" to OpenClaw's orchestrator,
+            // triggering auto-restart with exponential backoff (crash-loop).
+            await new Promise((resolve) => {
+                if (ctx.abortSignal.aborted) {
+                    resolve();
+                    return;
+                }
+                ctx.abortSignal.addEventListener("abort", () => resolve(), {
+                    once: true,
+                });
+            });
+        },
+        async stopAccount(ctx) {
+            const state = accounts.get(ctx.accountId);
+            if (state) {
+                clearConnectorClient();
+                state.client.removeAllListeners();
+                state.client.disconnect();
+                state.sessions.clear();
+                accounts.delete(ctx.accountId);
+            }
+        },
+    },
+};

package/dist/cli-setup.d.ts

@@ -0,0 +1,39 @@
+/**
+ * CLI Setup Path — Device Code Flow via terminal prompts.
+ *
+ * Implements `configureInteractive()` hook for OpenClaw's
+ * `openclaw channels login --channel agent-network` command.
+ *
+ * Follows the WhatsApp channel pattern: CLI displays a code,
+ * user authorizes in browser, credentials are returned to OpenClaw
+ * which persists them to openclaw.json.
+ *
+ */
+interface Prompter {
+    text(label: string, opts?: {
+        default?: string;
+    }): Promise<string>;
+    confirm(label: string): Promise<boolean>;
+    select(label: string, choices: string[]): Promise<string>;
+}
+interface ChannelSetupContext {
+    configured: boolean;
+    label: string;
+    cfg: Record<string, unknown>;
+    runtime: unknown;
+    prompter: Prompter;
+    options: Record<string, unknown>;
+}
+type SetupResult = "skip" | {
+    cfg: Record<string, unknown>;
+    accountId?: string;
+};
+/**
+ * Interactive Device Code Flow for OpenClaw CLI.
+ *
+ * Called by `openclaw channels login --channel agent-network` or the onboarding wizard.
+ * Returns `{ cfg, accountId }` — OpenClaw CLI handles writing to openclaw.json.
+ */
+export declare function configureInteractive(ctx: ChannelSetupContext): Promise<SetupResult>;
+export {};
+//# sourceMappingURL=cli-setup.d.ts.map

package/dist/cli-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-setup.d.ts","sourceRoot":"","sources":["../src/cli-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkBH,UAAU,QAAQ;IAChB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAED,UAAU,mBAAmB;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,KAAK,WAAW,GACZ,MAAM,GACN;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAYzD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,mBAAmB,GACvB,OAAO,CAAC,WAAW,CAAC,CAetB"}

package/dist/cli-setup.js

@@ -0,0 +1,146 @@
+/**
+ * CLI Setup Path — Device Code Flow via terminal prompts.
+ *
+ * Implements `configureInteractive()` hook for OpenClaw's
+ * `openclaw channels login --channel agent-network` command.
+ *
+ * Follows the WhatsApp channel pattern: CLI displays a code,
+ * user authorizes in browser, credentials are returned to OpenClaw
+ * which persists them to openclaw.json.
+ *
+ */
+import { DEFAULT_API_HOST, initSetup, listAgents, onboard, PlatformApiError, pollSetup, reconnect, SetupExpiredError, SetupPendingError, } from "./platform-client.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CREATE_NEW_OPTION = "Create new agent";
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Interactive Device Code Flow for OpenClaw CLI.
+ *
+ * Called by `openclaw channels login --channel agent-network` or the onboarding wizard.
+ * Returns `{ cfg, accountId }` — OpenClaw CLI handles writing to openclaw.json.
+ */
+export async function configureInteractive(ctx) {
+    const { prompter } = ctx;
+    // Resolve API host from existing config or default
+    const apiHost = typeof ctx.cfg.apiHost === "string" ? ctx.cfg.apiHost : DEFAULT_API_HOST;
+    const cfg = { apiHost };
+    // --- Phase 1: Device Code Flow (init + authorize + poll) ---
+    const setupToken = await deviceCodeFlow(cfg, prompter);
+    // --- Phase 2: Agent selection or creation ---
+    const finalCreds = await agentSetup(cfg, setupToken, prompter);
+    return buildResult(finalCreds.connectorUrl, finalCreds.token, apiHost);
+}
+// ---------------------------------------------------------------------------
+// Device Code Flow
+// ---------------------------------------------------------------------------
+/**
+ * Run the Device Code Flow loop. Returns an authorized setup token.
+ * Handles code expiration by restarting with a fresh init.
+ */
+async function deviceCodeFlow(cfg, prompter) {
+    for (;;) {
+        const initResult = await initSetup(cfg);
+        // Display setup code and authorization link.
+        // Uses prompter.text() as a "press Enter to continue" prompt —
+        // OpenClaw's prompter has no display-only method, so text() with
+        // discarded input is the established pattern (see WhatsApp channel).
+        await prompter.text([
+            "",
+            `Setup code: ${initResult.setup_code}`,
+            "",
+            `Open this link to authorize: ${initResult.verification_uri}`,
+            "",
+            "Press Enter after you've authorized in the browser",
+        ].join("\n"));
+        // Poll until authorized or expired
+        const pollResult = await pollUntilAuthorized(cfg, initResult.setup_token, prompter);
+        if (pollResult === "expired") {
+            continue;
+        }
+        return pollResult.setup_token;
+    }
+}
+async function pollUntilAuthorized(cfg, setupToken, prompter) {
+    for (;;) {
+        try {
+            const result = await pollSetup(cfg, setupToken);
+            return result;
+        }
+        catch (err) {
+            if (err instanceof SetupExpiredError) {
+                await prompter.text("Setup code expired. Press Enter to generate a new one.");
+                return "expired";
+            }
+            if (err instanceof SetupPendingError) {
+                const retry = await prompter.confirm("Not authorized yet. Have you entered the code in your browser?");
+                if (!retry) {
+                    return "expired"; // User gave up — treat as restart
+                }
+                continue;
+            }
+            throw err; // Unexpected error — propagate
+        }
+    }
+}
+async function agentSetup(cfg, setupToken, prompter) {
+    const { agents } = await listAgents(cfg, setupToken);
+    if (agents.length > 0) {
+        // User has existing agents — let them choose or create new
+        const choices = [
+            ...agents.map((a) => `${a.handle} (${a.address})`),
+            CREATE_NEW_OPTION,
+        ];
+        const selected = await prompter.select("You already have agent(s). Choose one to reconnect or create new:", choices);
+        if (selected !== CREATE_NEW_OPTION) {
+            // Find the selected agent and reconnect
+            const idx = choices.indexOf(selected);
+            const agent = agents[idx];
+            if (agent) {
+                const result = await reconnect(cfg, setupToken, agent.id);
+                return { connectorUrl: result.connectorUrl, token: result.token };
+            }
+        }
+    }
+    // Create new agent
+    return createAgent(cfg, setupToken, prompter);
+}
+async function createAgent(cfg, setupToken, prompter) {
+    for (;;) {
+        const handle = await prompter.text("Choose a handle for your Agent (3-15 chars, lowercase letters, numbers, hyphens, underscores):");
+        try {
+            const result = await onboard(cfg, setupToken, { handle: handle.trim() });
+            return { connectorUrl: result.connectorUrl, token: result.token };
+        }
+        catch (err) {
+            if (err instanceof PlatformApiError) {
+                if (err.code === "handle_taken") {
+                    await prompter.text(`"${handle}" is already taken. Press Enter to try another.`);
+                    continue;
+                }
+                if (err.code === "invalid_handle") {
+                    await prompter.text(`"${handle}" is not valid. Use 3-15 lowercase letters, numbers, hyphens, or underscores. Press Enter to try again.`);
+                    continue;
+                }
+            }
+            throw err; // Unexpected error — propagate
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Result builder
+// ---------------------------------------------------------------------------
+function buildResult(connectorUrl, token, apiHost) {
+    return {
+        cfg: {
+            accounts: {
+                default: { connectorUrl, token },
+            },
+            apiHost,
+        },
+        accountId: "default",
+    };
+}

package/dist/config-schema.d.ts

@@ -0,0 +1,7 @@
+import { type Static } from "@sinclair/typebox";
+export declare const MstpAccountSchema: import("@sinclair/typebox").TObject<{
+    connectorUrl: import("@sinclair/typebox").TString;
+    token: import("@sinclair/typebox").TString;
+}>;
+export type MstpAccount = Static<typeof MstpAccountSchema>;
+//# sourceMappingURL=config-schema.d.ts.map

package/dist/config-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-schema.d.ts","sourceRoot":"","sources":["../src/config-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AAEtD,eAAO,MAAM,iBAAiB;;;EAO5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/config-schema.js

@@ -0,0 +1,9 @@
+import { Type } from "@sinclair/typebox";
+export const MstpAccountSchema = Type.Object({
+    connectorUrl: Type.String({
+        description: "WebSocket URL of the Connector Plugin endpoint",
+    }),
+    token: Type.String({
+        description: "Authentication token (API key)",
+    }),
+});

package/dist/config.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Config & runtime bridge — mediates shared state between channel.ts and tools.ts.
+ *
+ * Read/write separation architecture:
+ * - **Reads**: `initToolConfig(ctx.cfg)` injects Host-provided config into
+ *   module-level variables. Tools read from these vars via guard functions.
+ * - **Writes**: 3 fs functions write to `openclaw.json`, signaling the Host
+ *   (Gateway monitors file changes for hot-reload / restart).
+ * - **Runtime**: `initConnectorClient(client)` injects the live WebSocket
+ *   client after connection is established. Conversation tools read it via
+ *   `requireConnectorClient()`.
+ *
+ * `ctx.cfg` is the Host's authoritative value for this process lifecycle.
+ * Plugin does not re-parse the config file for reads.
+ *
+ */
+import type { ConnectorClient } from "./connector-client.js";
+import { type PlatformClientConfig } from "./platform-client.js";
+/**
+ * Extract the `channels["agent-network"]` section from the full OpenClaw config.
+ *
+ * OpenClaw Gateway passes the ENTIRE config (all of openclaw.json) to
+ * channel adapter methods and startAccount(). This helper navigates to
+ * the MSTP-specific section.
+ *
+ */
+export declare function extractMstpConfig(cfg: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * Inject Host-provided config into module-level variables.
+ *
+ * Called by `startAccount()` each time Gateway starts or hot-reloads.
+ * Ensures tools always read the Host's current config values.
+ */
+export declare function initToolConfig(cfg: Record<string, unknown>): void;
+/**
+ * Inject the live ConnectorClient after WebSocket connection is established.
+ *
+ * Called by `startAccount()` AFTER `client.connect()` resolves — ensures
+ * tools never receive a client with a null WebSocket.
+ *
+ * Phase 1 supports a single account. The double-init guard makes this
+ * assumption explicit: a second call without `clearConnectorClient()` throws.
+ */
+export declare function initConnectorClient(client: ConnectorClient): void;
+/**
+ * Clear the stored ConnectorClient reference.
+ *
+ * Called by `stopAccount()` before disconnecting — prevents tools from
+ * operating on a disconnected client.
+ */
+export declare function clearConnectorClient(): void;
+/**
+ * Get platform config. Always returns a valid config — defaults are set
+ * at module load time, and overwritten by `initToolConfig()` when
+ * `startAccount()` runs.
+ *
+ * This ensures setup tools work on first install (before credentials
+ * exist and before `startAccount()` has run).
+ */
+export declare function requirePlatformConfig(): PlatformClientConfig;
+/**
+ * Get stored API key. Throws if no credentials are configured.
+ */
+export declare function requireApiKey(): string;
+/**
+ * Get pending connection target handle, or null if none.
+ */
+export declare function getPendingTarget(): string | null;
+/**
+ * Get the live ConnectorClient. Throws if not initialized.
+ *
+ * Note: The returned client may be in a reconnecting state (WebSocket
+ * temporarily null after a drop). Callers must handle `false` returns
+ * from send methods (`sendMessage`, `createSession`, `endSession`).
+ */
+export declare function requireConnectorClient(): ConnectorClient;
+export interface MstpCredentials {
+    connectorUrl: string;
+    token: string;
+}
+/**
+ * Write credentials + apiHost to `openclaw.json`.
+ *
+ * Atomic: credentials and apiHost are written in a single operation
+ * to avoid partial-write race conditions.
+ */
+export declare function writeCredentials(creds: MstpCredentials, apiHost?: string): Promise<void>;
+/**
+ * Write pending connection target handle.
+ *
+ * Reserved for future use: web-initiated connection flows where a target
+ * handle is pre-set before the plugin starts.
+ */
+export declare function writeTargetHandle(handle: string): Promise<void>;
+/**
+ * Clear pending connection target from config file AND module-level variable.
+ *
+ * This is a deliberate exception to the read/write separation pattern:
+ * we also update `storedPendingTarget` in memory to avoid stale reads
+ * within the same session (since `initToolConfig()` only runs at startup).
+ */
+export declare function clearTargetHandle(): Promise<void>;
+/** @internal Reset module state for test isolation. */
+export declare function _resetForTesting(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +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;AAqDD,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;;;;;GAKG;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,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC"}