@artinet/cruiser 0.1.3 → 0.1.6

package/dist/openclaw/client.js

@@ -0,0 +1,236 @@
+import { v4 as uuidv4 } from 'uuid';
+import { createSignedDevicePayload, persistConnectAuth, readStoredAuth, resolveAuthFilePath, resolveOrCreateDeviceIdentity, } from './auth.js';
+export class OpenClawGatewayClient {
+    url;
+    authToken;
+    authPassword;
+    device;
+    deviceIdentity;
+    authFilePath;
+    scopes;
+    connectTimeoutMs;
+    clientId;
+    socket;
+    connectPromise;
+    isConnected = false;
+    connectRequestId;
+    pendingRequests = new Map();
+    constructor({ url, authToken, authPassword, agent, device, scopes, connectTimeoutMs, }) {
+        this.url = url;
+        this.authFilePath = resolveAuthFilePath(agent);
+        const storedAuth = readStoredAuth(this.authFilePath);
+        this.authToken = authToken ?? storedAuth?.tokens?.operator?.token;
+        this.authPassword = authPassword;
+        this.device = device;
+        this.deviceIdentity = resolveOrCreateDeviceIdentity({ agent, authFilePath: this.authFilePath });
+        const requestedScopes = scopes ?? [];
+        const requiredScopes = ['operator.read', 'operator.write'];
+        this.scopes = Array.from(new Set([...requiredScopes, ...requestedScopes]));
+        this.connectTimeoutMs = connectTimeoutMs;
+        this.clientId = uuidv4();
+    }
+    async ensureConnected() {
+        if (this.isConnected && this.socket?.readyState === WebSocket.OPEN) {
+            return;
+        }
+        if (this.connectPromise) {
+            return this.connectPromise;
+        }
+        this.connectPromise = new Promise((resolve, reject) => {
+            const socket = new WebSocket(this.url);
+            this.socket = socket;
+            const connectTimeout = setTimeout(() => {
+                reject(new Error('OpenClaw gateway connect timeout'));
+            }, this.connectTimeoutMs);
+            let challengeFallback;
+            function cleanupConnect() {
+                clearTimeout(connectTimeout);
+                if (challengeFallback) {
+                    clearTimeout(challengeFallback);
+                    challengeFallback = undefined;
+                }
+            }
+            socket.onopen = () => {
+                challengeFallback = setTimeout(() => {
+                    this.sendConnectRequest();
+                }, 1_000);
+            };
+            socket.onmessage = (event) => {
+                this.handleMessage(event.data, resolve, reject, cleanupConnect);
+            };
+            socket.onerror = () => {
+                cleanupConnect();
+                reject(new Error('OpenClaw gateway socket error'));
+            };
+            socket.onclose = () => {
+                this.isConnected = false;
+                this.connectPromise = undefined;
+                this.connectRequestId = undefined;
+                this.socket = undefined;
+                this.rejectAllPending(new Error('OpenClaw gateway socket closed'));
+            };
+        })
+            .catch((error) => {
+            this.connectPromise = undefined;
+            throw error;
+        })
+            .then(() => undefined);
+        return this.connectPromise;
+    }
+    async requestAgentRun({ message, agentId, sessionKey, timeoutMs, }) {
+        await this.ensureConnected();
+        const requestId = uuidv4();
+        const idempotencyKey = uuidv4();
+        const frame = {
+            type: 'req',
+            id: requestId,
+            method: 'agent',
+            params: {
+                message,
+                agentId,
+                sessionKey,
+                deliver: false,
+                idempotencyKey,
+            },
+        };
+        const responsePromise = new Promise((resolve, reject) => {
+            this.pendingRequests.set(requestId, {
+                expectFinal: true,
+                resolve,
+                reject,
+            });
+        });
+        this.sendFrame(frame);
+        const timeout = new Promise((_, reject) => {
+            setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                reject(new Error('OpenClaw gateway request timeout'));
+            }, timeoutMs);
+        });
+        const payload = (await Promise.race([responsePromise, timeout]));
+        if (payload.status && payload.status !== 'ok') {
+            const details = payload.error?.message ?? 'unknown error';
+            throw new Error(`OpenClaw agent failed: ${payload.status}: ${details}`);
+        }
+        return (payload.result ?? payload);
+    }
+    handleMessage(raw, connectResolve, connectReject, cleanupConnect) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        const frame = parsed;
+        if (frame.type === 'event' && frame.event === 'connect.challenge') {
+            this.sendConnectRequest(frame.payload?.nonce);
+            return;
+        }
+        if (frame.type !== 'res' || !frame.id) {
+            return;
+        }
+        const response = parsed;
+        if (frame.id === this.connectRequestId) {
+            cleanupConnect();
+            if (!response.ok) {
+                connectReject(new Error(response.error?.message ?? 'OpenClaw gateway connect rejected'));
+                return;
+            }
+            persistConnectAuth({
+                authFilePath: this.authFilePath,
+                payload: response.payload,
+                scopes: this.scopes,
+                deviceIdentity: this.deviceIdentity,
+            });
+            this.isConnected = true;
+            connectResolve();
+            return;
+        }
+        const pending = this.pendingRequests.get(frame.id);
+        if (!pending) {
+            return;
+        }
+        const payload = response.payload;
+        if (pending.expectFinal && payload?.status === 'accepted') {
+            return;
+        }
+        this.pendingRequests.delete(frame.id);
+        if (!response.ok) {
+            pending.reject(new Error(response.error?.message ?? 'OpenClaw gateway request failed'));
+            return;
+        }
+        pending.resolve(response.payload);
+    }
+    sendConnectRequest(nonce) {
+        if (this.connectRequestId) {
+            return;
+        }
+        const params = {
+            minProtocol: 3,
+            maxProtocol: 3,
+            client: {
+                id: 'cli',
+                displayName: 'cruiser-openclaw',
+                version: '0.1.5',
+                platform: 'node',
+                mode: 'cli',
+                instanceId: this.clientId,
+            },
+            role: 'operator',
+            scopes: this.scopes,
+            caps: [],
+            commands: [],
+            permissions: {},
+            locale: 'en-US',
+            userAgent: 'artinet-cruiser/openclaw',
+        };
+        if (this.authToken || this.authPassword) {
+            params.auth = {
+                ...(this.authToken ? { token: this.authToken } : {}),
+                ...(this.authPassword ? { password: this.authPassword } : {}),
+            };
+        }
+        const signedDevice = this.deviceIdentity
+            ? createSignedDevicePayload({
+                identity: this.deviceIdentity,
+                scopes: this.scopes,
+                token: this.authToken,
+                nonce,
+            })
+            : undefined;
+        if (signedDevice) {
+            params.device = signedDevice;
+        }
+        else if (this.device) {
+            const deviceNonce = nonce ?? this.device.nonce;
+            params.device = {
+                id: this.device.id,
+                publicKey: this.device.publicKey,
+                signature: this.device.signature,
+                signedAt: this.device.signedAt,
+                ...(deviceNonce ? { nonce: deviceNonce } : {}),
+            };
+        }
+        const requestId = uuidv4();
+        this.connectRequestId = requestId;
+        this.sendFrame({
+            type: 'req',
+            id: requestId,
+            method: 'connect',
+            params,
+        });
+    }
+    sendFrame(frame) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            throw new Error('OpenClaw gateway is not connected');
+        }
+        this.socket.send(JSON.stringify(frame));
+    }
+    rejectAllPending(error) {
+        for (const pending of this.pendingRequests.values()) {
+            pending.reject(error);
+        }
+        this.pendingRequests.clear();
+    }
+}

