@orgloop/agentctl 1.0.1 → 1.2.0

package/dist/adapters/openclaw.d.ts

@@ -1,7 +1,19 @@
 import type { AgentAdapter, AgentSession, LaunchOpts, LifecycleEvent, ListOpts, PeekOpts, StopOpts } from "../core/types.js";
+export interface DeviceIdentity {
+    deviceId: string;
+    publicKeyPem: string;
+    privateKeyPem: string;
+}
+/**
+ * Load or create agentctl's device identity. Uses its own key pair
+ * (separate from OpenClaw's identity at ~/.openclaw/identity/device.json).
+ */
+export declare function loadOrCreateDeviceIdentity(filePath?: string): DeviceIdentity;
 export interface OpenClawAdapterOpts {
     baseUrl?: string;
     authToken?: string;
+    /** Device identity for scoped access. Auto-created if not provided. */
+    deviceIdentity?: DeviceIdentity | null;
     /** Override for testing — replaces the real WebSocket RPC call */
     rpcCall?: RpcCallFn;
 }
@@ -53,17 +65,63 @@ export interface SessionsPreviewResult {
     ts: number;
     previews: SessionsPreviewEntry[];
 }
+/**
+ * Build the device auth payload string for signing.
+ * Format: v2|deviceId|clientId|clientMode|role|scopes|signedAtMs|token|nonce
+ */
+export declare function buildDeviceAuthPayload(params: {
+    deviceId: string;
+    clientId: string;
+    clientMode: string;
+    role: string;
+    scopes: string[];
+    signedAtMs: number;
+    token: string | null;
+    nonce: string | null;
+}): string;
+/**
+ * Build the full `connect` handshake params sent to the gateway.
+ * Includes device auth for scoped access when identity is available.
+ * Exported so tests can verify the protocol constants.
+ */
+export declare function buildConnectParams(authToken: string, deviceIdentity?: DeviceIdentity | null, nonce?: string | null): {
+    minProtocol: number;
+    maxProtocol: number;
+    client: {
+        id: "cli";
+        version: string;
+        platform: NodeJS.Platform;
+        mode: "cli";
+    };
+    role: "operator";
+    scopes: string[];
+    auth: {
+        token: string | null;
+    };
+    device: {
+        id: string;
+        publicKey: string;
+        signature: string;
+        signedAt: number;
+        nonce: string | undefined;
+    } | undefined;
+};
 /**
  * OpenClaw adapter — reads session data from the OpenClaw gateway via
  * its WebSocket RPC protocol. Falls back gracefully when the gateway
  * is unreachable.
+ *
+ * Uses Ed25519 device auth for scoped access (operator.read).
+ * Device identity is auto-created at ~/.agentctl/identity/device.json.
  */
 export declare class OpenClawAdapter implements AgentAdapter {
     readonly id = "openclaw";
     private readonly baseUrl;
     private readonly authToken;
+    private readonly deviceIdentity;
     private readonly rpcCall;
     constructor(opts?: OpenClawAdapterOpts);
+    private tryLoadDeviceIdentity;
     list(opts?: ListOpts): Promise<AgentSession[]>;
     peek(sessionId: string, opts?: PeekOpts): Promise<string>;
     status(sessionId: string): Promise<AgentSession>;
@@ -71,18 +129,11 @@ export declare class OpenClawAdapter implements AgentAdapter {
     stop(_sessionId: string, _opts?: StopOpts): Promise<void>;
     resume(sessionId: string, _message: string): Promise<void>;
     events(): AsyncIterable<LifecycleEvent>;
-    /**
-     * Map a gateway session row to the standard AgentSession interface.
-     * OpenClaw sessions with a recent updatedAt are considered "running".
-     */
     private mapRowToSession;
-    /**
-     * Resolve a sessionId (or prefix) to a gateway session key.
-     */
     private resolveKey;
     /**
-     * Real WebSocket RPC call — connects, performs handshake, sends one
-     * request, reads the response, then disconnects.
+     * Real WebSocket RPC call — connects, performs handshake with device auth,
+     * sends one request, reads the response, then disconnects.
      */
     private defaultRpcCall;
 }

package/dist/adapters/openclaw.js

@@ -1,25 +1,206 @@
-import { randomUUID } from "node:crypto";
+import crypto, { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
 const DEFAULT_BASE_URL = "http://127.0.0.1:18789";
+const _require = createRequire(import.meta.url);
+const PKG_VERSION = _require("../../package.json").version;
+// --- Device identity helpers ---
+/** Ed25519 SPKI DER prefix (RFC 8410) — strip to get raw 32-byte public key */
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+function base64UrlEncode(buf) {
+    return buf
+        .toString("base64")
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/g, "");
+}
+function derivePublicKeyRaw(publicKeyPem) {
+    const spki = crypto
+        .createPublicKey(publicKeyPem)
+        .export({ type: "spki", format: "der" });
+    if (spki.length === ED25519_SPKI_PREFIX.length + 32 &&
+        spki.subarray(0, ED25519_SPKI_PREFIX.length).equals(ED25519_SPKI_PREFIX)) {
+        return spki.subarray(ED25519_SPKI_PREFIX.length);
+    }
+    return spki;
+}
+function fingerprintPublicKey(publicKeyPem) {
+    const raw = derivePublicKeyRaw(publicKeyPem);
+    return crypto.createHash("sha256").update(raw).digest("hex");
+}
+function publicKeyRawBase64Url(publicKeyPem) {
+    return base64UrlEncode(derivePublicKeyRaw(publicKeyPem));
+}
+function signPayload(privateKeyPem, payload) {
+    const key = crypto.createPrivateKey(privateKeyPem);
+    return base64UrlEncode(Buffer.from(crypto.sign(null, Buffer.from(payload, "utf8"), key)));
+}
+function generateDeviceIdentity() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+    const publicKeyPem = publicKey
+        .export({ type: "spki", format: "pem" })
+        .toString();
+    const privateKeyPem = privateKey
+        .export({ type: "pkcs8", format: "pem" })
+        .toString();
+    return {
+        deviceId: fingerprintPublicKey(publicKeyPem),
+        publicKeyPem,
+        privateKeyPem,
+    };
+}
+/** Default identity path: ~/.agentctl/identity/device.json */
+function resolveDefaultIdentityPath() {
+    return path.join(os.homedir(), ".agentctl", "identity", "device.json");
+}
+/**
+ * Load or create agentctl's device identity. Uses its own key pair
+ * (separate from OpenClaw's identity at ~/.openclaw/identity/device.json).
+ */
+export function loadOrCreateDeviceIdentity(filePath = resolveDefaultIdentityPath()) {
+    try {
+        if (fs.existsSync(filePath)) {
+            const raw = fs.readFileSync(filePath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed?.version === 1 &&
+                typeof parsed.deviceId === "string" &&
+                typeof parsed.publicKeyPem === "string" &&
+                typeof parsed.privateKeyPem === "string") {
+                // Re-derive deviceId from public key in case it drifted
+                const derivedId = fingerprintPublicKey(parsed.publicKeyPem);
+                return {
+                    deviceId: derivedId,
+                    publicKeyPem: parsed.publicKeyPem,
+                    privateKeyPem: parsed.privateKeyPem,
+                };
+            }
+        }
+    }
+    catch {
+        // Fall through to generate new identity
+    }
+    const identity = generateDeviceIdentity();
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const stored = {
+        version: 1,
+        deviceId: identity.deviceId,
+        publicKeyPem: identity.publicKeyPem,
+        privateKeyPem: identity.privateKeyPem,
+        createdAtMs: Date.now(),
+    };
+    fs.writeFileSync(filePath, `${JSON.stringify(stored, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    return identity;
+}
+/**
+ * Build the device auth payload string for signing.
+ * Format: v2|deviceId|clientId|clientMode|role|scopes|signedAtMs|token|nonce
+ */
+export function buildDeviceAuthPayload(params) {
+    const version = params.nonce ? "v2" : "v1";
+    const base = [
+        version,
+        params.deviceId,
+        params.clientId,
+        params.clientMode,
+        params.role,
+        params.scopes.join(","),
+        String(params.signedAtMs),
+        params.token ?? "",
+    ];
+    if (version === "v2")
+        base.push(params.nonce ?? "");
+    return base.join("|");
+}
+/**
+ * Build the full `connect` handshake params sent to the gateway.
+ * Includes device auth for scoped access when identity is available.
+ * Exported so tests can verify the protocol constants.
+ */
+export function buildConnectParams(authToken, deviceIdentity, nonce) {
+    const scopes = ["operator.read"];
+    const signedAtMs = Date.now();
+    const device = deviceIdentity
+        ? (() => {
+            const payload = buildDeviceAuthPayload({
+                deviceId: deviceIdentity.deviceId,
+                clientId: "cli",
+                clientMode: "cli",
+                role: "operator",
+                scopes,
+                signedAtMs,
+                token: authToken || null,
+                nonce: nonce ?? null,
+            });
+            return {
+                id: deviceIdentity.deviceId,
+                publicKey: publicKeyRawBase64Url(deviceIdentity.publicKeyPem),
+                signature: signPayload(deviceIdentity.privateKeyPem, payload),
+                signedAt: signedAtMs,
+                nonce: nonce ?? undefined,
+            };
+        })()
+        : undefined;
+    return {
+        minProtocol: 1,
+        maxProtocol: 3,
+        client: {
+            id: "cli",
+            version: PKG_VERSION,
+            platform: process.platform,
+            mode: "cli",
+        },
+        role: "operator",
+        scopes,
+        auth: { token: authToken || null },
+        device,
+    };
+}
 /**
  * OpenClaw adapter — reads session data from the OpenClaw gateway via
  * its WebSocket RPC protocol. Falls back gracefully when the gateway
  * is unreachable.
+ *
+ * Uses Ed25519 device auth for scoped access (operator.read).
+ * Device identity is auto-created at ~/.agentctl/identity/device.json.
  */
 export class OpenClawAdapter {
     id = "openclaw";
     baseUrl;
     authToken;
+    deviceIdentity;
     rpcCall;
     constructor(opts) {
         this.baseUrl = opts?.baseUrl || DEFAULT_BASE_URL;
         this.authToken =
-            opts?.authToken || process.env.OPENCLAW_WEBHOOK_TOKEN || "";
+            opts?.authToken ||
+                process.env.OPENCLAW_GATEWAY_TOKEN ||
+                process.env.OPENCLAW_WEBHOOK_TOKEN ||
+                "";
+        // Device identity: explicit null disables it (for tests), undefined = auto-create
+        this.deviceIdentity =
+            opts?.deviceIdentity === null
+                ? null
+                : (opts?.deviceIdentity ?? this.tryLoadDeviceIdentity());
         this.rpcCall = opts?.rpcCall || this.defaultRpcCall.bind(this);
     }
+    tryLoadDeviceIdentity() {
+        try {
+            return loadOrCreateDeviceIdentity();
+        }
+        catch {
+            // Don't break adapter construction if identity can't be created
+            return null;
+        }
+    }
     async list(opts) {
         if (!this.authToken) {
-            console.warn("Warning: OPENCLAW_WEBHOOK_TOKEN is not set — OpenClaw adapter cannot authenticate. " +
-                "Set this environment variable to connect to the gateway.");
+            console.warn("Warning: OPENCLAW_GATEWAY_TOKEN is not set — OpenClaw adapter cannot authenticate. " +
+                "Set OPENCLAW_GATEWAY_TOKEN (or OPENCLAW_WEBHOOK_TOKEN) to connect to the gateway.");
             return [];
         }
         let result;
@@ -33,7 +214,7 @@ export class OpenClawAdapter {
             const msg = err?.message || "unknown error";
             if (msg.includes("auth") || msg.includes("Auth")) {
                 console.warn(`Warning: OpenClaw gateway authentication failed: ${msg}. ` +
-                    "Check that OPENCLAW_WEBHOOK_TOKEN is valid.");
+                    "Check that OPENCLAW_GATEWAY_TOKEN (or OPENCLAW_WEBHOOK_TOKEN) is valid.");
             }
             else {
                 console.warn(`Warning: OpenClaw gateway unreachable (${msg}). ` +
@@ -81,7 +262,7 @@ export class OpenClawAdapter {
     }
     async status(sessionId) {
         if (!this.authToken) {
-            throw new Error("OPENCLAW_WEBHOOK_TOKEN is not set — cannot connect to OpenClaw gateway");
+            throw new Error("OPENCLAW_GATEWAY_TOKEN is not set — cannot connect to OpenClaw gateway");
         }
         let result;
         try {
@@ -108,14 +289,10 @@ export class OpenClawAdapter {
         throw new Error("OpenClaw sessions cannot be stopped via agentctl");
     }
     async resume(sessionId, _message) {
-        // OpenClaw sessions receive messages through their configured channels,
-        // not through a direct CLI interface.
         throw new Error(`Cannot resume OpenClaw session ${sessionId} — use the gateway UI or configured channel`);
     }
     async *events() {
-        // Poll-based diffing (same pattern as claude-code)
         let knownSessions = new Map();
-        // Initial snapshot
         const initial = await this.list({ all: true });
         for (const s of initial) {
             knownSessions.set(s.id, s);
@@ -164,15 +341,10 @@ export class OpenClawAdapter {
         }
     }
     // --- Private helpers ---
-    /**
-     * Map a gateway session row to the standard AgentSession interface.
-     * OpenClaw sessions with a recent updatedAt are considered "running".
-     */
     mapRowToSession(row, defaults) {
         const now = Date.now();
         const updatedAt = row.updatedAt ?? 0;
         const ageMs = now - updatedAt;
-        // Consider "running" if updated in the last 5 minutes
         const isActive = updatedAt > 0 && ageMs < 5 * 60 * 1000;
         const model = row.model || defaults.model || undefined;
         const input = row.inputTokens ?? 0;
@@ -196,12 +368,9 @@ export class OpenClawAdapter {
             },
         };
     }
-    /**
-     * Resolve a sessionId (or prefix) to a gateway session key.
-     */
     async resolveKey(sessionId) {
         if (!this.authToken) {
-            throw new Error("OPENCLAW_WEBHOOK_TOKEN is not set — cannot connect to OpenClaw gateway");
+            throw new Error("OPENCLAW_GATEWAY_TOKEN is not set — cannot connect to OpenClaw gateway");
         }
         let result;
         try {
@@ -219,13 +388,11 @@ export class OpenClawAdapter {
         return row?.key ?? null;
     }
     /**
-     * Real WebSocket RPC call — connects, performs handshake, sends one
-     * request, reads the response, then disconnects.
+     * Real WebSocket RPC call — connects, performs handshake with device auth,
+     * sends one request, reads the response, then disconnects.
      */
     async defaultRpcCall(method, params) {
-        // Dynamic import so tests can inject a mock without loading ws
         const { WebSocket } = await import("ws").catch(() => {
-            // Fall back to globalThis.WebSocket (available in Node 22+)
             return { WebSocket: globalThis.WebSocket };
         });
         const wsUrl = this.baseUrl.replace(/^http/, "ws");
@@ -244,25 +411,16 @@ export class OpenClawAdapter {
                 try {
                     const raw = typeof event.data === "string" ? event.data : String(event.data);
                     const frame = JSON.parse(raw);
-                    // Step 1: Receive challenge, send connect
+                    // Step 1: Receive challenge (with nonce), send connect with device auth
                     if (frame.type === "event" && frame.event === "connect.challenge") {
+                        const nonce = frame.payload && typeof frame.payload.nonce === "string"
+                            ? frame.payload.nonce
+                            : null;
                         ws.send(JSON.stringify({
                             type: "req",
                             id: randomUUID(),
                             method: "connect",
-                            params: {
-                                minProtocol: 1,
-                                maxProtocol: 1,
-                                client: {
-                                    id: "agentctl",
-                                    version: "0.1.0",
-                                    platform: process.platform,
-                                    mode: "cli",
-                                },
-                                role: "operator",
-                                scopes: ["operator.read"],
-                                auth: { token: this.authToken || null },
-                            },
+                            params: buildConnectParams(this.authToken, this.deviceIdentity, nonce),
                         }));
                         return;
                     }
@@ -306,7 +464,6 @@ export class OpenClawAdapter {
             };
             ws.onclose = () => {
                 clearTimeout(timeout);
-                // Only reject if we haven't resolved yet
             };
         });
     }

package/dist/adapters/opencode.d.ts

@@ -0,0 +1,143 @@
+import type { AgentAdapter, AgentSession, LaunchOpts, LifecycleEvent, ListOpts, PeekOpts, StopOpts } from "../core/types.js";
+export interface PidInfo {
+    pid: number;
+    cwd: string;
+    args: string;
+    /** Process start time from `ps -p <pid> -o lstart=`, used to detect PID recycling */
+    startTime?: string;
+}
+/** Metadata persisted by launch() so status checks survive wrapper exit */
+export interface LaunchedSessionMeta {
+    sessionId: string;
+    pid: number;
+    /** Process start time from `ps -p <pid> -o lstart=` for PID recycling detection */
+    startTime?: string;
+    /** The PID of the wrapper (agentctl launch) — may differ from `pid` (opencode process) */
+    wrapperPid?: number;
+    cwd: string;
+    model?: string;
+    prompt?: string;
+    launchedAt: string;
+}
+/** Shape of an OpenCode session JSON file */
+export interface OpenCodeSessionFile {
+    id: string;
+    slug?: string;
+    version?: string;
+    projectID?: string;
+    directory?: string;
+    title?: string;
+    time?: {
+        created?: number | string;
+        updated?: number | string;
+    };
+    summary?: {
+        additions?: number;
+        deletions?: number;
+        files?: number;
+    };
+}
+/** Shape of an OpenCode message JSON file */
+export interface OpenCodeMessageFile {
+    id: string;
+    sessionID?: string;
+    role?: "user" | "assistant";
+    time?: {
+        created?: number | string;
+        completed?: number | string;
+    };
+    agent?: string;
+    model?: {
+        providerID?: string;
+        modelID?: string;
+    };
+    tokens?: {
+        input?: number;
+        output?: number;
+        reasoning?: number;
+    };
+    cache?: {
+        read?: number;
+        write?: number;
+    };
+    cost?: number;
+    finish?: string;
+    error?: {
+        name?: string;
+        data?: {
+            message?: string;
+        };
+    };
+    modelID?: string;
+    providerID?: string;
+}
+export interface OpenCodeAdapterOpts {
+    storageDir?: string;
+    sessionsMetaDir?: string;
+    getPids?: () => Promise<Map<number, PidInfo>>;
+    /** Override PID liveness check for testing (default: process.kill(pid, 0)) */
+    isProcessAlive?: (pid: number) => boolean;
+}
+/**
+ * Compute the project hash matching OpenCode's approach: SHA1 of the directory path.
+ */
+export declare function computeProjectHash(directory: string): string;
+/**
+ * OpenCode adapter — reads session data from ~/.local/share/opencode/storage/
+ * and cross-references with running opencode processes.
+ */
+export declare class OpenCodeAdapter implements AgentAdapter {
+    readonly id = "opencode";
+    private readonly storageDir;
+    private readonly sessionDir;
+    private readonly messageDir;
+    private readonly sessionsMetaDir;
+    private readonly getPids;
+    private readonly isProcessAlive;
+    constructor(opts?: OpenCodeAdapterOpts);
+    list(opts?: ListOpts): Promise<AgentSession[]>;
+    peek(sessionId: string, opts?: PeekOpts): Promise<string>;
+    status(sessionId: string): Promise<AgentSession>;
+    launch(opts: LaunchOpts): Promise<AgentSession>;
+    stop(sessionId: string, opts?: StopOpts): Promise<void>;
+    resume(sessionId: string, message: string): Promise<void>;
+    events(): AsyncIterable<LifecycleEvent>;
+    /**
+     * Read all session JSON files for a project directory.
+     */
+    private getSessionFilesForProject;
+    /**
+     * Build an AgentSession from an OpenCode session file.
+     */
+    private buildSession;
+    /**
+     * Check whether a session is currently running by cross-referencing PIDs.
+     */
+    private isSessionRunning;
+    /**
+     * Check whether a process plausibly belongs to a session by verifying
+     * the process started at or after the session's creation time.
+     */
+    private processStartedAfterSession;
+    private findMatchingPid;
+    /**
+     * Read all messages for a session and aggregate stats.
+     */
+    private aggregateMessageStats;
+    /**
+     * Read all message files for a session, sorted by time.
+     */
+    private readMessages;
+    /**
+     * Read message content parts from storage/part/<messageId>/
+     */
+    private readMessageParts;
+    /**
+     * Resolve a session ID (supports prefix matching).
+     */
+    private resolveSessionId;
+    private findPidForSession;
+    writeSessionMeta(meta: Omit<LaunchedSessionMeta, "startTime">): Promise<void>;
+    readSessionMeta(sessionId: string): Promise<LaunchedSessionMeta | null>;
+    private deleteSessionMeta;
+}