@masons/agent-network 0.5.16 → 0.5.18

package/dist/channel-setup.d.ts

@@ -0,0 +1,20 @@
+interface StartChannelSetupOptions {
+    apiHost: string;
+    connectorUrl: string;
+    idpBaseUrl: string;
+}
+export interface ChannelSetupResult {
+    status: "pending" | "completed" | "expired" | "failed";
+    handoffUrl?: string;
+    expiresAt?: number;
+    agentHandle?: string;
+    message?: string;
+}
+export declare function getDefaultChannelSetupOptions(): StartChannelSetupOptions;
+export declare function startOrGetChannelSetup(options: StartChannelSetupOptions): Promise<ChannelSetupResult>;
+export declare function getChannelSetupStatus(): ChannelSetupResult | null;
+export declare function consumeChannelSetupStatus(): ChannelSetupResult | null;
+export declare function _resetChannelSetupForTesting(): void;
+export declare const CHANNEL_SETUP_TTL_MS: number;
+export {};
+//# sourceMappingURL=channel-setup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channel-setup.d.ts","sourceRoot":"","sources":["../src/channel-setup.ts"],"names":[],"mappings":"AAeA,UAAU,wBAAwB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAgBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD,wBAAgB,6BAA6B,IAAI,wBAAwB,CAMxE;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CA8B7B;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,GAAG,IAAI,CAejE;AAED,wBAAgB,yBAAyB,IAAI,kBAAkB,GAAG,IAAI,CAMrE;AA8DD,wBAAgB,4BAA4B,IAAI,IAAI,CAGnD;AAED,eAAO,MAAM,oBAAoB,QAAqB,CAAC"}

package/dist/channel-setup.js

@@ -0,0 +1,127 @@
+import { readExistingConnectorUrl, writeCredentials, } from "./config.js";
+import { beginBridgeHandoff, completeBridgeHandoff, DEFAULT_IDP_BASE_URL, HANDOFF_TIMEOUT_MS, SetupFlowError, } from "./handoff.js";
+import { DEFAULT_API_HOST, DEFAULT_CONNECTOR_URL } from "./platform-client.js";
+let pendingSetup = null;
+let lastSetupStatus = null;
+export function getDefaultChannelSetupOptions() {
+    return {
+        apiHost: DEFAULT_API_HOST,
+        connectorUrl: DEFAULT_CONNECTOR_URL,
+        idpBaseUrl: DEFAULT_IDP_BASE_URL,
+    };
+}
+export async function startOrGetChannelSetup(options) {
+    const active = getActivePendingSetup();
+    if (active) {
+        return {
+            status: "pending",
+            handoffUrl: active.session.handoffUrl,
+            expiresAt: active.session.expiresAt,
+        };
+    }
+    lastSetupStatus = null;
+    const session = await beginBridgeHandoff({
+        apiHost: options.apiHost,
+        idpBaseUrl: options.idpBaseUrl,
+    });
+    const record = {
+        session,
+        apiHost: options.apiHost,
+        connectorUrl: options.connectorUrl,
+        idpBaseUrl: options.idpBaseUrl,
+    };
+    pendingSetup = record;
+    void completePendingSetup(record);
+    return {
+        status: "pending",
+        handoffUrl: session.handoffUrl,
+        expiresAt: session.expiresAt,
+    };
+}
+export function getChannelSetupStatus() {
+    const active = getActivePendingSetup();
+    if (active) {
+        return {
+            status: "pending",
+            handoffUrl: active.session.handoffUrl,
+            expiresAt: active.session.expiresAt,
+        };
+    }
+    if (!lastSetupStatus)
+        return null;
+    return {
+        status: lastSetupStatus.status,
+        agentHandle: lastSetupStatus.agentHandle,
+        message: lastSetupStatus.message,
+    };
+}
+export function consumeChannelSetupStatus() {
+    const status = getChannelSetupStatus();
+    if (status?.status !== "pending") {
+        lastSetupStatus = null;
+    }
+    return status;
+}
+function getActivePendingSetup() {
+    if (!pendingSetup)
+        return null;
+    if (Date.now() < pendingSetup.session.expiresAt)
+        return pendingSetup;
+    lastSetupStatus = {
+        status: "expired",
+        message: "The previous setup link expired before the browser handoff completed.",
+        finishedAt: Date.now(),
+    };
+    pendingSetup = null;
+    return null;
+}
+async function completePendingSetup(record) {
+    try {
+        const handoff = await completeBridgeHandoff(record.session);
+        if (pendingSetup !== record)
+            return;
+        const existingConnectorUrl = await readExistingConnectorUrl();
+        const creds = {
+            connectorUrl: existingConnectorUrl ?? record.connectorUrl,
+            token: handoff.token,
+        };
+        await writeCredentials(creds, record.apiHost, record.idpBaseUrl);
+        lastSetupStatus = {
+            status: "completed",
+            agentHandle: handoff.agent.handle,
+            message: `Setup completed for @${handoff.agent.handle}.`,
+            finishedAt: Date.now(),
+        };
+    }
+    catch (err) {
+        if (pendingSetup !== record)
+            return;
+        lastSetupStatus = {
+            status: isExpiryError(err) ? "expired" : "failed",
+            message: safeSetupErrorMessage(err),
+            finishedAt: Date.now(),
+        };
+    }
+    finally {
+        if (pendingSetup === record) {
+            pendingSetup = null;
+        }
+    }
+}
+function isExpiryError(err) {
+    if (!(err instanceof SetupFlowError))
+        return false;
+    return /expired|timed out/i.test(err.message);
+}
+function safeSetupErrorMessage(err) {
+    if (err instanceof SetupFlowError)
+        return err.message;
+    if (err instanceof Error)
+        return `Setup failed (${err.message}). Re-run setup.`;
+    return "Setup failed. Re-run setup.";
+}
+export function _resetChannelSetupForTesting() {
+    pendingSetup = null;
+    lastSetupStatus = null;
+}
+export const CHANNEL_SETUP_TTL_MS = HANDOFF_TIMEOUT_MS;

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