package/dist/openclaw/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview openclaw → artinet
+ *
+ * @module @artinet/cruiser/openclaw
+ * @description
+ * This adapter "docks" OpenClaw Gateway agents into artinet.
+ */
+import { Dock, Park } from '../corsair.js';
+import { type OpenClawAgent } from './utils.js';
+/**
+ * Configuration options for OpenClaw Gateway WebSocket calls.
+ */
+export type OpenClawDockOptions = {
+    /**
+     * Timeout for WS connect handshake in milliseconds.
+     */
+    connectTimeoutMs?: number;
+    /**
+     * Timeout for gateway request completion in milliseconds.
+     */
+    timeoutMs?: number;
+};
+/**
+ * @deprecated Use {@link OpenClawDockOptions} instead.
+ */
+export type OpenClawParkOptions = OpenClawDockOptions;
+/**
+ * Docks an OpenClaw Gateway agent into artinet.
+ *
+ * This adapter uses OpenClaw's native Gateway WebSocket protocol.
+ *
+ * OpenClaw docs:
+ * https://docs.openclaw.ai/gateway/protocol
+ */
+export declare const dock: Dock<OpenClawAgent, OpenClawDockOptions>;
+/**
+ * @deprecated Use {@link dock} instead.
+ */
+export declare const park: Park<OpenClawAgent, OpenClawDockOptions>;
+export type { OpenClawAgent } from './utils.js';

