@hypercli.com/sdk 2026.3.13-2 → 2026.3.18

package/dist/agents.js

@@ -1,14 +1,39 @@
+/**
+ * HyperClaw agents API - typed agent lifecycle, files, exec, and OpenClaw access.
+ */
+import { getAgentsApiBaseUrl, getConfigValue } from './config.js';
 import { GatewayClient, } from './gateway.js';
 const AGENTS_API_BASE = 'https://api.hypercli.com/agents';
 const DEV_AGENTS_API_BASE = 'https://api.dev.hypercli.com/agents';
 const DEPLOYMENTS_API_PREFIX = '/deployments';
 const AGENTS_WS_URL = 'wss://api.agents.hypercli.com/ws';
 const DEV_AGENTS_WS_URL = 'wss://api.agents.dev.hypercli.com/ws';
+export const DEFAULT_OPENCLAW_IMAGE = 'ghcr.io/hypercli/hypercli-openclaw:prod';
 function parseDate(value) {
     if (typeof value !== 'string' || !value)
         return null;
     return new Date(value.replace('Z', '+00:00'));
 }
+function deepMergeConfig(base, patch) {
+    const merged = structuredClone(base);
+    for (const [key, value] of Object.entries(patch)) {
+        if (value &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            merged[key] &&
+            typeof merged[key] === 'object' &&
+            !Array.isArray(merged[key])) {
+            merged[key] = deepMergeConfig(merged[key], value);
+        }
+        else {
+            merged[key] = structuredClone(value);
+        }
+    }
+    return merged;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function toWsBaseUrl(baseUrl) {
     const base = (baseUrl || '').replace(/\/+$/, '');
     if (!base)
@@ -30,21 +55,42 @@ export function resolveAgentsApiBase(apiBase) {
     if (!raw)
         return AGENTS_API_BASE;
     const parsed = new URL(raw.includes('://') ? raw : `https://${raw}`);
+    const normalizedPath = parsed.pathname.replace(/\/+$/, '');
     const host = parsed.host.toLowerCase();
-    if (host === 'api.hypercli.com' || host === 'api.hyperclaw.app')
+    if (normalizedPath.endsWith('/agents')) {
+        return `${parsed.origin}${normalizedPath}`;
+    }
+    if (normalizedPath.endsWith('/api')) {
+        if (host === 'api.agents.hypercli.com') {
+            return AGENTS_API_BASE;
+        }
+        if (host === 'api.agents.dev.hypercli.com') {
+            return DEV_AGENTS_API_BASE;
+        }
+        return `${parsed.origin}${normalizedPath.slice(0, -4)}/agents`;
+    }
+    if (host === 'api.agents.hypercli.com' || host === 'api.hypercli.com' || host === 'api.hyperclaw.app') {
         return AGENTS_API_BASE;
-    if (host === 'api.dev.hypercli.com' || host === 'api.dev.hyperclaw.app' || host === 'dev-api.hyperclaw.app') {
+    }
+    if (host === 'api.agents.dev.hypercli.com' ||
+        host === 'api.dev.hypercli.com' ||
+        host === 'api.dev.hyperclaw.app' ||
+        host === 'dev-api.hyperclaw.app') {
         return DEV_AGENTS_API_BASE;
     }
-    return raw.replace(/\/$/, '');
+    const normalized = raw.replace(/\/$/, '');
+    return `${normalized}/agents`;
 }
 function defaultAgentsWsUrl(apiBase) {
     const resolvedApiBase = resolveAgentsApiBase(apiBase);
     const parsed = new URL(resolvedApiBase.includes('://') ? resolvedApiBase : `https://${resolvedApiBase}`);
     const host = parsed.host.toLowerCase();
-    if (host === 'api.hypercli.com' || host === 'api.hyperclaw.app')
+    if (host === 'api.agents.hypercli.com' || host === 'api.hypercli.com' || host === 'api.hyperclaw.app')
         return AGENTS_WS_URL;
-    if (host === 'api.dev.hypercli.com' || host === 'api.dev.hyperclaw.app' || host === 'dev-api.hyperclaw.app') {
+    if (host === 'api.agents.dev.hypercli.com' ||
+        host === 'api.dev.hypercli.com' ||
+        host === 'api.dev.hyperclaw.app' ||
+        host === 'dev-api.hyperclaw.app') {
         return DEV_AGENTS_WS_URL;
     }
     return normalizeAgentsWsUrl(resolvedApiBase);
@@ -135,6 +181,30 @@ export function buildAgentConfig(config = {}, options = {}) {
         prepared.registry_auth = options.registryAuth;
     return { config: prepared, gatewayToken };
 }
+function defaultOpenClawImage(image, config) {
+    if (image !== undefined && image !== null)
+        return image;
+    const configured = String(config?.image ?? '').trim();
+    return configured || DEFAULT_OPENCLAW_IMAGE;
+}
+export function buildOpenClawRoutes(options = {}) {
+    const routes = {};
+    if (options.includeGateway ?? true) {
+        routes.openclaw = {
+            port: options.gatewayPort ?? 18789,
+            auth: options.gatewayAuth ?? false,
+            prefix: options.gatewayPrefix ?? '',
+        };
+    }
+    if (options.includeDesktop ?? true) {
+        routes.desktop = {
+            port: options.desktopPort ?? 3000,
+            auth: options.desktopAuth ?? true,
+            prefix: options.desktopPrefix ?? 'desktop',
+        };
+    }
+    return routes;
+}
 async function getFsPromises() {
     return import('node:fs/promises');
 }
@@ -196,11 +266,30 @@ export class Agent {
     get publicUrl() {
         return this.hostname ? `https://${this.hostname}` : null;
     }
+    routePrefix(routeName, defaultPrefix = null) {
+        const route = this.routes[routeName] ?? {};
+        const prefix = route.prefix;
+        if (typeof prefix === 'undefined' || prefix === null) {
+            return defaultPrefix;
+        }
+        return String(prefix);
+    }
+    routeUrl(routeName, defaultPrefix = null) {
+        if (!this.hostname)
+            return null;
+        const prefix = this.routePrefix(routeName, defaultPrefix);
+        if (prefix === null)
+            return null;
+        return prefix === '' ? `https://${this.hostname}` : `https://${prefix}-${this.hostname}`;
+    }
+    get desktopUrl() {
+        return this.routeUrl('desktop', 'desktop');
+    }
     get vncUrl() {
-        return this.publicUrl;
+        return this.desktopUrl;
     }
     get shellUrl() {
-        return this.hostname ? `https://shell-${this.hostname}` : null;
+        return this.routeUrl('shell');
     }
     get executorUrl() {
         return this.shellUrl;
@@ -214,12 +303,22 @@ export class Agent {
         }
         return this._deployments;
     }
+    routeRequiresAuth(routeName, defaultValue = true) {
+        const route = this.routes[routeName];
+        if (!route || typeof route.auth === 'undefined') {
+            return defaultValue;
+        }
+        return Boolean(route.auth);
+    }
     async refreshToken() {
         const data = await this.requireDeployments().refreshToken(this.id);
         this.jwtToken = data.token ?? data.jwt ?? null;
         this.jwtExpiresAt = parseDate(data.expires_at);
         return data;
     }
+    async waitRunning(timeoutMs = 300_000, pollIntervalMs = 5_000) {
+        return this.requireDeployments().waitRunning(this.id, timeoutMs, pollIntervalMs);
+    }
     async env() {
         const data = await this.requireDeployments().env(this.id);
         return data.env ?? {};
@@ -269,7 +368,7 @@ export class OpenClawAgent extends Agent {
     static fromDict(data) {
         return new OpenClawAgent({
             ...agentStateFromDict(data),
-            gatewayUrl: data.openclaw_url ?? data.gateway_url ?? null,
+            gatewayUrl: data.openclaw_url ?? data.gateway_url ?? (data.hostname ? `wss://${data.hostname}` : null),
             gatewayToken: data.gateway_token ?? null,
         });
     }
@@ -288,17 +387,28 @@ export class OpenClawAgent extends Agent {
         if (!this.gatewayUrl) {
             throw new Error('Agent has no OpenClaw gateway URL');
         }
-        if (!this.jwtToken) {
-            throw new Error('Agent has no JWT token');
-        }
+        const deployments = this.requireDeployments();
         return new GatewayClient({
             url: this.gatewayUrl,
-            token: this.jwtToken,
+            token: undefined,
             gatewayToken: options.gatewayToken ?? this.gatewayToken ?? undefined,
+            deploymentId: options.deploymentId ?? this.id,
+            apiKey: options.apiKey ?? deployments.agentApiKey,
+            apiBase: options.apiBase ?? deployments.agentApiBase,
+            autoApprovePairing: options.autoApprovePairing ?? true,
             clientId: options.clientId,
             clientMode: options.clientMode,
+            clientDisplayName: options.clientDisplayName,
+            clientVersion: options.clientVersion,
+            platform: options.platform,
+            instanceId: options.instanceId,
+            caps: options.caps,
             origin: options.origin,
             timeout: options.timeout,
+            onHello: options.onHello,
+            onClose: options.onClose,
+            onGap: options.onGap,
+            onPairing: options.onPairing,
         });
     }
     async connect(options = {}) {
@@ -319,6 +429,18 @@ export class OpenClawAgent extends Agent {
             client.close();
         }
     }
+    async waitReady(timeoutMs = 300_000, options = {}) {
+        const client = this.gateway(options);
+        try {
+            return await client.waitReady(timeoutMs, {
+                retryIntervalMs: options.retryIntervalMs,
+                probe: options.probe,
+            });
+        }
+        finally {
+            client.close();
+        }
+    }
     async configGet(options = {}) {
         const client = await this.connect(options);
         try {
@@ -337,6 +459,33 @@ export class OpenClawAgent extends Agent {
             client.close();
         }
     }
+    async configPatch(patch, options = {}) {
+        const client = await this.connect(options);
+        try {
+            await client.configPatch(patch);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async configApply(config, options = {}) {
+        const client = await this.connect(options);
+        try {
+            await client.configApply(config);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async modelsList(options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.modelsList();
+        }
+        finally {
+            client.close();
+        }
+    }
     async sessionsList(options = {}) {
         const client = await this.connect(options);
         try {
@@ -357,6 +506,251 @@ export class OpenClawAgent extends Agent {
             client.close();
         }
     }
+    async channelsStatus(options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.channelsStatus(options.probe ?? false, options.timeoutMs);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async channelsLogout(channel, accountId, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.channelsLogout(channel, accountId);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async webLoginStart(options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.webLoginStart({
+                force: options.force,
+                timeoutMs: options.timeoutMs,
+                verbose: options.verbose,
+                accountId: options.accountId,
+            });
+        }
+        finally {
+            client.close();
+        }
+    }
+    async webLoginWait(options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.webLoginWait({
+                timeoutMs: options.timeoutMs,
+                accountId: options.accountId,
+            });
+        }
+        finally {
+            client.close();
+        }
+    }
+    async workspaceFiles(options = {}) {
+        const client = await this.connect(options);
+        try {
+            const agents = await client.agentsList();
+            const agentId = agents[0]?.id ?? 'main';
+            const files = await client.filesList(agentId);
+            return { agentId, files };
+        }
+        finally {
+            client.close();
+        }
+    }
+    async fileGet(name, agentId, options = {}) {
+        const client = await this.connect(options);
+        try {
+            let resolvedAgentId;
+            if (agentId) {
+                resolvedAgentId = agentId;
+            }
+            else {
+                const agents = await client.agentsList();
+                resolvedAgentId = agents[0]?.id ?? 'main';
+            }
+            return await client.fileGet(resolvedAgentId, name);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async fileSet(name, content, agentId, options = {}) {
+        const client = await this.connect(options);
+        try {
+            let resolvedAgentId;
+            if (agentId) {
+                resolvedAgentId = agentId;
+            }
+            else {
+                const agents = await client.agentsList();
+                resolvedAgentId = agents[0]?.id ?? 'main';
+            }
+            await client.fileSet(resolvedAgentId, name, content);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async chatHistory(sessionKey, limit = 50, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.chatHistory(sessionKey, limit);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async chatSendMessage(message, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.sendChat(message, options.sessionKey ?? 'main', options.agentId, options.attachments);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async mutateConfig(mutator, options = {}) {
+        const config = structuredClone(await this.configGet(options));
+        await mutator(config);
+        await this.configApply(config, options);
+        return config;
+    }
+    async providerUpsert(providerId, providerConfig, gatewayOptions = {}) {
+        const { api, baseUrl, apiKey, models, ...extra } = providerConfig;
+        const config = await this.mutateConfig((next) => {
+            const modelsCfg = (next.models ??= {});
+            const providers = (modelsCfg.providers ??= {});
+            const provider = { ...(providers[providerId] ?? {}) };
+            provider.api = api;
+            provider.baseUrl = baseUrl;
+            if (apiKey !== undefined)
+                provider.apiKey = apiKey;
+            if (models !== undefined)
+                provider.models = structuredClone(models);
+            Object.assign(provider, extra);
+            providers[providerId] = provider;
+        }, gatewayOptions);
+        return config.models?.providers?.[providerId] ?? {};
+    }
+    async providerRemove(providerId, options = {}) {
+        const config = await this.mutateConfig((next) => {
+            if (next.models?.providers) {
+                delete next.models.providers[providerId];
+            }
+        }, options);
+        return config.models?.providers ?? {};
+    }
+    async modelUpsert(providerId, modelId, modelConfig = {}, gatewayOptions = {}) {
+        const config = await this.mutateConfig((next) => {
+            const providers = ((next.models ??= {}).providers ??= {});
+            const provider = { ...(providers[providerId] ?? {}) };
+            const models = Array.isArray(provider.models)
+                ? provider.models.map((entry) => ({ ...entry }))
+                : [];
+            let model = models.find((entry) => entry.id === modelId);
+            if (!model) {
+                model = { id: modelId };
+                models.push(model);
+            }
+            Object.assign(model, modelConfig);
+            provider.models = models;
+            providers[providerId] = provider;
+        }, gatewayOptions);
+        return (config.models?.providers?.[providerId]?.models?.find((entry) => entry.id === modelId) ??
+            {});
+    }
+    async modelRemove(providerId, modelId, options = {}) {
+        const config = await this.mutateConfig((next) => {
+            const providers = ((next.models ??= {}).providers ??= {});
+            const provider = { ...(providers[providerId] ?? {}) };
+            provider.models = Array.isArray(provider.models)
+                ? provider.models.filter((entry) => entry.id !== modelId)
+                : [];
+            providers[providerId] = provider;
+        }, options);
+        return config.models?.providers?.[providerId]?.models ?? [];
+    }
+    async setDefaultModel(providerId, modelId, options = {}) {
+        const primary = `${providerId}/${modelId}`;
+        await this.mutateConfig((next) => {
+            const defaults = ((next.agents ??= {}).defaults ??= {});
+            const model = (defaults.model ??= {});
+            model.primary = primary;
+        }, options);
+        return primary;
+    }
+    async setMemorySearch(memorySearchConfig, gatewayOptions = {}) {
+        const { provider, model, baseUrl, apiKey, ...extra } = memorySearchConfig;
+        const config = await this.mutateConfig((next) => {
+            const defaults = ((next.agents ??= {}).defaults ??= {});
+            const memorySearch = { ...(defaults.memorySearch ?? {}) };
+            memorySearch.provider = provider;
+            memorySearch.model = model;
+            const remote = { ...(memorySearch.remote ?? {}) };
+            if (baseUrl !== undefined)
+                remote.baseUrl = baseUrl;
+            if (apiKey !== undefined)
+                remote.apiKey = apiKey;
+            if (Object.keys(remote).length > 0)
+                memorySearch.remote = remote;
+            Object.assign(memorySearch, extra);
+            defaults.memorySearch = memorySearch;
+        }, gatewayOptions);
+        return config.agents?.defaults?.memorySearch ?? {};
+    }
+    async channelUpsert(channelId, channelConfig, options = {}) {
+        const { accountId, ...gatewayOptions } = options;
+        const config = await this.mutateConfig((next) => {
+            const channels = (next.channels ??= {});
+            const current = channels[channelId] && typeof channels[channelId] === 'object'
+                ? structuredClone(channels[channelId])
+                : {};
+            if (accountId) {
+                const accounts = current.accounts && typeof current.accounts === 'object'
+                    ? structuredClone(current.accounts)
+                    : {};
+                const currentAccount = accounts[accountId] && typeof accounts[accountId] === 'object'
+                    ? accounts[accountId]
+                    : {};
+                accounts[accountId] = deepMergeConfig(currentAccount, channelConfig);
+                current.accounts = accounts;
+                channels[channelId] = current;
+                return;
+            }
+            channels[channelId] = deepMergeConfig(current, channelConfig);
+        }, gatewayOptions);
+        const channel = config.channels?.[channelId] ?? {};
+        if (accountId) {
+            return channel.accounts?.[accountId] ?? {};
+        }
+        return channel;
+    }
+    async channelPatch(channelId, patch, options = {}) {
+        return await this.channelUpsert(channelId, patch, options);
+    }
+    async telegramUpsert(channelConfig, options = {}) {
+        return await this.channelUpsert('telegram', channelConfig, options);
+    }
+    async slackUpsert(channelConfig, options = {}) {
+        return await this.channelUpsert('slack', channelConfig, options);
+    }
+    async discordUpsert(channelConfig, options = {}) {
+        return await this.channelUpsert('discord', channelConfig, options);
+    }
+    async cronList(options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.cronList();
+        }
+        finally {
+            client.close();
+        }
+    }
 }
 export class Deployments {
     http;
@@ -366,8 +760,14 @@ export class Deployments {
     constructor(http, agentApiKey, agentApiBase, agentsWsUrl) {
         this.http = http;
         this.apiKey = agentApiKey || http.apiKey;
-        this.apiBase = resolveAgentsApiBase(agentApiBase || process.env.HYPERCLI_API_URL || AGENTS_API_BASE);
-        this.agentsWsUrl = agentsWsUrl ? normalizeAgentsWsUrl(agentsWsUrl) : defaultAgentsWsUrl(this.apiBase);
+        this.apiBase = resolveAgentsApiBase(agentApiBase || getAgentsApiBaseUrl());
+        this.agentsWsUrl = normalizeAgentsWsUrl(agentsWsUrl || getConfigValue('AGENTS_WS_URL') || defaultAgentsWsUrl(this.apiBase));
+    }
+    get agentApiKey() {
+        return this.apiKey;
+    }
+    get agentApiBase() {
+        return this.apiBase;
     }
     hydrateAgent(data) {
         const agent = data.openclaw_url || data.gateway_url
@@ -410,6 +810,14 @@ export class Deployments {
         agent.entrypoint = [...(config.entrypoint ?? [])];
         return agent;
     }
+    async createOpenClaw(options = {}) {
+        const effectiveOptions = { ...options };
+        if (options.routes === undefined) {
+            effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? {});
+        }
+        effectiveOptions.image = defaultOpenClawImage(options.image, options.config ?? {});
+        return this.create(effectiveOptions);
+    }
     async budget() {
         return this.http.get(`${DEPLOYMENTS_API_PREFIX}/budget`);
     }
@@ -428,6 +836,22 @@ export class Deployments {
         const data = await this.http.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}`);
         return this.hydrateAgent(data);
     }
+    async waitRunning(agentId, timeoutMs = 300_000, pollIntervalMs = 5_000) {
+        const deadline = Date.now() + timeoutMs;
+        let lastState = '';
+        while (Date.now() < deadline) {
+            const agent = await this.get(agentId);
+            lastState = String(agent.state || '');
+            if (lastState.toLowerCase() === 'running') {
+                return agent;
+            }
+            if (lastState.toLowerCase() === 'failed' || lastState.toLowerCase() === 'error') {
+                throw new Error(`Agent entered ${lastState} while waiting for RUNNING`);
+            }
+            await sleep(pollIntervalMs);
+        }
+        throw new Error(`Timed out waiting for agent ${agentId} to reach RUNNING (last=${lastState})`);
+    }
     async start(agentId, options = {}) {
         const { config, gatewayToken } = buildAgentConfig(options.config ?? {}, options);
         const body = { config };
@@ -443,6 +867,14 @@ export class Deployments {
         agent.entrypoint = [...(config.entrypoint ?? [])];
         return agent;
     }
+    async startOpenClaw(agentId, options = {}) {
+        const effectiveOptions = { ...options };
+        if (options.routes === undefined) {
+            effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? {});
+        }
+        effectiveOptions.image = defaultOpenClawImage(options.image, options.config ?? {});
+        return this.start(agentId, effectiveOptions);
+    }
     async stop(agentId) {
         const data = await this.http.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/stop`);
         return this.hydrateAgent(data);