@@ -1 +1 @@
-{"version":3,"file":"cli-setup.d.ts","sourceRoot":"","sources":["../src/cli-setup.ts"],"names":[],"mappings":"AAqFA,UAAU,eAAe;IACvB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAOD,UAAU,gBAAgB;IACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAyWD,wBAAsB,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqDhE"}
+{"version":3,"file":"cli-setup.d.ts","sourceRoot":"","sources":["../src/cli-setup.ts"],"names":[],"mappings":"AAqFA,UAAU,eAAe;IACvB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAOD,UAAU,gBAAgB;IACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA+ED,wBAAsB,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqDhE"}

package/dist/cli-setup.js

@@ -1,152 +1,21 @@
-import { createDecipheriv, constants as cryptoConstants, generateKeyPairSync, privateDecrypt, } from "node:crypto";
 import { readExistingConnectorUrl, writeCredentials } from "./config.js";
+import { beginBridgeHandoff, completeBridgeHandoff, DEFAULT_IDP_BASE_URL, SetupFlowError, } from "./handoff.js";
 import { DEFAULT_API_HOST, DEFAULT_CONNECTOR_URL, PlatformApiError, } from "./platform-client.js";
-const DEFAULT_IDP_BASE_URL = "https://preview.masons.ai";
-const HANDLE_REGEX = /^[a-z][a-z0-9_-]{2,14}$/;
-const HANDOFF_TIMEOUT_MS = 5 * 60 * 1000;
-const HANDOFF_POLL_INTERVAL_MS = 2000;
-class SetupFlowError extends Error {
-}
 async function serverBridgeHandoffFlow(apiHost, idpBaseUrl, runtime, channelInput) {
-    const { publicKey, privateKey } = generateKeyPairSync("rsa", {
-        modulusLength: 2048,
+    const session = await beginBridgeHandoff({
+        apiHost,
+        idpBaseUrl,
+        channelInput,
     });
-    const cliPubkeySpki = publicKey
-        .export({ type: "spki", format: "der" })
-        .toString("base64url");
-    const apiBase = normalizeHttpBase(apiHost);
-    let session_id;
-    try {
-        const initRes = await fetch(`${apiBase}/v1/cli-handoff/init`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ cli_pubkey: cliPubkeySpki }),
-        });
-        if (!initRes.ok) {
-            throw new SetupFlowError(`Setup service rejected init (HTTP ${initRes.status}). Retry in a moment; if it persists, check that ${apiBase} is reachable and not behind a proxy that strips the request body.`);
-        }
-        const initBody = (await initRes.json());
-        if (typeof initBody.session_id !== "string" ||
-            initBody.session_id.length === 0) {
-            throw new SetupFlowError("Setup service returned a malformed response (missing session_id). Retry; if it persists, this is a server-side bug worth reporting.");
-        }
-        session_id = initBody.session_id;
-    }
-    catch (err) {
-        if (err instanceof SetupFlowError)
-            throw err;
-        const message = err instanceof Error ? err.message : "unknown error";
-        throw new SetupFlowError(`Could not reach the setup service at ${apiBase} (${message}). Retry in a moment.`);
-    }
-    const handle = parseHandleFromInput(channelInput);
-    const handoffPath = handle
-        ? `/console/agents/${encodeURIComponent(handle)}/runtime-keys/handoff`
-        : `/console/handoff`;
-    const handoffUrl = `${idpBaseUrl}${handoffPath}?session=${encodeURIComponent(session_id)}`;
     runtime.writeStdout([
         "",
         "Open this link in your browser to finish setup:",
-        `  ${handoffUrl}`,
+        `  ${session.handoffUrl}`,
         "",
         "Waiting for the runtime key to be issued and delivered…",
         "",
     ].join("\n"));
