@masons/agent-network 0.4.25 → 0.5.0

package/dist/connector-client.js

@@ -12,6 +12,13 @@ const BACKOFF_INITIAL_MS = 1_000;
 const BACKOFF_MAX_MS = 30_000;
 const ALREADY_CONNECTED_RETRY_MS = 2_000;
 const ALREADY_CONNECTED_MAX_RETRIES = 30;
+// --- Single-driver Node semantic (#1264) ---
+// The connector closes with WS code 4001 + this reason when a new Runtime
+// REGISTERs for the same agentId. The current api_key may have been rotated
+// by /runtime/v1/onboard select mode, so reconnecting with the cached token
+// is futile (would 401 forever).
+const REPLACED_BY_NEW_RUNTIME_REASON = "Replaced by new Runtime";
+const REPLACED_BY_NEW_RUNTIME_CODE = 4001;
 // --- Error class for structured errors ---
 /**
  * Error with machine-readable `code` from Connector structured errors.
@@ -146,6 +153,8 @@ export class ConnectorClient extends EventEmitter {
                 this.startRegisterTimeout();
             });
             ws.on("message", this.handleMessage);
+            // ws's "close" event passes (code, reason) — handleClose accepts both.
+            // Pass the bound arrow reference so cleanupConnection can `off()` it.
             ws.on("close", this.handleClose);
             ws.on("error", this.handleError);
         });
@@ -277,7 +286,13 @@ export class ConnectorClient extends EventEmitter {
                 this.ws?.close(4001, reason);
                 return;
             }
-            // "Already connected" — track retries for short backoff
+            // "Already connected" — track retries for short backoff.
+            // As of connector #1264 the server flips this to single-driver
+            // eviction (close code 4001 + reason "Replaced by new Runtime",
+            // handled in handleClose). The REGISTER_ACK error path with this
+            // reason is now only reachable against pre-#1264 connector
+            // deployments during a rollout window — kept for that compat,
+            // safe to remove in 0.7.0 once preview/production are upgraded.
             if (reason === "Already connected") {
                 this.alreadyConnectedRetries++;
             }
@@ -319,10 +334,36 @@ export class ConnectorClient extends EventEmitter {
         this.emit("error", new Error(`[${event.code}] ${event.message}`));
     }
     // --- Connection close ---
-    handleClose = () => {
-        dbg("connection closed intentional=%s", this.intentionalClose);
+    handleClose = (code, reason) => {
+        const reasonStr = reason
+            ? typeof reason === "string"
+                ? reason
+                : reason.toString()
+            : "";
+        dbg("connection closed code=%s reason=%s intentional=%s", code ?? "?", reasonStr, this.intentionalClose);
         const wasRegistering = this.registerReject !== null;
         this.cleanupConnection();
+        // Single-driver eviction (#1264) — connector closes us with code 4001
+        // and reason "Replaced by new Runtime" when a new REGISTER claims our
+        // agentId. The api_key we hold may have been rotated by the new
+        // Runtime's /runtime/v1/onboard call; reconnecting would 401 forever.
+        // Treat as terminal: stop reconnects, surface an actionable message,
+        // emit a distinct event so consumers (channel.ts, etc.) can react.
+        const replacedByNewRuntime = code === REPLACED_BY_NEW_RUNTIME_CODE &&
+            reasonStr === REPLACED_BY_NEW_RUNTIME_REASON;
+        if (replacedByNewRuntime) {
+            this.intentionalClose = true;
+            const msg = "This agent was claimed by another Runtime " +
+                "(api_key rotated, this Runtime disconnected). " +
+                "Re-run `openclaw channels login --channel agent-network` " +
+                "to drive this agent from here again.";
+            this.emit("error", new Error(msg));
+            if (wasRegistering) {
+                this.rejectRegister(new Error(msg));
+            }
+            this.emit("disconnected");
+            return;
+        }
         if (wasRegistering) {
             // Connection closed during REGISTER — check for special retry logic
             // (handled by rejectRegister which was already called if ACK error came first)

package/dist/platform-client.d.ts

@@ -1,15 +1,18 @@
 /**
- * MASONS Platform API client.
+ * MASONS runtime API client.
  *
- * Pure HTTP functions wrapping the setup and connection API endpoints.
+ * Pure HTTP functions wrapping `/runtime/v1/*` endpoints on the connector.
  * Zero platform dependencies — only global fetch.
  *
- * Used by:
- * - cli-setup.ts  (CLI path: configureInteractive)
- * - tools.ts      (LLM path: tool execute functions)
+ * Used by `tools.ts` (LLM path: tool execute functions).
+ *
+ * The pre-0.5.0 setup-flow functions (`initSetup`, `pollSetup`, `listAgents`,
+ * `onboard`, `reconnect`) were deleted in this version: onboarding moves to
+ * the OAuth Device Authorization Grant flow served by Better Auth at the IdP
+ * (#1253), not via bespoke MASONS endpoints on the runtime API.
  */
 /** Default API host. */
