@alfe.ai/openclaw 0.0.1

package/README.md

@@ -0,0 +1,51 @@
+# @alfe.ai/openclaw
+
+OpenClaw plugin that connects to the local Alfe gateway daemon via IPC.
+
+## What It Does
+
+- Connects to the Alfe gateway daemon at `~/.alfe/gateway.sock`
+- Registers OpenClaw capabilities (sessions, tools, plugins) with the daemon
+- Re-registers automatically on reconnect (daemon may restart)
+- Gracefully handles daemon being unavailable
+
+## Usage
+
+```js
+// openclaw.config.js
+export default {
+  plugins: {
+    entries: {
+      '@alfe.ai/openclaw': {},
+    },
+  },
+};
+```
+
+The daemon socket path defaults to `~/.alfe/gateway.sock`. Override via config
+(`socketPath`) or the `ALFE_GATEWAY_SOCKET` environment variable.
+
+## Setup
+
+```bash
+alfe setup   # Authenticate and install the gateway daemon
+```
+
+## Architecture
+
+```
+Alfe Cloud ←—— WebSocket ——→ alfe-gateway daemon (always-on)
+                                    ↕ IPC (~/.alfe/gateway.sock)
+                              @alfe.ai/openclaw (this plugin)
+                                    ↕
+                               OpenClaw process
+```
+
+The plugin is a thin IPC client. All heavy lifting (cloud connection, auth,
+protocol translation) is handled by the daemon.
+
+## Note
+
+Integration management (install, remove, configure, health) is handled by
+the gateway service directly — this plugin does not process integration
+commands.

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+import plugin from "./plugin.js";
+import { EventEmitter } from "node:events";
+
+//#region src/types.d.ts
+
+/**
+ * IPC protocol types for communication with the Alfe gateway daemon.
+ *
+ * These match the protocol defined in @alfe.ai/gateway (packages/gateway/src/protocol.ts).
+ * Duplicated here to avoid a direct dependency on the daemon package
+ * (the daemon is a standalone process, not a library dependency).
+ */
+interface IPCRequest {
+  type: 'req';
+  id: string;
+  method: string;
+  params: Record<string, unknown>;
+}
+interface IPCResponse {
+  id: string;
+  ok: boolean;
+  payload?: unknown;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+interface IPCEvent {
+  type: 'event';
+  event: string;
+  payload: unknown;
+}
+interface RegisterResult {
+  status: string;
+  daemonVersion: string;
+  protocolVersion: number;
+}
+declare function isIPCRequest(msg: unknown): msg is IPCRequest;
+declare function isIPCResponse(msg: unknown): msg is IPCResponse;
+declare function isIPCEvent(msg: unknown): msg is IPCEvent;
+/** IPC protocol version — must match daemon's PROTOCOL_VERSION */
+declare const PROTOCOL_VERSION = 1;
+//#endregion
+//#region src/ipc-client.d.ts
+
+declare class IPCClient extends EventEmitter {
+  private socket;
+  private socketPath;
+  private buffer;
+  private backoffMs;
+  private closed;
+  private _connected;
+  private reconnectTimer;
+  private pending;
+  private log;
+  constructor(socketPath: string);
+  get connected(): boolean;
+  /**
+   * Start the IPC connection with auto-reconnect.
+   */
+  start(): void;
+  /**
+   * Stop the IPC connection and all timers.
+   */
+  stop(): void;
+  /**
+   * Send a request to the daemon and wait for a response.
+   */
+  request(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<IPCResponse>;
+  /**
+   * Send a response to a daemon request.
+   * Used internally by the request event handler.
+   */
+  sendResponse(response: IPCResponse): void;
+  private doConnect;
+  private processBuffer;
+  private handleResponse;
+  private handleIncomingRequest;
+  private scheduleReconnect;
+  private clearReconnectTimer;
+}
+//#endregion
+//#region src/capability-reporter.d.ts
+/**
+ * Register this OpenClaw plugin with the daemon.
+ * Should be called on every (re)connect.
+ *
+ * @returns Registration result or null on failure
+ */
+declare function registerWithDaemon(client: IPCClient, log: {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+}): Promise<RegisterResult | null>;
+//#endregion
+//#region ../../packages-internal/agent-client/dist/types.d.ts
+interface BaseClientOptions {
+  url: string;
+  token: string;
+  clientId: string;
+  displayName: string;
+  version?: string;
+  instanceId?: string;
+  maxPayload?: number;
+  logger?: Logger;
+}
+interface Logger {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  debug(msg: string, ...args: unknown[]): void;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region ../../packages-internal/agent-client/dist/base-client.d.ts
+declare abstract class BaseAgentClient {
+  private ws;
+  private connected;
+  private closed;
+  private backoffMs;
+  private pending;
+  private readyResolve;
+  private readyReject;
+  private readyPromise;
+  protected readonly log: Logger;
+  protected readonly opts: BaseClientOptions;
+  protected readonly instanceId: string;
+  constructor(opts: BaseClientOptions);
+  get isConnected(): boolean;
+  start(): Promise<void>;
+  stop(): void;
+  request(method: string, params: Record<string, unknown>, opts?: {
+    expectFinal?: boolean;
+    timeoutMs?: number;
+  }): Promise<unknown>;
+  /** Perform protocol-specific handshake after WebSocket opens. */
+  protected abstract performHandshake(): Promise<void>;
+  /**
+   * Handle a protocol event. Base implementation handles 'chat' events.
+   * Subclasses should override and call super for unhandled events.
+   */
+  protected handleEvent(event: string, payload: unknown): void;
+  /** Called after successful handshake. Override to add service registration, health beacons, etc. */
+  protected onConnected(): void | Promise<void>;
+  /** Called when the connection is lost or stopped. Override to clean up timers, etc. */
+  protected onDisconnected(): void;
+  /** Close the underlying WebSocket connection. Useful for subclass timeout handling. */
+  protected closeConnection(code: number, reason: string): void;
+  /** Mark the client as connected and resolve the ready promise. */
+  protected setConnected(): void;
+  /** Resolve the ready promise (call after handshake + onConnected). */
+  protected resolveReady(): void;
+  /** Reject the ready promise (call on handshake failure). */
+  protected rejectReady(err: Error): void;
+  protected doConnect(): void;
+  private initiateHandshake;
+  private handleMessage;
+  private scheduleReconnect;
+  private flushPending;
+}
+//# sourceMappingURL=base-client.d.ts.map
+//#endregion
+//#region src/ws-client.d.ts
+interface OpenClawClientOptions extends BaseClientOptions {
+  /** Role for the connect handshake. Defaults to 'operator'. */
+  role?: string;
+  /** Scopes for the connect handshake. Defaults to ['operator.admin']. */
+  scopes?: string[];
+}
+declare class OpenClawGatewayAdapter extends BaseAgentClient {
+  private tickTimer;
+  private lastTick;
+  private handshakeInFlight;
+  private readonly openclawOpts;
+  constructor(opts: OpenClawClientOptions);
+  protected performHandshake(): Promise<void>;
+  protected handleEvent(event: string, payload: unknown): void;
+  protected onDisconnected(): void;
+  private startTickWatch;
+  /** Parse the standard agent response format into plain text. */
+  static parseAgentResponse(response: unknown): string;
+  /** Format a session key with the standard agent prefix. */
+  static formatSessionKey(agentId: string, sessionKey: string): string;
+}
+//#endregion
+export { IPCClient, IPCEvent, IPCRequest, IPCResponse, type OpenClawClientOptions, OpenClawGatewayAdapter, PROTOCOL_VERSION, RegisterResult, isIPCEvent, isIPCRequest, isIPCResponse, plugin, registerWithDaemon };