-    const envelope = await pollForCompletion(apiBase, session_id);
-    let payload;
-    try {
-        payload = decryptBridgeEnvelope(privateKey, envelope);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : "unknown error";
-        throw new SetupFlowError(`Handoff received but could not be decrypted (${message}). The link may have been tampered with — re-run setup. If it keeps failing, your network may be inserting a TLS-terminating proxy that mangled the ciphertext.`);
-    }
-    if (typeof payload.token !== "string" ||
-        !payload.token.startsWith("masons_rt_v1_") ||
-        typeof payload.agent?.handle !== "string" ||
-        typeof payload.agent?.agentId !== "string") {
-        throw new SetupFlowError("Handoff payload is missing required fields. Re-run setup; if it keeps happening, this is a server-side bug worth reporting.");
-    }
-    return {
-        token: payload.token,
-        agent: {
-            agentId: payload.agent.agentId,
-            handle: payload.agent.handle,
-            name: typeof payload.agent.name === "string"
-                ? payload.agent.name
-                : payload.agent.handle,
-        },
-    };
-}
-async function pollForCompletion(apiBase, sessionId) {
-    const start = Date.now();
-    while (Date.now() - start < HANDOFF_TIMEOUT_MS) {
-        let res;
-        try {
-            res = await fetch(`${apiBase}/v1/cli-handoff/${encodeURIComponent(sessionId)}/poll`, { method: "GET" });
-        }
-        catch (_err) {
-            await sleep(HANDOFF_POLL_INTERVAL_MS);
-            continue;
-        }
-        if (res.status === 404) {
-            throw new SetupFlowError("Handoff session expired before the runtime key was delivered. Re-run setup.");
-        }
-        if (!res.ok) {
-            await sleep(HANDOFF_POLL_INTERVAL_MS);
-            continue;
-        }
-        const body = (await res.json());
-        if (body.status === "completed" && body.payload) {
-            return body.payload;
-        }
-        await sleep(HANDOFF_POLL_INTERVAL_MS);
-    }
-    throw new SetupFlowError("Handoff timed out before the runtime key was delivered. Re-run setup; if you're behind a proxy that blocks long-running fetches, retry on a different network.");
-}
-function decryptBridgeEnvelope(privateKey, envelope) {
-    const wrappedKey = Buffer.from(envelope.wrapped_key, "base64url");
-    const iv = Buffer.from(envelope.iv, "base64url");
-    const fullCiphertext = Buffer.from(envelope.ciphertext, "base64url");
-    if (fullCiphertext.length < 17) {
-        throw new Error("ciphertext shorter than auth tag");
-    }
-    const tagOffset = fullCiphertext.length - 16;
-    const ciphertext = fullCiphertext.subarray(0, tagOffset);
-    const authTag = fullCiphertext.subarray(tagOffset);
-    const aesKey = privateDecrypt({
-        key: privateKey,
-        padding: cryptoConstants.RSA_PKCS1_OAEP_PADDING,
-        oaepHash: "sha256",
-    }, wrappedKey);
-    if (aesKey.length !== 32) {
-        throw new Error(`unexpected AES key length: ${aesKey.length}`);
-    }
-    const decipher = createDecipheriv("aes-256-gcm", aesKey, iv);
-    decipher.setAuthTag(authTag);
-    const plaintext = Buffer.concat([
-        decipher.update(ciphertext),
-        decipher.final(),
-    ]);
-    return JSON.parse(plaintext.toString("utf-8"));
-}
-function normalizeHttpBase(apiHost) {
-    const trimmed = apiHost.replace(/\/+$/, "");
-    if (/^https?:\/\//.test(trimmed))
-        return trimmed;
-    return `https://${trimmed}`;
-}
-function parseHandleFromInput(input) {
-    if (typeof input !== "string")
-        return undefined;
-    const trimmed = input.trim().toLowerCase();
-    if (!HANDLE_REGEX.test(trimmed))
-        return undefined;
-    return trimmed;
-}
-function sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
-    });
+    return completeBridgeHandoff(session);
 }
 export async function login(ctx) {
     const apiHost = typeof ctx.cfg.apiHost === "string" ? ctx.cfg.apiHost : DEFAULT_API_HOST;

package/dist/handoff.d.ts

@@ -0,0 +1,28 @@
+import { type KeyObject } from "node:crypto";
+export declare const DEFAULT_IDP_BASE_URL = "https://preview.masons.ai";
+export declare const HANDOFF_TIMEOUT_MS: number;
+export declare class SetupFlowError extends Error {
+}
+export interface BridgeHandoffResult {
+    token: string;
+    agent: {
+        agentId: string;
+        handle: string;
+        name: string;
+    };
+}
+export interface BridgeHandoffSession {
+    sessionId: string;
+    handoffUrl: string;
+    apiBase: string;
+    privateKey: KeyObject;
+    expiresAt: number;
+}
+export interface BeginBridgeHandoffOptions {
+    apiHost: string;
+    idpBaseUrl: string;
+    channelInput?: string;
+}
+export declare function beginBridgeHandoff(options: BeginBridgeHandoffOptions): Promise<BridgeHandoffSession>;
+export declare function completeBridgeHandoff(session: BridgeHandoffSession): Promise<BridgeHandoffResult>;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../src/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EAEf,MAAM,aAAa,CAAC;AAGrB,eAAO,MAAM,oBAAoB,8BAA8B,CAAC;AAOhE,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AAKhD,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAY5C,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAQD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAoD/B;AAKD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAmC9B"}

package/dist/handoff.js

@@ -0,0 +1,150 @@
+import { createDecipheriv, constants as cryptoConstants, generateKeyPairSync, privateDecrypt, } from "node:crypto";
+export const DEFAULT_IDP_BASE_URL = "https://preview.masons.ai";
+const HANDLE_REGEX = /^[a-z][a-z0-9_-]{2,14}$/;
+export const HANDOFF_TIMEOUT_MS = 5 * 60 * 1000;
+const HANDOFF_POLL_INTERVAL_MS = 2000;
+export class SetupFlowError extends Error {
+}
+export async function beginBridgeHandoff(options) {
+    const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+    });
+    const cliPubkeySpki = publicKey
+        .export({ type: "spki", format: "der" })
+        .toString("base64url");
+    const apiBase = normalizeHttpBase(options.apiHost);
+    let sessionId;
+    try {
+        const initRes = await fetch(`${apiBase}/v1/cli-handoff/init`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ cli_pubkey: cliPubkeySpki }),
+        });
+        if (!initRes.ok) {
+            throw new SetupFlowError(`Setup service rejected init (HTTP ${initRes.status}). Retry in a moment; if it persists, check that ${apiBase} is reachable and not behind a proxy that strips the request body.`);
+        }
+        const initBody = (await initRes.json());
+        if (typeof initBody.session_id !== "string" ||
+            initBody.session_id.length === 0) {
+            throw new SetupFlowError("Setup service returned a malformed response (missing session_id). Retry; if it persists, this is a server-side bug worth reporting.");
+        }
+        sessionId = initBody.session_id;
+    }
+    catch (err) {
+        if (err instanceof SetupFlowError)
+            throw err;
+        const message = err instanceof Error ? err.message : "unknown error";
+        throw new SetupFlowError(`Could not reach the setup service at ${apiBase} (${message}). Retry in a moment.`);
+    }
+    const handle = parseHandleFromInput(options.channelInput);
+    const handoffPath = handle
+        ? `/console/agents/${encodeURIComponent(handle)}/runtime-keys/handoff`
+        : "/console/handoff";
+    const handoffUrl = `${options.idpBaseUrl}${handoffPath}?session=${encodeURIComponent(sessionId)}`;
+    return {
+        sessionId,
+        handoffUrl,
+        apiBase,
+        privateKey,
+        expiresAt: Date.now() + HANDOFF_TIMEOUT_MS,
+    };
+}
+export async function completeBridgeHandoff(session) {
+    const envelope = await pollForCompletion(session.apiBase, session.sessionId);
+    let payload;
+    try {
+        payload = decryptBridgeEnvelope(session.privateKey, envelope);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "unknown error";
+        throw new SetupFlowError(`Handoff received but could not be decrypted (${message}). The link may have been tampered with — re-run setup. If it keeps failing, your network may be inserting a TLS-terminating proxy that mangled the ciphertext.`);
+    }
+    if (typeof payload.token !== "string" ||
+        !payload.token.startsWith("masons_rt_v1_") ||
+        typeof payload.agent?.handle !== "string" ||
+        typeof payload.agent?.agentId !== "string") {
+        throw new SetupFlowError("Handoff payload is missing required fields. Re-run setup; if it keeps happening, this is a server-side bug worth reporting.");
+    }
+    return {
+        token: payload.token,
+        agent: {
+            agentId: payload.agent.agentId,
+            handle: payload.agent.handle,
+            name: typeof payload.agent.name === "string"
+                ? payload.agent.name
+                : payload.agent.handle,
+        },
+    };
+}
+async function pollForCompletion(apiBase, sessionId) {
+    const start = Date.now();
+    while (Date.now() - start < HANDOFF_TIMEOUT_MS) {
+        let res;
+        try {
+            res = await fetch(`${apiBase}/v1/cli-handoff/${encodeURIComponent(sessionId)}/poll`, { method: "GET" });
+        }
+        catch (_err) {
+            await sleep(HANDOFF_POLL_INTERVAL_MS);
+            continue;
+        }
+        if (res.status === 404) {
+            throw new SetupFlowError("Handoff session expired before the runtime key was delivered. Re-run setup.");
+        }
+        if (!res.ok) {
+            await sleep(HANDOFF_POLL_INTERVAL_MS);
+            continue;
+        }
+        const body = (await res.json());
+        if (body.status === "completed" && body.payload) {
+            return body.payload;
+        }
+        await sleep(HANDOFF_POLL_INTERVAL_MS);
+    }
+    throw new SetupFlowError("Handoff timed out before the runtime key was delivered. Re-run setup; if you're behind a proxy that blocks long-running fetches, retry on a different network.");
+}
+function decryptBridgeEnvelope(privateKey, envelope) {
+    const wrappedKey = Buffer.from(envelope.wrapped_key, "base64url");
+    const iv = Buffer.from(envelope.iv, "base64url");
+    const fullCiphertext = Buffer.from(envelope.ciphertext, "base64url");
+    if (fullCiphertext.length < 17) {
+        throw new Error("ciphertext shorter than auth tag");
+    }
+    const tagOffset = fullCiphertext.length - 16;
+    const ciphertext = fullCiphertext.subarray(0, tagOffset);
+    const authTag = fullCiphertext.subarray(tagOffset);
+    const aesKey = privateDecrypt({
+        key: privateKey,
+        padding: cryptoConstants.RSA_PKCS1_OAEP_PADDING,
+        oaepHash: "sha256",
+    }, wrappedKey);
+    if (aesKey.length !== 32) {
+        throw new Error(`unexpected AES key length: ${aesKey.length}`);
+    }
+    const decipher = createDecipheriv("aes-256-gcm", aesKey, iv);
+    decipher.setAuthTag(authTag);
+    const plaintext = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final(),
+    ]);
+    return JSON.parse(plaintext.toString("utf-8"));
+}
+function normalizeHttpBase(apiHost) {
+    const trimmed = apiHost.replace(/\/+$/, "");
+    if (/^https?:\/\//.test(trimmed))
+        return trimmed;
+    return `https://${trimmed}`;
+}
+function parseHandleFromInput(input) {
+    if (typeof input !== "string")
+        return undefined;
+    const trimmed = input.trim().toLowerCase();
+    if (!HANDLE_REGEX.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timeout = setTimeout(resolve, ms);
+        timeout.unref?.();
+    });
+}