package/dist/openclaw/index.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview openclaw → artinet
+ *
+ * @module @artinet/cruiser/openclaw
+ * @description
+ * This adapter "docks" OpenClaw Gateway agents into artinet.
+ */
+import * as sdk from '@artinet/sdk';
+import { OpenClawGatewayClient } from './client.js';
+import { extractOpenClawText, getAgentCard } from './utils.js';
+/**
+ * Docks an OpenClaw Gateway agent into artinet.
+ *
+ * This adapter uses OpenClaw's native Gateway WebSocket protocol.
+ *
+ * OpenClaw docs:
+ * https://docs.openclaw.ai/gateway/protocol
+ */
+export const dock = async function dock(agent, card, options) {
+    const agentCard = await getAgentCard({ agent, card });
+    const gatewayUrl = (agent.gatewayUrl ?? 'ws://127.0.0.1:18789').replace(/\/+$/, '');
+    const agentId = agent.agentId ?? 'main';
+    const connectTimeoutMs = options?.connectTimeoutMs && options.connectTimeoutMs > 0 ? options.connectTimeoutMs : 10_000;
+    const requestTimeoutMs = options?.timeoutMs && options.timeoutMs > 0 ? options.timeoutMs : 60_000;
+    const gateway = new OpenClawGatewayClient({
+        url: gatewayUrl,
+        authToken: agent.authToken,
+        authPassword: agent.authPassword,
+        agent,
+        device: agent.device,
+        scopes: agent.scopes,
+        connectTimeoutMs,
+    });
+    await gateway.ensureConnected();
+    sdk.logger.debug(`OpenClaw[${agentCard.name}]:[card:${JSON.stringify(agentCard)}]`);
+    return sdk.cr8(agentCard).from(async function* (context) {
+        sdk.logger.debug(`OpenClaw[${agentCard.name}]:[context:${context.contextId}]: starting`);
+        const task = await context.getTask();
+        const text = sdk.extractTextContent(context.userMessage);
+        if (!text || text.trim().length === 0) {
+            yield sdk.describe.update.failed({
+                taskId: context.taskId,
+                contextId: context.contextId,
+                message: sdk.describe.message({
+                    taskId: context.taskId,
+                    contextId: context.contextId,
+                    parts: [sdk.describe.part.text('no input text detected')],
+                }),
+            });
+            return;
+        }
+        try {
+            const result = await gateway.requestAgentRun({
+                message: text,
+                agentId,
+                sessionKey: agent.sessionKey ?? context.contextId,
+                timeoutMs: requestTimeoutMs,
+            });
+            const responseText = extractOpenClawText(result);
+            const message = sdk.describe.message({
+                taskId: context.taskId,
+                contextId: context.contextId,
+                parts: [sdk.describe.part.text(responseText)],
+            });
+            yield sdk.describe.update.completed({
+                taskId: context.taskId,
+                contextId: context.contextId,
+                message,
+                metadata: {
+                    ...(task.metadata ?? {}),
+                    result,
+                },
+            });
+        }
+        catch (error) {
+            sdk.logger.error('OpenClaw execution failed', error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            yield sdk.describe.update.failed({
+                taskId: context.taskId,
+                contextId: context.contextId,
+                message: sdk.describe.message({
+                    taskId: context.taskId,
+                    contextId: context.contextId,
+                    parts: [sdk.describe.part.text(`error invoking OpenClaw agent: ${errorMessage}`)],
+                    metadata: {
+                        ...(task.metadata ?? {}),
+                        error: errorMessage,
+                    },
+                }),
+            });
+        }
+    });
+};
+/**
+ * @deprecated Use {@link dock} instead.
+ */
+export const park = dock;

package/dist/openclaw/utils.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview openclaw → artinet utils
+ *
+ * @module @artinet/cruiser/openclaw/utils
+ * @internal
+ */
+import * as sdk from "@artinet/sdk";
+export type OpenClawTool = {
+    name: string;
+    description?: string;
+};
+export type OpenClawDeviceIdentity = {
+    id: string;
+    publicKey: string;
+    privateKeyPem?: string;
+    signature?: string;
+    signedAt?: number;
+    nonce?: string;
+};
+export type OpenClawAgent = {
+    /**
+     * A2A card display name.
+     */
+    name: string;
+    /**
+     * Gateway base URL, e.g. http://127.0.0.1:18789
+     */
+    gatewayUrl?: string;
+    /**
+     * OpenClaw agent id. Defaults to "main".
+     */
+    agentId?: string;
+    /**
+     * Gateway auth token (token mode).
+     */
+    authToken?: string;
+    /**
+     * Gateway auth password (password mode).
+     */
+    authPassword?: string;
+    /**
+     * Optional fixed session key routed by OpenClaw gateway.
+     */
+    sessionKey?: string;
+    /**
+     * Optional explicit device identity for strict pairing setups.
+     */
+    device?: OpenClawDeviceIdentity;
+    /**
+     * Optional path where cruiser stores generated OpenClaw device auth state.
+     * Defaults to ~/artinet-openclaw.auth when auto device auth is enabled.
+     */
+    authFilePath?: string;
+    /**
+     * Enables automatic device identity bootstrap + persisted device token usage.
+     * Defaults to true.
+     */
+    autoDeviceAuth?: boolean;
+    /**
+     * Optional custom scopes passed during gateway connect.
+     */
+    scopes?: string[];
+    description?: string;
+    tools?: OpenClawTool[];
+};
+export declare function getAgentCard({ agent, card, }: {
+    agent: OpenClawAgent;
+    card?: sdk.A2A.AgentCardParams;
+}): Promise<sdk.A2A.AgentCard>;
+export declare function extractOpenClawText(result: OpenClawResult): string;
+export type OpenClawResult = Record<string, unknown>;

package/dist/openclaw/utils.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview openclaw → artinet utils
+ *
+ * @module @artinet/cruiser/openclaw/utils
+ * @internal
+ */
+import * as sdk from "@artinet/sdk";
+function createSkills(tools) {
+    return (tools?.map((tool) => ({
+        id: tool.name,
+        name: tool.name,
+        description: tool.description ?? `Tool: ${tool.name}`,
+        tags: ["tool"],
+    })) ?? []);
+}
+function createDescription(agent) {
+    if (agent.description && agent.description.trim().length > 0) {
+        return agent.description.trim();
+    }
+    return "An OpenClaw Gateway agent connected through @artinet/cruiser";
+}
+export async function getAgentCard({ agent, card, }) {
+    return sdk.describe.card({
+        name: agent.name,
+        ...(typeof card === "string" ? { name: card } : card),
+        description: createDescription(agent),
+        capabilities: {
+            streaming: true,
+            pushNotifications: true,
+            stateTransitionHistory: false,
+        },
+        defaultInputModes: ["text"],
+        defaultOutputModes: ["text"],
+        skills: createSkills(agent.tools),
+    });
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+export function extractOpenClawText(result) {
+    const record = asRecord(result);
+    if (!record) {
+        return "";
+    }
+    const payloads = record.payloads;
+    if (Array.isArray(payloads)) {
+        const text = payloads
+            .map((payload) => {
+            const entry = asRecord(payload);
+            if (typeof entry?.text === "string") {
+                return entry.text;
+            }
+            return "";
+        })
+            .filter((item) => item.length > 0)
+            .join("\n")
+            .trim();
+        if (text.length > 0) {
+            return text;
+        }
+    }
+    const choices = record.choices;
+    if (!Array.isArray(choices) || choices.length === 0) {
+        return "";
+    }
+    const firstChoice = asRecord(choices[0]);
+    const message = asRecord(firstChoice?.message);
+    const content = message?.content;
+    if (typeof content === "string") {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => {
+            if (typeof part === "string") {
+                return part;
+            }
+            const partRecord = asRecord(part);
+            if (typeof partRecord?.text === "string") {
+                return partRecord.text;
+            }
+            return JSON.stringify(part);
+        })
+            .join("\n");
+    }
+    return "";
+}