-export declare const DEFAULT_API_HOST = "preview-platform.masons.ai";
+export declare const DEFAULT_API_HOST = "preview-connectorapi.masons.ai";
 export interface PlatformClientConfig {
     apiHost: string;
 }
@@ -18,46 +21,6 @@ export declare class PlatformApiError extends Error {
     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;
-    agent_id: string | null;
-}
-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;
@@ -124,45 +87,77 @@ export interface ConnectionStatusResponse {
     status: "connected" | "pending" | "not_connected";
     canCreateSession: boolean;
 }
+/** Successful onboard — returned by all three branches. */
+export interface OnboardSuccess {
+    apiKey: string;
+    connectorUrl: string;
+    agentId: string;
+    handle: string;
+}
+export interface OnboardAgentSummary {
+    id: string;
+    handle: string;
+    name: 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.
+ * 422 agent_required — user owns multiple agents and didn't pick one.
+ * Plugin should prompter.select() from `agents` and re-call with `{agentId}`.
  */
-export declare function initSetup(cfg: PlatformClientConfig): Promise<InitSetupResponse>;
+export interface OnboardAgentRequiredError {
+    status: 422;
+    code: "agent_required";
+    agents: OnboardAgentSummary[];
+}
 /**
- * `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
+ * 412 no_agents — user owns zero agents. Plugin should prompt for handle
+ * and re-call with `{create: {handle}}`.
  */
-export declare function pollSetup(cfg: PlatformClientConfig, setupToken: string): Promise<PollSetupResponse>;
+export interface OnboardNoAgentsError {
+    status: 412;
+    code: "no_agents";
+    message: string;
+}
 /**
- * `GET /me/agents` — List authenticated user's agents.
- *
- * Requires Setup Token in Authorization header.
+ * 409 handle_taken — handle conflict in create branch. Plugin should
+ * re-prompt for a different handle.
  */
-export declare function listAgents(cfg: PlatformClientConfig, setupToken: string): Promise<ListAgentsResponse>;
+export interface OnboardHandleTakenError {
+    status: 409;
+    code: "handle_taken";
+}
 /**
- * `POST /onboard` — Create a new agent identity.
- *
- * Requires Setup Token in Authorization header.
- * Returns credentials for Gateway connection and API access.
+ * 422 invalid_handle — handle failed server-side validation. Plugin should
+ * surface the message and re-prompt.
  */
-export declare function onboard(cfg: PlatformClientConfig, setupToken: string, params: {
-    handle: string;
-    name?: string;
-}): Promise<OnboardResponse>;
+export interface OnboardInvalidHandleError {
+    status: 422;
+    code: "invalid_handle";
+    message: string;
+}
+/** Body shape for the onboard endpoint. */
+export type OnboardBody = Record<string, never> | {
+    agentId: string;
+} | {
+    create: {
+        handle: string;
+        name?: string;
+    };
+};
 /**
- * `POST /agents/{id}/reconnect` — Rotate API key for an existing agent.
+ * Result discriminator. `kind: "ok"` carries the credentials; `kind: "error"`
+ * surfaces structured errors the plugin must handle in its CLI prompter loop
+ * (no-agents → prompt handle; agent-required → prompt picker; handle-taken
+ * → re-prompt; invalid-handle → re-prompt).
  *
- * Requires Setup Token in Authorization header.
- * Returns fresh credentials (same shape as onboard).
+ * Other failure shapes (401, 403, 404, 500) are thrown as `PlatformApiError`.
  */
-export declare function reconnect(cfg: PlatformClientConfig, setupToken: string, agentId: string): Promise<ReconnectResponse>;
+export type OnboardResult = {
+    kind: "ok";
+    data: OnboardSuccess;
+} | {
+    kind: "error";
+    data: OnboardAgentRequiredError | OnboardNoAgentsError | OnboardHandleTakenError | OnboardInvalidHandleError;
+};
 /**
  * `POST /connections/requests` — Send a connection request.
  *
@@ -211,6 +206,21 @@ export declare function updateProfile(cfg: PlatformClientConfig, apiKey: string,
  * Returns name + MSTP address for each connected agent.
  */
 export declare function listConnections(cfg: PlatformClientConfig, apiKey: string): Promise<ListConnectionsResponse>;
+/**
+ * `POST /onboard` — bind a device-class client to an agent.
+ *
+ * Three branches selected by body shape (#1264):
+ *   - `{}` → list / auto-pick
+ *   - `{agentId}` → select existing (rotates api_key)
+ *   - `{create: {handle, name?}}` → mint new agent
+ *
+ * Auth: Bearer access_token from Better Auth's device-authorization plugin.
+ *
+ * Returns `{kind: "ok", data}` on 200. Returns `{kind: "error", data}` for
+ * the four structured errors the CLI prompter loop must handle. All other
+ * non-2xx responses throw `PlatformApiError`.
+ */
+export declare function onboard(cfg: PlatformClientConfig, sessionToken: string, body: OnboardBody): Promise<OnboardResult>;
 /**
  * `GET /connections/status?target={handle}` — Check connection status.
  *

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

@@ -1,18 +1,21 @@
 /**
- * MASONS Platform API client.
+ * MASONS runtime API client.
  *
- * Pure HTTP functions wrapping the setup and connection API endpoints.
+ * Pure HTTP functions wrapping `/runtime/v1/*` endpoints on the connector.
  * Zero platform dependencies — only global fetch.
  *
- * Used by:
- * - cli-setup.ts  (CLI path: configureInteractive)
- * - tools.ts      (LLM path: tool execute functions)
+ * Used by `tools.ts` (LLM path: tool execute functions).
+ *
+ * The pre-0.5.0 setup-flow functions (`initSetup`, `pollSetup`, `listAgents`,
+ * `onboard`, `reconnect`) were deleted in this version: onboarding moves to
+ * the OAuth Device Authorization Grant flow served by Better Auth at the IdP
+ * (#1253), not via bespoke MASONS endpoints on the runtime API.
  */
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
 /** Default API host. */
-export const DEFAULT_API_HOST = "preview-platform.masons.ai";
+export const DEFAULT_API_HOST = "preview-connectorapi.masons.ai";
 // ---------------------------------------------------------------------------
 // Error classes
 // ---------------------------------------------------------------------------
@@ -26,122 +29,24 @@ export class PlatformApiError extends Error {
         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`;
+    // `/runtime/v1/*` is the canonical prefix (renamed from legacy `/openclaw/v1/*`
+    // in connector PR #1248 — shared by OpenClaw plugin + Claude Code + any future
+    // device-class runtime). Atomic server-side change, no dual-serve.
+    return `https://${cfg.apiHost}/runtime/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/requests` — Send a connection request.
  *
@@ -247,6 +152,70 @@ export async function listConnections(cfg, apiKey) {
         return handleError(res);
     return (await res.json());
 }
+/**
+ * `POST /onboard` — bind a device-class client to an agent.
+ *
+ * Three branches selected by body shape (#1264):
+ *   - `{}` → list / auto-pick
+ *   - `{agentId}` → select existing (rotates api_key)
+ *   - `{create: {handle, name?}}` → mint new agent
+ *
+ * Auth: Bearer access_token from Better Auth's device-authorization plugin.
+ *
+ * Returns `{kind: "ok", data}` on 200. Returns `{kind: "error", data}` for
+ * the four structured errors the CLI prompter loop must handle. All other
+ * non-2xx responses throw `PlatformApiError`.
+ */
+export async function onboard(cfg, sessionToken, body) {
+    const res = await fetch(`${baseUrl(cfg)}/onboard`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${sessionToken}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (res.ok) {
+        const data = (await res.json());
+        return { kind: "ok", data };
+    }
+    // Branch on the structured-error codes the prompter loop knows how to
+    // recover from. Anything else → throw PlatformApiError.
+    const raw = (await res.json().catch(() => ({})));
+    const code = typeof raw.error === "string" ? raw.error : "unknown";
+    const message = typeof raw.message === "string" ? raw.message : res.statusText;
+    if (res.status === 412 && code === "no_agents") {
+        return {
+            kind: "error",
+            data: { status: 412, code: "no_agents", message },
+        };
+    }
+    if (res.status === 422 && code === "agent_required") {
+        const agents = Array.isArray(raw.agents)
+            ? raw.agents
+            : [];
+        return {
+            kind: "error",
+            data: { status: 422, code: "agent_required", agents },
+        };
+    }
+    if (res.status === 422 && code === "invalid_handle") {
+        return {
+            kind: "error",
+            data: { status: 422, code: "invalid_handle", message },
+        };
+    }
+    if (res.status === 409 && code === "handle_taken") {
+        return {
+            kind: "error",
+            data: { status: 409, code: "handle_taken" },
+        };
+    }
+    // 401 unauthorized, 403 forbidden, 404 agent_not_found, 500 internal —
+    // these are programming errors at this stage, propagate via the standard
+    // throw path so the CLI prompter loop sees them as fatal.
+    throw new PlatformApiError(res.status, code, message);
+}
 /**
  * `GET /connections/status?target={handle}` — Check connection status.
  *

package/dist/plugin.d.ts

@@ -22,6 +22,11 @@ declare const plugin: {
                 description: string;
                 default: string;
             };
+            idpBaseUrl: {
+                type: string;
+                description: string;
+                default: string;
+            };
             updateCheck: {
                 type: string;
                 description: string;

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AA4HA,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,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;;;;;;;;;;;;;;;;;;;;;kBAaI,iBAAiB;CAyVhC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAiJA,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,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;;;;;;;;;;;;;;;;;;;;;;;;;;kBAaI,iBAAiB;CAoXhC,CAAC;AAEF,eAAe,MAAM,CAAC"}