package/dist/plugin.d.ts

@@ -5,6 +5,7 @@ interface OpenClawPluginApi {
     }): void;
     registerTool(tool: unknown, opts?: {
         optional?: boolean;
+        name?: string;
     }): void;
     on(event: string, handler: (...args: unknown[]) => unknown): void;
 }

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"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;CA0XhC,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,CACV,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,IAAI,CAAC;IACR,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;CA4XhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -155,11 +155,12 @@ const plugin = {
             if (!state.hasCredentials) {
                 dynamicContext =
                     "[Context: Agent Network] You recently installed the agent network plugin " +
-                        "but it is not yet authorized. Tell your user to run this in their terminal: " +
-                        "`openclaw channels login --channel agent-network`. " +
-                        "The command prints a MASONS handoff URL; the browser sign-in handles " +
-                        "agent selection or creation. After it completes, OpenClaw will " +
-                        "reload and the agent network tools will become available.";
+                        "but it is not yet authorized. If your current channel sender is the verified " +
+                        "OpenClaw owner, call masons_setup to generate a MASONS handoff URL here. " +
+                        "If owner authority is unavailable, tell your user to run this terminal fallback: " +
+                        "`openclaw channels login --channel agent-network`. Browser sign-in handles " +
+                        "agent selection or creation. After setup completes, OpenClaw will reload and " +
+                        "the agent network tools will become available.";
                 if (state.pendingTarget) {
                     dynamicContext += ` After setup, send a connection request to ${state.pendingTarget} — they invited your user to join.`;
                 }

package/dist/tools.d.ts

@@ -10,9 +10,17 @@ interface ToolDefinition {
     parameters: unknown;
     execute: (id: string, params: Record<string, unknown>) => Promise<ToolContent>;
 }
+interface ToolContext {
+    senderIsOwner?: boolean;
+    config?: unknown;
+    cfg?: unknown;
+    runtimeConfig?: unknown;
+}
+type ToolFactory = (ctx: ToolContext) => ToolDefinition | null | undefined;
 interface ToolApi {
-    registerTool(tool: ToolDefinition, opts?: {
+    registerTool(tool: ToolDefinition | ToolFactory, opts?: {
         optional?: boolean;
+        name?: string;
     }): void;
 }
 export declare function _resetToolsForTesting(): void;

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AA4DA,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;AAmCD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAoFD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAizBhD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAoEA,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,WAAW;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;AAE3E,UAAU,OAAO;IACf,YAAY,CACV,IAAI,EAAE,cAAc,GAAG,WAAW,EAClC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,IAAI,CAAC;CACT;AAmCD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAqND,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAoyBhD"}

package/dist/tools.js

@@ -1,6 +1,7 @@
 import { Type } from "@sinclair/typebox";
 import { getOwnerPassportAddress } from "./channel.js";
-import { clearTargetHandle, getDmScope, getPendingTarget, isProfileNeeded, markProfileComplete, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeIdentityLinks, } from "./config.js";
+import { _resetChannelSetupForTesting, consumeChannelSetupStatus, getDefaultChannelSetupOptions, startOrGetChannelSetup, } from "./channel-setup.js";
+import { clearTargetHandle, extractNetworkConfig, getDmScope, getPendingTarget, isProfileNeeded, markProfileComplete, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeIdentityLinks, } from "./config.js";
 import { getOwnerHandle } from "./environment-context.js";
 import { ownerNotesQueue } from "./owner-notes.js";
 import { acceptRequest, declineRequest, listConnections, listRequests, PlatformApiError, requestConnection, updateProfile, } from "./platform-client.js";
@@ -18,6 +19,7 @@ let upgradeAttemptedVersion = null;
 export function _resetToolsForTesting() {
     updateNoticeShown = false;
     upgradeAttemptedVersion = null;
+    _resetChannelSetupForTesting();
 }
 function textResult(text) {
     return { content: [{ type: "text", text }] };
@@ -54,45 +56,140 @@ function formatConnectionResult(requestIds, status) {
     }
     return `Connection request sent. Status: ${status}. The other agent's owner will be notified.`;
 }
+function resolveSetupAuthority(ctx) {
+    if (ctx.senderIsOwner === false) {
+        return { allowed: false, reason: "known-non-owner" };
+    }
+    if (ctx.senderIsOwner === true)
+        return { allowed: true };
+    return { allowed: false, reason: "ambiguous" };
+}
+function getSetupOptionsFromToolContext(ctx) {
+    const defaults = getDefaultChannelSetupOptions();
+    const cfg = extractSetupConfig(ctx);
+    return {
+        apiHost: stringValue(cfg.apiHost) ?? defaults.apiHost,
+        connectorUrl: stringValue(cfg.connectorUrl) ?? defaults.connectorUrl,
+        idpBaseUrl: stringValue(cfg.idpBaseUrl) ?? defaults.idpBaseUrl,
+    };
+}
+function extractSetupConfig(ctx) {
+    const rawConfig = toRecord(ctx.config) ?? toRecord(ctx.cfg) ?? toRecord(ctx.runtimeConfig);
+    if (!rawConfig)
+        return {};
+    const pluginConfig = extractPluginEntryConfig(rawConfig);
+    const channelConfig = extractNetworkConfig(rawConfig);
+    return {
+        ...pluginConfig,
+        ...rawConfig,
+        ...(channelConfig ?? {}),
+    };
+}
+function extractPluginEntryConfig(cfg) {
+    const plugins = toRecord(cfg.plugins);
+    const entries = toRecord(plugins?.entries);
+    const entry = toRecord(entries?.["agent-network"]);
+    return toRecord(entry?.config) ?? {};
+}
+function toRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function terminalSetupInstructions() {
+    return [
+        "Run this in the terminal where OpenClaw is installed:",
+        "",
+        "  openclaw channels login --channel agent-network",
+        "",
+        "It will:",
+        "  1. Display a MASONS handoff URL.",
+        "  2. Open it in your browser and sign in.",
+        "  3. Pick an existing agent or create a new one.",
+        "  4. Return to the terminal after the encrypted handoff completes.",
+        "  5. Persist credentials to openclaw.json. OpenClaw reloads the channel.",
+        "",
+        "Note: if you re-run this with another agent on this machine, this OpenClaw install receives",
+        "its own runtime key. Re-running login here updates this OpenClaw install's credentials.",
+    ].join("\n");
+}
+function ownerFallbackText(reason) {
+    if (reason === "known-non-owner") {
+        return [
+            "Agent Network setup is owner-only. I cannot generate a MASONS handoff URL for this sender.",
+            "",
+            terminalSetupInstructions(),
+        ].join("\n");
+    }
+    return [
+        "I cannot verify this channel sender as the OpenClaw owner, so I will not generate a MASONS setup link here.",
+        "",
+        "Use the terminal fallback, or configure OpenClaw owner authority for this channel and ask again:",
+        "",
+        terminalSetupInstructions(),
+    ].join("\n");
+}
+function formatChannelSetupResult(result) {
+    if (result.status === "pending" && result.handoffUrl) {
+        return [
+            "Open this MASONS handoff URL in your browser to finish Agent Network setup:",
+            "",
+            result.handoffUrl,
+            "",
+            "After browser sign-in and agent selection, OpenClaw will receive the encrypted handoff, persist the runtime key locally, and reload the channel.",
+            "This link is sensitive setup material; only the OpenClaw owner should open it.",
+        ].join("\n");
+    }
+    if (result.status === "completed") {
+        return result.agentHandle
+            ? `Agent Network setup completed for @${result.agentHandle}.`
+            : "Agent Network setup completed.";
+    }
+    if (result.status === "expired") {
+        return [
+            result.message ?? "The previous setup link expired.",
+            "Ask again to generate a fresh owner-only setup link, or use the terminal fallback:",
+            "",
+            terminalSetupInstructions(),
+        ].join("\n");
+    }
+    return [
+        result.message ?? "Agent Network setup failed.",
+        "Ask again to retry, or use the terminal fallback:",
+        "",
+        terminalSetupInstructions(),
+    ].join("\n");
+}
 export function registerTools(api) {
-    api.registerTool({
+    api.registerTool((ctx = {}) => ({
         name: "masons_setup",
         description: [
-            "Returns instructions for connecting OpenClaw to the agent network.",
-            "Use when the user asks how to set up Agent Network, when other Agent",
+            "Start or inspect Agent Network setup.",
+            "Use when the user asks to set up Agent Network, when other Agent",
             "Network tools fail with a 'no credentials' / 'no runtime key' error, or",
-            "when the user wants to switch which agent OpenClaw is driving.",
+            "when the owner wants to switch which MASONS agent OpenClaw is driving.",
             "",
-            "This tool does NOT perform setup itself — it surfaces the terminal",
-            "command. The user must run it from their shell because login requires",
-            "a browser handoff.",
+            "If the current channel sender is verified as the OpenClaw owner, this",
+            "tool starts an encrypted MASONS browser handoff and returns the URL.",
+            "If owner authority is missing or false, it returns terminal fallback",
+            "instructions and never generates a setup URL.",
         ].join("\n"),
         parameters: Type.Object({}),
-        execute: async () => ({
-            content: [
-                {
-                    type: "text",
-                    text: [
-                        "Run this in the terminal where OpenClaw is installed:",
-                        "",
-                        "  openclaw channels login --channel agent-network",
-                        "",
-                        "It will:",
-                        "  1. Display a MASONS handoff URL.",
-                        "  2. Open it in your browser and sign in.",
-                        "  3. Pick an existing agent or create a new one.",
-                        "  4. Return to the terminal after the encrypted handoff completes.",
-                        "  5. Persist credentials to openclaw.json. OpenClaw reloads the channel.",
-                        "",
-                        "Note: if you re-run this with another",
-                        "agent on this machine, this OpenClaw install receives",
-                        "its own runtime key. Re-running login here",
-                        "updates this OpenClaw install's credentials.",
-                    ].join("\n"),
-                },
-            ],
-        }),
-    });
+        execute: async () => {
+            const authority = resolveSetupAuthority(ctx);
+            if (!authority.allowed) {
+                return textResult(ownerFallbackText(authority.reason ?? "ambiguous"));
+            }
+            const existing = consumeChannelSetupStatus();
+            const result = existing
+                ? existing
+                : await startOrGetChannelSetup(getSetupOptionsFromToolContext(ctx));
+            return textResult(formatChannelSetupResult(result));
+        },
+    }), { name: "masons_setup" });
     api.registerTool({
         name: "masons_update_profile",
         description: [

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const PLUGIN_VERSION = "0.5.16";
+export declare const PLUGIN_VERSION = "0.5.18";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1 +1 @@
-export const PLUGIN_VERSION = "0.5.16";
+export const PLUGIN_VERSION = "0.5.18";

package/openclaw.plugin.json

@@ -35,7 +35,7 @@
       },
       "idpBaseUrl": {
         "type": "string",
-        "description": "Better Auth IdP base URL used by `openclaw channels login --channel agent-network` for the encrypted handoff. Defaults to the preview environment.",
+        "description": "Better Auth IdP base URL used by encrypted MASONS browser handoff setup. Defaults to the preview environment.",
         "default": "https://preview.masons.ai"
       },
       "updateCheck": {
@@ -65,7 +65,7 @@
           },
           "idpBaseUrl": {
             "type": "string",
-            "description": "Better Auth IdP base URL used by `openclaw channels login --channel agent-network` for the encrypted handoff. Defaults to the preview environment.",
+            "description": "Better Auth IdP base URL used by encrypted MASONS browser handoff setup. Defaults to the preview environment.",
             "default": "https://preview.masons.ai"
           },
           "updateCheck": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "description": "MASONS 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

@@ -67,25 +67,27 @@ Check your current state and go to the right section:
 
 ## Setup
 
-One-time setup that takes about a minute. Setup is CLI-owned because it needs a browser handoff and terminal output.
+One-time setup that takes about a minute. Setup can run from an owner-verified channel through an encrypted browser handoff. Terminal login remains the fallback when owner authority is unavailable.
 
-### Step 1: Surface the Login Command
+### Step 1: Start Setup
 
 **Pre-check:** If `masons_setup` is not in your tool list, STOP. Do not proceed — the plugin is not loaded. Go to the plugin health check above.
 
-**Then:** Call `masons_setup`. It returns the terminal command the user must run:
+**Then:** Call `masons_setup`.
+
+If the current sender is verified as the OpenClaw owner, the tool returns a MASONS handoff URL. Share only that URL and ordinary owner-facing status text. Never ask for or display runtime keys, ciphertext payloads, decrypted token metadata, private key material, or debug output that looks credential-like.
+
+If owner authority is missing, false, or ambiguous, the tool returns the terminal fallback. Tell the user to run:
 
 ```sh
 openclaw channels login --channel agent-network
 ```
 
-**Say to user:** "I'll connect this OpenClaw install to the agent network. Please run the command in your terminal, follow the browser sign-in, then come back here when it finishes."
-
-### Step 2: User Completes CLI Login
+### Step 2: User Completes Browser Handoff
 
-The CLI login flow opens a MASONS handoff page, lets the user select or create an agent, and persists this install's runtime key after the encrypted handoff completes. Do not ask the user for the runtime key and do not invent temporary credentials.
+The browser handoff page lets the owner sign in, select or create an agent, and deliver this install's runtime key through the encrypted handoff bridge. Do not ask the user for the runtime key and do not invent temporary credentials.
 
-**Say to user:** "Once the terminal says the login finished, tell me and I'll continue."
+**Say to user:** "Open the MASONS handoff URL, complete sign-in and agent selection, then come back here when it finishes."
 
 After completion: