@masons/agent-network 0.1.5

package/dist/platform-client.d.ts

@@ -0,0 +1,113 @@
+/**
+ * MASONS Platform API client.
+ *
+ * Pure HTTP functions wrapping the setup and connection API endpoints.
+ * Zero platform dependencies — only global fetch.
+ *
+ * Used by:
+ * - cli-setup.ts  (CLI path: configureInteractive)
+ * - tools.ts      (LLM path: tool execute functions)
+ */
+/** Default API host. */
+export declare const DEFAULT_API_HOST = "preview-platform.masons.ai";
+export interface PlatformClientConfig {
+    apiHost: string;
+}
+export declare class PlatformApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** HTTP 428 — user hasn't authorized the setup code yet. Keep polling. */
+export declare class SetupPendingError extends PlatformApiError {
+    constructor(message?: string);
+}
+/** HTTP 410 — setup token expired or not found. Must start over. */
+export declare class SetupExpiredError extends PlatformApiError {
+    constructor(message?: string);
+}
+export interface InitSetupResponse {
+    setup_code: string;
+    setup_token: string;
+    verification_uri: string;
+    expires_in: number;
+    interval: number;
+}
+export interface PollSetupResponse {
+    status: "authorized";
+    setup_token: string;
+    expires_in: number;
+}
+export interface AgentInfo {
+    id: string;
+    handle: string;
+    address: string;
+    deliveryMode: string;
+    createdAt: string;
+}
+export interface ListAgentsResponse {
+    agents: AgentInfo[];
+}
+export interface OnboardResponse {
+    agentId: string;
+    handle: string;
+    address: string;
+    connectorUrl: string;
+    token: string;
+}
+/** Same shape as OnboardResponse. */
+export type ReconnectResponse = OnboardResponse;
+export interface RequestConnectionResponse {
+    requestIds: string[];
+    status: string;
+}
+/**
+ * `POST /setup/init` — Start Device Code Flow.
+ *
+ * Public endpoint (no auth). Returns a setup code for the user to enter
+ * in their browser, plus a setup token for subsequent API calls.
+ */
+export declare function initSetup(cfg: PlatformClientConfig): Promise<InitSetupResponse>;
+/**
+ * `POST /setup/poll` — Poll for user authorization.
+ *
+ * Public endpoint. The setup token is sent in the request body (not header).
+ *
+ * @throws {SetupPendingError} 428 — user hasn't authorized yet
+ * @throws {SetupExpiredError} 410 — token expired, start over
+ */
+export declare function pollSetup(cfg: PlatformClientConfig, setupToken: string): Promise<PollSetupResponse>;
+/**
+ * `GET /me/agents` — List authenticated user's agents.
+ *
+ * Requires Setup Token in Authorization header.
+ */
+export declare function listAgents(cfg: PlatformClientConfig, setupToken: string): Promise<ListAgentsResponse>;
+/**
+ * `POST /onboard` — Create a new agent identity.
+ *
+ * Requires Setup Token in Authorization header.
+ * Returns credentials for Gateway connection and API access.
+ */
+export declare function onboard(cfg: PlatformClientConfig, setupToken: string, params: {
+    handle: string;
+    name?: string;
+}): Promise<OnboardResponse>;
+/**
+ * `POST /agents/{id}/reconnect` — Rotate API key for an existing agent.
+ *
+ * Requires Setup Token in Authorization header.
+ * Returns fresh credentials (same shape as onboard).
+ */
+export declare function reconnect(cfg: PlatformClientConfig, setupToken: string, agentId: string): Promise<ReconnectResponse>;
+/**
+ * `POST /connections/request` — Send a connection request.
+ *
+ * Requires API Key in Authorization header.
+ * Idempotent: returns 201 with empty requestIds if already connected.
+ */
+export declare function requestConnection(cfg: PlatformClientConfig, apiKey: string, params: {
+    targetHandle: string;
+    variants: ("distribute" | "receive")[];
+}): Promise<RequestConnectionResponse>;
+//# sourceMappingURL=platform-client.d.ts.map

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

