@greatlhd/ailo-endpoint-sdk 1.0.0

package/dist/endpoint-client.js

@@ -0,0 +1,669 @@
+import WebSocket from "ws";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import crypto from "crypto";
+import { EndpointError } from "./errors.js";
+import { ConsoleLogger } from "./logger.js";
+import { ConnectionFSM } from "./connection-state.js";
+import { toContentParts } from "./utils/index.js";
+const SDK_VERSION = "1.0.0";
+function resolveBlueprintPath(blueprint) {
+    if (!blueprint)
+        return "";
+    if (blueprint.startsWith("http://") || blueprint.startsWith("https://") || blueprint.startsWith("file://")) {
+        return blueprint;
+    }
+    return path.resolve(blueprint);
+}
+function jsonTextContent(value) {
+    const text = JSON.stringify(value);
+    if (text === undefined) {
+        throw new Error("structured payload must be JSON-serializable");
+    }
+    return [{ type: "text", text }];
+}
+const DEFAULT_OPTIONS = {
+    handshakeTimeout: 30_000,
+    heartbeatInterval: 30_000,
+    heartbeatTimeout: 10_000,
+    reconnectBaseDelay: 1_000,
+    reconnectMaxDelay: 60_000,
+    offlineBufferSize: 200,
+    logger: new ConsoleLogger('[endpoint]'),
+};
+export const RECONNECT_COOLDOWN_MS = 1000;
+export class EndpointClient {
+    ws = null;
+    cfg;
+    opts;
+    fsm;
+    reqId = 0;
+    pending = new Map();
+    heartbeatTimer = null;
+    pongTimer = null;
+    reconnectTimer = null;
+    reconnectAttempt = 0;
+    offlineBuffer = [];
+    offlineBufferMax;
+    toolRequestHandler = null;
+    intentHandler = null;
+    worldEnrichmentHandler = null;
+    streamHandler = null;
+    signalHandlers = new Map();
+    evictedHandler = null;
+    fsProbeMarker = null;
+    reconnectWaiters = [];
+    constructor(config, options) {
+        this.cfg = config;
+        this.opts = {
+            handshakeTimeout: options?.handshakeTimeout ?? DEFAULT_OPTIONS.handshakeTimeout,
+            heartbeatInterval: options?.heartbeatInterval ?? DEFAULT_OPTIONS.heartbeatInterval,
+            heartbeatTimeout: options?.heartbeatTimeout ?? DEFAULT_OPTIONS.heartbeatTimeout,
+            reconnectBaseDelay: options?.reconnectBaseDelay ?? DEFAULT_OPTIONS.reconnectBaseDelay,
+            reconnectMaxDelay: options?.reconnectMaxDelay ?? DEFAULT_OPTIONS.reconnectMaxDelay,
+            offlineBufferSize: options?.offlineBufferSize ?? DEFAULT_OPTIONS.offlineBufferSize,
+            logger: options?.logger ?? DEFAULT_OPTIONS.logger,
+        };
+        this.offlineBufferMax = config.offlineBufferSize ?? this.opts.offlineBufferSize;
+        this.fsm = new ConnectionFSM();
+        this.fsProbeMarker = this.writeFsProbeFile();
+        this.fsm.onStateChange((transition) => {
+            this.opts.logger.debug('state_change', {
+                from: transition.from,
+                to: transition.to,
+                reason: transition.reason,
+            });
+        });
+    }
+    get state() {
+        return this.fsm.state;
+    }
+    get isConnected() {
+        return this.fsm.isConnected;
+    }
+    onStateChange(listener) {
+        return this.fsm.onStateChange(listener);
+    }
+    setLogger(logger) {
+        this.opts.logger = logger;
+    }
+    async connect() {
+        if (!this.fsm.canTransitionTo('connecting')) {
+            throw EndpointError.notConnected();
+        }
+        this.fsm.transition('connecting', 'user initiated');
+        await this.dial();
+    }
+    close() {
+        if (this.fsm.state === 'disconnected')
+            return;
+        this.fsm.transition('closing', 'user close');
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.stopHeartbeat();
+        this.rejectAllPending(new Error("client closed"));
+        this.rejectReconnectWaiters(new Error("client closed"));
+        this.offlineBuffer.length = 0;
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        if (this.fsProbeMarker) {
+            try {
+                fs.unlinkSync(this.fsProbeMarker.path);
+            }
+            catch { }
+            this.fsProbeMarker = null;
+        }
+        this.fsm.forceTransition('disconnected', 'close complete');
+    }
+    async reconnect(skills, connectionOverrides, tools, blueprints) {
+        if (skills !== undefined)
+            this.cfg = { ...this.cfg, skills };
+        if (tools !== undefined)
+            this.cfg = { ...this.cfg, tools };
+        if (blueprints !== undefined)
+            this.cfg = { ...this.cfg, blueprints };
+        if (connectionOverrides) {
+            const { url, apiKey, endpointId } = connectionOverrides;
+            if (url !== undefined)
+                this.cfg = { ...this.cfg, url };
+            if (apiKey !== undefined)
+                this.cfg = { ...this.cfg, apiKey };
+            if (endpointId !== undefined)
+                this.cfg = { ...this.cfg, endpointId };
+        }
+        this.fsm.forceTransition('closing', 'reconnect initiated');
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.stopHeartbeat();
+        this.rejectAllPending(new Error("reconnecting"));
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this.fsm.forceTransition('disconnected', 'reconnect cleanup');
+        this.reconnectAttempt = 0;
+        if (connectionOverrides) {
+            await new Promise((r) => setTimeout(r, RECONNECT_COOLDOWN_MS));
+        }
+        await this.connect();
+    }
+    async update(params) {
+        await this.request("endpoint.update", params);
+    }
+    onToolRequest(handler) {
+        this.toolRequestHandler = handler;
+        return this;
+    }
+    onIntent(handler) {
+        this.intentHandler = handler;
+        return this;
+    }
+    onWorldEnrichment(handler) {
+        this.worldEnrichmentHandler = handler;
+        return this;
+    }
+    onStream(handler) {
+        this.streamHandler = handler;
+        return this;
+    }
+    onSignal(signal, handler) {
+        const list = this.signalHandlers.get(signal) ?? [];
+        list.push(handler);
+        this.signalHandlers.set(signal, list);
+        return this;
+    }
+    onEvicted(handler) {
+        this.evictedHandler = handler;
+        return this;
+    }
+    async accept(msg) {
+        if (!this.fsm.isConnected) {
+            if (this.fsm.state === 'closing' || this.fsm.state === 'disconnected' || this.offlineBufferMax <= 0) {
+                throw EndpointError.notConnected();
+            }
+            if (this.offlineBuffer.length >= this.offlineBufferMax) {
+                throw new Error(`offline buffer full (${this.offlineBufferMax})`);
+            }
+            this.offlineBuffer.push(msg);
+            return;
+        }
+        await this.acceptDirect(msg);
+    }
+    async toolResponse(payload) {
+        if (!this.fsm.isConnected) {
+            if (this.fsm.state !== 'closing' && this.fsm.state !== 'disconnected') {
+                await this.waitForConnection();
+            }
+        }
+        await this.request("tool_response", payload);
+    }
+    sendSignal(signal, data) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify({ type: "signal", id: signal, payload: data }));
+    }
+    dial() {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(this.cfg.url);
+            let settled = false;
+            const settle = (ok, err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (ok) {
+                    this.fsm.transition('connected', 'handshake complete');
+                    resolve();
+                }
+                else {
+                    this.fsm.transition('disconnected', 'dial failed');
+                    reject(err);
+                }
+            };
+            ws.on("open", async () => {
+                try {
+                    await this.handshake(ws);
+                    this.ws = ws;
+                    this.reconnectAttempt = 0;
+                    this.attachHandlers(ws);
+                    this.startHeartbeat();
+                    this.flushOfflineBuffer();
+                    this.resolveReconnectWaiters();
+                    settle(true);
+                }
+                catch (err) {
+                    ws.close();
+                    settle(false, err);
+                }
+            });
+            ws.on("error", (err) => {
+                this.opts.logger.error('ws_error', { error: err.message });
+                settle(false, EndpointError.network('WebSocket error', err));
+            });
+            ws.on("close", () => settle(false, EndpointError.network("closed before handshake")));
+        });
+    }
+    handshake(ws) {
+        const id = `connect-${++this.reqId}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                ws.off("message", handler);
+                this.opts.logger.warn('handshake_timeout', { timeout: this.opts.handshakeTimeout });
+                reject(EndpointError.timeout("handshake timeout"));
+            }, this.opts.handshakeTimeout);
+            const handler = (raw) => {
+                const frame = JSON.parse(raw.toString("utf-8"));
+                if (frame.type === "res" && frame.id === id) {
+                    clearTimeout(timer);
+                    ws.off("message", handler);
+                    if (frame.ok) {
+                        resolve();
+                    }
+                    else {
+                        const errMsg = frame.error?.message ?? "connect rejected";
+                        this.opts.logger.error('handshake_failed', { error: errMsg });
+                        if (frame.error?.code === 'AUTH_FAILED') {
+                            reject(EndpointError.auth(errMsg));
+                        }
+                        else {
+                            reject(EndpointError.handshakeFailed(errMsg));
+                        }
+                    }
+                }
+            };
+            ws.on("message", handler);
+            const connectParams = {
+                role: "endpoint",
+                apiKey: this.cfg.apiKey,
+                endpointId: this.cfg.endpointId,
+                caps: this.cfg.caps,
+                sdkVersion: SDK_VERSION,
+            };
+            if (this.cfg.instructions)
+                connectParams.instructions = this.cfg.instructions;
+            if (this.cfg.tools && this.cfg.tools.length > 0)
+                connectParams.tools = this.cfg.tools;
+            if (this.cfg.blueprints && this.cfg.blueprints.length > 0) {
+                connectParams.blueprints = this.cfg.blueprints.map(resolveBlueprintPath);
+            }
+            if (this.cfg.skills && this.cfg.skills.length > 0)
+                connectParams.skills = this.cfg.skills;
+            if (this.fsProbeMarker)
+                connectParams.fsProbe = this.fsProbeMarker;
+            ws.send(JSON.stringify({ type: "req", id, method: "connect", params: connectParams }));
+        });
+    }
+    attachHandlers(ws) {
+        ws.on("message", (raw) => {
+            const frame = JSON.parse(raw.toString("utf-8"));
+            if (frame.type === "res" && frame.id) {
+                const req = this.pending.get(frame.id);
+                if (!req)
+                    return;
+                this.pending.delete(frame.id);
+                frame.ok
+                    ? req.resolve(frame.payload ?? {})
+                    : req.reject(new Error(frame.error?.message ?? "request failed"));
+                return;
+            }
+            if (frame.type === "event") {
+                this.handleEvent(frame);
+                return;
+            }
+            if (frame.type === "signal" && frame.id) {
+                const handlers = this.signalHandlers.get(frame.id);
+                if (handlers) {
+                    for (const h of handlers)
+                        h(frame.id, frame.payload);
+                }
+                return;
+            }
+        });
+        ws.on("close", (code, reason) => {
+            const isEvicted = code === 1001 && reason?.toString("utf-8").includes("replaced");
+            if (isEvicted) {
+                this.opts.logger.warn('evicted', { code, reason: reason.toString() });
+                this.fsm.forceTransition('disconnected', 'evicted');
+                this.rejectReconnectWaiters(EndpointError.evicted());
+                this.evictedHandler?.();
+                return;
+            }
+            if (ws !== this.ws)
+                return;
+            this.onDisconnect();
+        });
+        ws.on("pong", () => {
+            if (this.pongTimer) {
+                clearTimeout(this.pongTimer);
+                this.pongTimer = null;
+            }
+        });
+    }
+    handleEvent(frame) {
+        switch (frame.event) {
+            case "tool_request": {
+                const payload = frame.payload;
+                if (!this.toolRequestHandler || !payload?.id)
+                    return;
+                void this.toolRequestHandler(payload)
+                    .then((result) => {
+                    return this.toolResponse({
+                        id: payload.id,
+                        success: true,
+                        content: toContentParts(result),
+                    });
+                })
+                    .catch((err) => this.toolResponse({ id: payload.id, success: false, error: err.message }))
+                    .catch((sendErr) => {
+                    this.opts.logger.error('tool_response_failed', {
+                        toolId: payload.id,
+                        error: sendErr.message,
+                    });
+                });
+                break;
+            }
+            case "intent": {
+                const payload = frame.payload;
+                this.intentHandler?.(payload);
+                break;
+            }
+            case "world_enrichment": {
+                const payload = frame.payload;
+                this.worldEnrichmentHandler?.(payload);
+                break;
+            }
+            case "stream": {
+                const payload = frame.payload;
+                this.streamHandler?.(payload);
+                break;
+            }
+            case "file_fetch": {
+                const reqId = frame.id;
+                if (!reqId)
+                    break;
+                const payload = frame.payload;
+                void this.handleFileFetch(reqId, payload);
+                break;
+            }
+            case "dir_list": {
+                const reqId = frame.id;
+                if (!reqId)
+                    break;
+                const payload = frame.payload;
+                void this.handleDirList(reqId, payload);
+                break;
+            }
+            case "file_push": {
+                const reqId = frame.id;
+                if (!reqId)
+                    break;
+                const payload = frame.payload;
+                void this.handleFilePush(reqId, payload);
+                break;
+            }
+            case "fs_probe": {
+                const reqId = frame.id;
+                if (!reqId)
+                    break;
+                const payload = frame.payload;
+                void this.handleFsProbe(reqId, payload);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    request(method, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+                reject(EndpointError.notConnected());
+                return;
+            }
+            const id = `${method}-${++this.reqId}`;
+            this.pending.set(id, { resolve: resolve, reject });
+            this.ws.send(JSON.stringify({ type: "req", id, method, params }));
+        });
+    }
+    async acceptDirect(msg) {
+        const params = {
+            content: msg.content,
+            contextTags: msg.contextTags,
+        };
+        await this.request("endpoint.accept", params);
+    }
+    flushOfflineBuffer() {
+        if (this.offlineBuffer.length === 0)
+            return;
+        const buffered = this.offlineBuffer.splice(0);
+        this.opts.logger.info('flushing_offline_buffer', { count: buffered.length });
+        for (const msg of buffered) {
+            this.acceptDirect(msg).catch((err) => this.opts.logger.error('replay_failed', { error: err.message }));
+        }
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+                return;
+            this.ws.ping();
+            this.pongTimer = setTimeout(() => {
+                this.opts.logger.error('pong_timeout', { timeout: this.opts.heartbeatTimeout });
+                this.ws?.terminate();
+            }, this.opts.heartbeatTimeout);
+        }, this.opts.heartbeatInterval);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.pongTimer) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+    }
+    waitForConnection() {
+        if (this.fsm.isConnected)
+            return Promise.resolve();
+        if (this.fsm.state === 'closing' || this.fsm.state === 'disconnected') {
+            return Promise.reject(EndpointError.notConnected());
+        }
+        return new Promise((resolve, reject) => {
+            this.reconnectWaiters.push({ resolve, reject });
+        });
+    }
+    resolveReconnectWaiters() {
+        const waiters = this.reconnectWaiters.splice(0);
+        for (const w of waiters)
+            w.resolve();
+    }
+    rejectReconnectWaiters(err) {
+        const waiters = this.reconnectWaiters.splice(0);
+        for (const w of waiters)
+            w.reject(err);
+    }
+    onDisconnect() {
+        this.ws = null;
+        this.stopHeartbeat();
+        this.rejectAllPending(new Error("disconnected"));
+        if (this.fsm.state !== 'closing' && this.fsm.state !== 'disconnected') {
+            this.fsm.transition('reconnecting', 'unexpected disconnect');
+            this.scheduleReconnect();
+        }
+    }
+    rejectAllPending(err) {
+        for (const [, req] of this.pending) {
+            req.reject(err);
+        }
+        this.pending.clear();
+    }
+    async handleFileFetch(reqId, payload) {
+        try {
+            const localPath = payload.path;
+            if (!path.isAbsolute(localPath)) {
+                await this.toolResponse({ id: reqId, success: false, error: `path must be absolute, got: "${localPath}"` });
+                return;
+            }
+            if (!fs.existsSync(localPath)) {
+                await this.toolResponse({ id: reqId, success: false, error: `file not found: ${localPath}` });
+                return;
+            }
+            const fileBuffer = fs.readFileSync(localPath);
+            const fileName = path.basename(localPath);
+            const form = new FormData();
+            form.append("file", new Blob([fileBuffer]), fileName);
+            const res = await fetch(payload.upload_url, {
+                method: "POST",
+                body: form,
+            });
+            if (!res.ok) {
+                await this.toolResponse({ id: reqId, success: false, error: `upload failed: ${res.status}` });
+                return;
+            }
+            const result = await res.json();
+            await this.toolResponse({ id: reqId, success: true, content: jsonTextContent(result) });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.opts.logger.error('file_fetch_error', { error: msg });
+            await this.toolResponse({ id: reqId, success: false, error: msg }).catch(() => { });
+        }
+    }
+    async handleDirList(reqId, payload) {
+        try {
+            const dirPath = payload.path;
+            if (!path.isAbsolute(dirPath)) {
+                await this.toolResponse({ id: reqId, success: false, error: `path must be absolute, got: "${dirPath}"` });
+                return;
+            }
+            if (!fs.existsSync(dirPath)) {
+                await this.toolResponse({ id: reqId, success: false, error: `directory not found: ${dirPath}` });
+                return;
+            }
+            const stat = fs.statSync(dirPath);
+            if (!stat.isDirectory()) {
+                await this.toolResponse({ id: reqId, success: false, error: `not a directory: ${dirPath}` });
+                return;
+            }
+            const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+            const result = {
+                entries: entries
+                    .filter((e) => e.isFile() || e.isDirectory())
+                    .map((e) => {
+                    const fullPath = path.join(dirPath, e.name);
+                    try {
+                        const s = fs.statSync(fullPath);
+                        return {
+                            name: e.name,
+                            type: e.isDirectory() ? "dir" : "file",
+                            size: s.size,
+                            mtime: s.mtime.toISOString(),
+                        };
+                    }
+                    catch {
+                        return { name: e.name, type: e.isDirectory() ? "dir" : "file", size: 0 };
+                    }
+                }),
+            };
+            await this.toolResponse({ id: reqId, success: true, content: jsonTextContent(result) });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.opts.logger.error('dir_list_error', { error: msg });
+            await this.toolResponse({ id: reqId, success: false, error: msg }).catch(() => { });
+        }
+    }
+    async handleFilePush(reqId, payload) {
+        try {
+            const targetPath = payload.target_path;
+            if (!path.isAbsolute(targetPath)) {
+                await this.toolResponse({ id: reqId, success: false, error: `target_path must be absolute, got: "${targetPath}"` });
+                return;
+            }
+            const dir = path.dirname(targetPath);
+            fs.mkdirSync(dir, { recursive: true });
+            if (payload.local_source) {
+                if (!path.isAbsolute(payload.local_source)) {
+                    await this.toolResponse({ id: reqId, success: false, error: `local_source must be absolute, got: "${payload.local_source}"` });
+                    return;
+                }
+                fs.copyFileSync(payload.local_source, targetPath);
+                const stat = fs.statSync(targetPath);
+                await this.toolResponse({ id: reqId, success: true, content: jsonTextContent({ size: stat.size }) });
+                return;
+            }
+            if (!payload.url) {
+                await this.toolResponse({ id: reqId, success: false, error: "neither url nor local_source provided" });
+                return;
+            }
+            const res = await fetch(payload.url);
+            if (!res.ok) {
+                await this.toolResponse({ id: reqId, success: false, error: `download failed: ${res.status}` });
+                return;
+            }
+            const buffer = Buffer.from(await res.arrayBuffer());
+            fs.writeFileSync(targetPath, buffer);
+            await this.toolResponse({ id: reqId, success: true, content: jsonTextContent({ size: buffer.length }) });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.opts.logger.error('file_push_error', { error: msg });
+            await this.toolResponse({ id: reqId, success: false, error: msg }).catch(() => { });
+        }
+    }
+    async handleFsProbe(reqId, payload) {
+        try {
+            if (!path.isAbsolute(payload.path)) {
+                await this.toolResponse({ id: reqId, success: true, content: jsonTextContent({ found: false, content: "" }) });
+                return;
+            }
+            if (fs.existsSync(payload.path)) {
+                const content = fs.readFileSync(payload.path, "utf-8");
+                await this.toolResponse({ id: reqId, success: true, content: jsonTextContent({ found: true, content }) });
+            }
+            else {
+                await this.toolResponse({ id: reqId, success: true, content: jsonTextContent({ found: false, content: "" }) });
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            await this.toolResponse({ id: reqId, success: true, content: jsonTextContent({ found: false, content: "" }) }).catch(() => { });
+            this.opts.logger.error('fs_probe_error', { error: msg });
+        }
+    }
+    writeFsProbeFile() {
+        try {
+            const nonce = crypto.randomUUID();
+            const probePath = path.join(os.tmpdir(), `ailo-ep-${this.cfg.endpointId}.probe`);
+            fs.writeFileSync(probePath, nonce, "utf-8");
+            return { path: probePath, nonce };
+        }
+        catch (err) {
+            this.opts.logger.error('fs_probe_write_failed', { error: String(err) });
+            return null;
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        const delay = Math.min(this.opts.reconnectBaseDelay * 2 ** this.reconnectAttempt, this.opts.reconnectMaxDelay);
+        this.reconnectAttempt++;
+        this.opts.logger.info('scheduling_reconnect', { delay, attempt: this.reconnectAttempt });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.fsm.transition('connecting', 'reconnect attempt');
+            this.dial().catch((err) => {
+                this.opts.logger.error('reconnect_failed', { error: err.message });
+                this.fsm.transition('reconnecting', 'reconnect failed');
+                this.scheduleReconnect();
+            });
+        }, delay);
+    }
+}
+//# sourceMappingURL=endpoint-client.js.map