@@ -0,0 +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"}

package/dist/platform-client.js

@@ -0,0 +1,163 @@
+/**
+ * MASONS Platform API client.
+ *
+ * Pure HTTP functions wrapping the setup and connection API endpoints.
+ * Zero platform dependencies — only global fetch.
+ *
+ * Used by:
+ * - cli-setup.ts  (CLI path: configureInteractive)
+ * - tools.ts      (LLM path: tool execute functions)
+ */
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+/** Default API host. */
+export const DEFAULT_API_HOST = "preview-platform.masons.ai";
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+export class PlatformApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "PlatformApiError";
+    }
+}
+/** HTTP 428 — user hasn't authorized the setup code yet. Keep polling. */
+export class SetupPendingError extends PlatformApiError {
+    constructor(message = "Authorization pending") {
+        super(428, "authorization_pending", message);
+        this.name = "SetupPendingError";
+    }
+}
+/** HTTP 410 — setup token expired or not found. Must start over. */
+export class SetupExpiredError extends PlatformApiError {
+    constructor(message = "Setup token expired") {
+        super(410, "expired_token", message);
+        this.name = "SetupExpiredError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function baseUrl(cfg) {
+    return `https://${cfg.apiHost}/openclaw/v1`;
+}
+async function handleError(res) {
+    const body = (await res.json().catch(() => ({})));
+    const code = typeof body.error === "string" ? body.error : "unknown";
+    const message = typeof body.message === "string" ? body.message : res.statusText;
+    if (res.status === 428)
+        throw new SetupPendingError(message);
+    if (res.status === 410)
+        throw new SetupExpiredError(message);
+    throw new PlatformApiError(res.status, code, message);
+}
+// ---------------------------------------------------------------------------
+// API functions
+// ---------------------------------------------------------------------------
+/**
+ * `POST /setup/init` — Start Device Code Flow.
+ *
+ * Public endpoint (no auth). Returns a setup code for the user to enter
+ * in their browser, plus a setup token for subsequent API calls.
+ */
+export async function initSetup(cfg) {
+    const res = await fetch(`${baseUrl(cfg)}/setup/init`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+    });
+    if (!res.ok)
+        return handleError(res);
+    return (await res.json());
+}
+/**
+ * `POST /setup/poll` — Poll for user authorization.
+ *
+ * Public endpoint. The setup token is sent in the request body (not header).
+ *
+ * @throws {SetupPendingError} 428 — user hasn't authorized yet
+ * @throws {SetupExpiredError} 410 — token expired, start over
+ */
+export async function pollSetup(cfg, setupToken) {
+    const res = await fetch(`${baseUrl(cfg)}/setup/poll`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ setup_token: setupToken }),
+    });
+    if (!res.ok)
+        return handleError(res);
+    return (await res.json());
+}
+/**
+ * `GET /me/agents` — List authenticated user's agents.
+ *
+ * Requires Setup Token in Authorization header.
+ */
+export async function listAgents(cfg, setupToken) {
+    const res = await fetch(`${baseUrl(cfg)}/me/agents`, {
+        headers: { Authorization: `Bearer ${setupToken}` },
+    });
+    if (!res.ok)
+        return handleError(res);
+    return (await res.json());
+}
+/**
+ * `POST /onboard` — Create a new agent identity.
+ *
+ * Requires Setup Token in Authorization header.
+ * Returns credentials for Gateway connection and API access.
+ */
+export async function onboard(cfg, setupToken, params) {
+    const res = await fetch(`${baseUrl(cfg)}/onboard`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${setupToken}`,
+        },
+        body: JSON.stringify(params),
+    });
+    if (!res.ok)
+        return handleError(res);
+    return (await res.json());
+}
+/**
+ * `POST /agents/{id}/reconnect` — Rotate API key for an existing agent.
+ *
+ * Requires Setup Token in Authorization header.
+ * Returns fresh credentials (same shape as onboard).
+ */
+export async function reconnect(cfg, setupToken, agentId) {
+    const res = await fetch(`${baseUrl(cfg)}/agents/${encodeURIComponent(agentId)}/reconnect`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${setupToken}`,
+        },
+    });
+    if (!res.ok)
+        return handleError(res);
+    return (await res.json());
+}
+/**
+ * `POST /connections/request` — 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`, {
+        method: "POST",
+        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

@@ -0,0 +1,27 @@
+interface OpenClawPluginApi {
+    registerChannel(opts: {
+        plugin: unknown;
+    }): void;
+    registerTool(tool: unknown, opts?: {
+        optional?: boolean;
+    }): void;
+}
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        properties: {
+            apiHost: {
+                type: "string";
+                description: string;
+                default: string;
+            };
+        };
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AASA,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;CAClE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;kBAsBI,iBAAiB;CAmBhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -0,0 +1,46 @@
+// OpenClaw Plugin entry point.
+// Loaded by OpenClaw Gateway via the "openclaw.extensions" field in package.json.
+// NOT imported by index.ts to avoid pulling ws/typebox into Next.js app bundles.
+import { mstpChannel } from "./channel.js";
+import { configureInteractive } from "./cli-setup.js";
+import { registerMstpTools } from "./tools.js";
+const plugin = {
+    id: "agent-network",
+    name: "MSTP",
+    description: "Connect your Agent to the agent network for real-time communication",
+    // configSchema MUST be on the plugin export object (not just openclaw.plugin.json).
+    // Gateway validates user config via AJV against this schema BEFORE calling register().
+    // Missing configSchema → register() is never called (silent skip, no error logged).
+    // Keep in sync with openclaw.plugin.json.
+    configSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            apiHost: {
+                type: "string",
+                description: "MASONS Platform API host",
+                default: "preview-platform.masons.ai",
+            },
+        },
+    },
+    register(api) {
+        // Register tools FIRST — they must be available even when the channel
+        // has no credentials yet (setup flow needs these tools to GET credentials).
+        registerMstpTools(api);
+        // Channel registration may fail if no credentials are configured yet.
+        // This is expected on first run — the user will use the setup tools above
+        // to obtain credentials, then restart to activate the channel.
+        try {
+            api.registerChannel({
+                plugin: {
+                    ...mstpChannel,
+                    setup: { configureInteractive },
+                },
+            });
+        }
+        catch {
+            // Silently ignore — channel will be registered after setup + restart.
+        }
+    },
+};
+export default plugin;

package/dist/tools.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ *
+ * Two access patterns:
+ * - **HTTP tools** (setup, connection): read config via `requirePlatformConfig()`,
+ *   call Platform API via `platform-client.ts`.
+ * - **WebSocket tools** (conversation): read runtime client via
+ *   `requireConnectorClient()`, send/receive over the live connection.
+ *
+ */
+interface ToolContent {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: unknown;
+    execute: (id: string, params: Record<string, unknown>) => Promise<ToolContent>;
+}
+interface ToolApi {
+    registerTool(tool: ToolDefinition, opts?: {
+        optional?: boolean;
+    }): void;
+}
+/** @internal Reset module state for test isolation. */
+export declare function _resetToolsForTesting(): void;
+/** @internal Override session creation timeout for tests. */
+export declare function _setSessionTimeoutForTesting(ms: number): void;
+/**
+ * Register MSTP setup and connection tools with the OpenClaw Plugin API.
+ *
+ * Called from `plugin.ts` during plugin registration. Tools become available
+ * to the LLM after the plugin loads. Tools that require config will fail-fast
+ * with a clear error if `initToolConfig()` hasn't been called yet (i.e.,
+ * `startAccount()` hasn't run).
+ */
+export declare function registerMstpTools(api: ToolApi): void;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6BH,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,CAG5C;AAED,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7D;AAmGD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAsRpD"}