feat(openclaw): support gateway protocol v4 (#68)

Co-authored-by: Cursor <cursoragent@cursor.com>

AGENTS.md

@@ -0,0 +1,46 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/routes/`: TanStack Start file-based routes (`/monitor`, `/workspace`, API handlers under `src/routes/api/`).
+- `src/components/`: UI by domain (`monitor/`, `workspace/`, `navigation/`, `ani/`).
+- `src/integrations/`: external/system integrations (`openclaw/`, `trpc/`, `query/`).
+- `src/lib/`: shared utilities (graph layout, workspace FS helpers, demo data).
+- `public/`: static assets (images, fonts, skill metadata).
+- Runtime and packaging files: `Dockerfile`, `docker-compose.yml`, `bin/crabwalk`.
+
+## Architecture Overview
+- Stack: TanStack Start + Router, tRPC, TanStack Query/DB, ReactFlow, Tailwind v4, React 19.
+- Monitor flow: OpenClaw gateway WebSocket -> server integration (`src/integrations/openclaw/`) -> tRPC router (`src/integrations/trpc/router.ts`) -> client collections/graph UI.
+- API entrypoint: `src/routes/api/trpc.$.ts`; router setup in `src/router.tsx`.
+
+## Build, Test, and Development Commands
+- `npm run dev`: starts local dev server on `http://localhost:3000`.
+- `npm run build`: creates production build with Vite/TanStack Start.
+- `npm start`: runs the built server from `.output/server/index.mjs`.
+- `docker-compose up -d`: run containerized app (set `CLAWDBOT_API_TOKEN` first).
+
+## Coding Style & Naming Conventions
+- Language: TypeScript + React function components.
+- Style in current codebase: 2-space indentation, single quotes, semicolon-light formatting.
+- Components/files: `PascalCase` for React components (example: `SessionNode.tsx`).
+- Hooks/utilities: `camelCase` exports, hooks prefixed with `use` (example: `useIsMobile.ts`).
+- Route files follow TanStack conventions, e.g. `src/routes/monitor/index.tsx`, `src/routes/api/trpc.$.ts`.
+- Use path alias `~/` for imports from `src`.
+
+## Testing Guidelines
+- No dedicated automated test script is currently defined in `package.json`.
+- Minimum pre-PR validation: run `npm run build`, then verify `/monitor` connectivity and `/workspace` file operations in `npm run dev`.
+- If adding tests, colocate as `*.test.ts` / `*.test.tsx` near the feature and prefer fast unit tests for parsing/state logic.
+
+## Commit & Pull Request Guidelines
+- Follow Conventional Commit style used in history: `feat(scope): ...`, `fix(scope): ...`, `docs: ...`, `chore: ...`.
+- Keep scopes aligned with feature areas (`monitor`, `workspace`, `nav`, `openclaw`).
+- PRs should include:
+  - clear summary of behavior changes,
+  - linked issue(s) when applicable,
+  - screenshots/GIFs for UI changes,
+  - notes on env/config changes (tokens, gateway URL, workspace mounts).
+
+## Security & Configuration Tips
+- Never commit secrets. Use `.env` or runtime env vars (`CLAWDBOT_API_TOKEN`, `CLAWDBOT_URL`).
+- Keep `.env.example` updated when introducing new required configuration.

src/integrations/openclaw/client.ts

@@ -9,17 +9,124 @@ import {
   type AgentEvent,
   type SessionInfo,
   type SessionsListParams,
+  type ConnectChallengePayload,
   createConnectParams,
 } from './protocol'
+import {
+  buildSignedDevice,
+  clearStoredDeviceToken,
+  getOrCreateIdentity,
+  loadStoredDeviceToken,
+  saveStoredDeviceToken,
+} from './device'
 
 const DEFAULT_GATEWAY_URL = process.env.CLAWDBOT_URL || 'ws://127.0.0.1:18789'
-
-interface ChallengePayload {
-  nonce: string
-  ts: number
-}
+const DEFAULT_SCOPES = ['operator.read'] as const
 
 type EventCallback = (event: EventFrame) => void
+export type GatewayAuthState =
+  | 'unknown'
+  | 'authorized'
+  | 'unpaired'
+  | 'unauthorized'
+  | 'degraded'
+
+interface PairingInfo {
+  requestId?: string
+  message?: string
+}
+
+function normalized(value: unknown): string | undefined {
+  return typeof value === 'string' ? value.trim() || undefined : undefined
+}
+
+function isTrustedLoopback(url: string): boolean {
+  try {
+    const u = new URL(url)
+    return u.hostname === '127.0.0.1' || u.hostname === 'localhost' || u.hostname === '::1'
+  } catch {
+    return false
+  }
+}
+
+/** Inline of openclaw selectGatewayConnectAuth / buildGatewayConnectAuth (operator subset). */
+function selectConnectAuth(params: {
+  envToken?: string
+  storedToken?: string
+  storedScopes?: string[]
+  pendingDeviceTokenRetry?: boolean
+  trustedDeviceTokenRetry?: boolean
+}) {
+  const authToken = normalized(params.envToken)
+  const storedToken = normalized(params.storedToken)
+  const useRetryToken =
+    params.pendingDeviceTokenRetry === true &&
+    Boolean(authToken && storedToken && params.trustedDeviceTokenRetry)
+  // Reference: resolved when retry OR (!(authToken) && stored)
+  const resolvedDeviceToken =
+    useRetryToken || (!authToken && storedToken) ? storedToken : undefined
+  const usingStoredDeviceToken =
+    Boolean(resolvedDeviceToken && storedToken) && resolvedDeviceToken === storedToken
+  const selectedToken = authToken ?? resolvedDeviceToken
+  return {
+    authToken: selectedToken,
+    // buildGatewayConnectAuth: deviceToken = authDeviceToken ?? resolvedDeviceToken
+    // select sets authDeviceToken only on retry; resolved covers stored-as-primary
+    authDeviceToken: (useRetryToken ? storedToken : undefined) ?? resolvedDeviceToken,
+    signatureToken: selectedToken ?? null,
+    usingStoredDeviceToken,
+    /** Stored token is auth.token (no env) — for clear-and-retry path. */
+    usingStoredAsPrimary: Boolean(!authToken && selectedToken && selectedToken === storedToken),
+    storedScopes: params.storedScopes,
+  }
+}
+
+function shouldRetryWithDeviceToken(params: {
+  retryBudgetUsed: boolean
+  currentDeviceToken?: string
+  explicitToken?: string
+  storedToken?: string
+  trustedEndpoint: boolean
+  error?: { code?: string; message?: string; details?: unknown }
+}): boolean {
+  if (
+    params.retryBudgetUsed ||
+    params.currentDeviceToken ||
+    !params.explicitToken ||
+    !params.storedToken ||
+    !params.trustedEndpoint
+  ) {
+    return false
+  }
+  const code = params.error?.code ?? ''
+  const message = (params.error?.message ?? '').toLowerCase()
+  const details = JSON.stringify(params.error?.details ?? '')
+  return (
+    code === 'AUTH_TOKEN_MISMATCH' ||
+    message.includes('auth_token_mismatch') ||
+    message.includes('retry_with_device_token') ||
+    details.includes('retry_with_device_token') ||
+    details.includes('AUTH_TOKEN_MISMATCH')
+  )
+}
+
+function shouldRetryClearStoredToken(params: {
+  retryBudgetUsed: boolean
+  usingStoredAsPrimary: boolean
+  envToken?: string
+  error?: { code?: string; message?: string; details?: unknown }
+}): boolean {
+  if (params.retryBudgetUsed || !params.usingStoredAsPrimary || !params.envToken) return false
+  const code = params.error?.code ?? ''
+  const message = (params.error?.message ?? '').toLowerCase()
+  const details = JSON.stringify(params.error?.details ?? '')
+  return (
+    code === 'AUTH_TOKEN_MISMATCH' ||
+    message.includes('auth_token_mismatch') ||
+    message.includes('retry_with_device_token') ||
+    details.includes('AUTH_TOKEN_MISMATCH')
+  )
+}
 
 export class ClawdbotClient {
   private ws: WebSocket | null = null
@@ -32,6 +139,21 @@ export class ClawdbotClient {
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null
   private _connected = false
   private _connecting = false
+  private _authState: GatewayAuthState = 'unknown'
+  private _scopes: string[] = []
+  private _pairingInfo: PairingInfo | null = null
+  private _connectPromiseSettled = false
+  private readonly debugEnabled = process.env.CRABWALK_DEBUG_OPENCLAW === '1'
+  /** One-shot AUTH_TOKEN_MISMATCH retry within a connect attempt. */
+  private _authRetryUsed = false
+  private _pendingDeviceTokenRetry = false
+  private _lastConnectAuth: {
+    authDeviceToken?: string
+    usingStoredAsPrimary: boolean
+  } | null = null
+  private _connectResolve?: (v: HelloOk) => void
+  private _connectReject?: (e: Error) => void
+  private _connectTimeout?: ReturnType<typeof setTimeout>
 
   constructor(
     private url: string = DEFAULT_GATEWAY_URL,
@@ -42,17 +164,39 @@ export class ClawdbotClient {
     return this._connected
   }
 
+  get authState() {
+    return this._authState
+  }
+
+  get scopes() {
+    return [...this._scopes]
+  }
+
+  get pairingInfo() {
+    return this._pairingInfo
+  }
+
   async connect(): Promise<HelloOk> {
     if (this._connecting || this._connected) {
-      return { type: 'hello-ok', protocol: 3 } as HelloOk
+      return { type: 'hello-ok', protocol: 4 } as HelloOk
     }
     this._connecting = true
+    this._connectPromiseSettled = false
+    this._authRetryUsed = false
+    this._pendingDeviceTokenRetry = false
+    this._lastConnectAuth = null
     return new Promise((resolve, reject) => {
+      this._connectResolve = resolve
+      this._connectReject = reject
       const timeout = setTimeout(() => {
         this._connecting = false
         this.ws?.close()
-        reject(new Error('Connection timeout - is openclaw gateway running?'))
+        if (!this._connectPromiseSettled) {
+          this._connectPromiseSettled = true
+          reject(new Error('Connection timeout - is openclaw gateway running?'))
+        }
       }, 10000)
+      this._connectTimeout = timeout
 
       try {
         this.ws = new WebSocket(this.url)
@@ -63,7 +207,7 @@ export class ClawdbotClient {
       }
 
       this.ws.once('open', () => {
-        // WebSocket connected, waiting for challenge
+        this.debugLog('socket open, waiting for connect.challenge')
       })
 
       this.ws.on('message', (data) => {
@@ -73,11 +217,11 @@ export class ClawdbotClient {
 
           // Handle challenge-response auth
           if (msg.type === 'event' && msg.event === 'connect.challenge') {
-            this.handleChallenge(msg.payload as ChallengePayload)
+            this.handleChallenge(msg.payload as ConnectChallengePayload)
             return
           }
 
-          this.handleMessage(msg, resolve, reject, timeout)
+          this.handleMessage(msg)
         } catch (e) {
           console.error('[openclaw] Failed to parse message:', e)
         }
@@ -86,14 +230,33 @@ export class ClawdbotClient {
       this.ws.on('error', (err) => {
         clearTimeout(timeout)
         this._connecting = false
-        reject(err)
+        this.debugLog('socket error before connect', err)
+        if (!this._connectPromiseSettled) {
+          this._connectPromiseSettled = true
+          reject(err)
+        }
       })
 
-      this.ws.on('close', (code, _reason) => {
+      this.ws.on('close', (code, reason) => {
         clearTimeout(timeout)
         const wasConnected = this._connected
+        const wasConnecting = this._connecting
+        this.debugLog('socket close', {
+          code,
+          reason: reason?.toString?.() ?? '',
+          wasConnected,
+          wasConnecting,
+        })
         this._connected = false
         this._connecting = false
+        if (!wasConnected && wasConnecting && !this._connectPromiseSettled) {
+          this._connectPromiseSettled = true
+          reject(
+            new Error(
+              `Gateway closed before connect (code ${code}${reason ? `, reason: ${reason.toString()}` : ''})`
+            )
+          )
+        }
         // Only reconnect if we were previously connected and it wasn't a clean close
         if (wasConnected && code !== 1000) {
           this.scheduleReconnect()
@@ -102,12 +265,69 @@ export class ClawdbotClient {
     })
   }
 
-  private handleChallenge(_challenge: ChallengePayload) {
-    if (!this.token || this.ws?.readyState !== WebSocket.OPEN) {
+  private handleChallenge(challenge: ConnectChallengePayload) {
+    if (this.ws?.readyState !== WebSocket.OPEN) {
       return
     }
 
-    const params = createConnectParams(this.token)
+    const stored = loadStoredDeviceToken()
+    const selected = selectConnectAuth({
+      envToken: this.token,
+      storedToken: stored?.token,
+      storedScopes: stored?.scopes,
+      pendingDeviceTokenRetry: this._pendingDeviceTokenRetry,
+      trustedDeviceTokenRetry: isTrustedLoopback(this.url),
+    })
+
+    const scopes =
+      selected.usingStoredDeviceToken && stored?.scopes?.length
+        ? stored.scopes
+        : [...DEFAULT_SCOPES]
+
+    let params = createConnectParams({
+      token: selected.authToken,
+      deviceToken: selected.authDeviceToken,
+      scopes,
+    })
+
+    // Payload platform must match client.platform after normalize (createConnectParams sets raw platform)
+    try {
+      const device = buildSignedDevice({
+        challenge,
+        token: selected.signatureToken,
+        role: params.role,
+        scopes: params.scopes,
+        clientId: params.client.id,
+        clientMode: params.client.mode,
+        platform: params.client.platform,
+      })
+      params = createConnectParams({
+        token: selected.authToken,
+        deviceToken: selected.authDeviceToken,
+        scopes,
+        device,
+      })
+    } catch (error) {
+      console.error('[openclaw] Failed to create signed device identity:', error)
+    }
+
+    this._lastConnectAuth = {
+      authDeviceToken: selected.authDeviceToken,
+      usingStoredAsPrimary: selected.usingStoredAsPrimary,
+    }
+
+    this.debugLog('sending connect', {
+      hasToken: Boolean(params.auth?.token),
+      hasDeviceToken: Boolean(params.auth?.deviceToken),
+      hasDevice: Boolean(params.device),
+      deviceId: params.device?.id,
+      usingStored: selected.usingStoredDeviceToken,
+      pendingRetry: this._pendingDeviceTokenRetry,
+      clientMode: params.client.mode,
+      clientPlatform: params.client.platform,
+      scopes: params.scopes,
+    })
+
     const response: RequestFrame = {
       type: 'req',
       id: `connect-${Date.now()}`,
@@ -118,27 +338,149 @@ export class ClawdbotClient {
     this.ws.send(JSON.stringify(response))
   }
 
-  private handleMessage(
-    msg: GatewayFrame | HelloOk,
-    connectResolve?: (v: HelloOk) => void,
-    _connectReject?: (e: Error) => void,
-    connectTimeout?: ReturnType<typeof setTimeout>
-  ) {
+  private handleConnectFailure(error?: { code?: string; message?: string; details?: unknown }) {
+    const stored = loadStoredDeviceToken()
+    const trusted = isTrustedLoopback(this.url)
+    const last = this._lastConnectAuth
+
+    // Env primary failed → retry once with cached device token
+    if (
+      shouldRetryWithDeviceToken({
+        retryBudgetUsed: this._authRetryUsed,
+        currentDeviceToken: last?.authDeviceToken,
+        explicitToken: this.token,
+        storedToken: stored?.token,
+        trustedEndpoint: trusted,
+        error,
+      })
+    ) {
+      this._authRetryUsed = true
+      this._pendingDeviceTokenRetry = true
+      this.debugLog('AUTH_TOKEN_MISMATCH — retrying with device token')
+      this.reopenForAuthRetry()
+      return
+    }
+
+    // Stored primary failed → clear token file, retry once with env token only
+    if (
+      shouldRetryClearStoredToken({
+        retryBudgetUsed: this._authRetryUsed,
+        usingStoredAsPrimary: Boolean(last?.usingStoredAsPrimary),
+        envToken: this.token,
+        error,
+      })
+    ) {
+      this._authRetryUsed = true
+      this._pendingDeviceTokenRetry = false
+      clearStoredDeviceToken()
+      this.debugLog('AUTH_TOKEN_MISMATCH — cleared stored device token, retrying with env')
+      this.reopenForAuthRetry()
+      return
+    }
+
+    const message = error?.message || 'Connect failed'
+    this.updateAuthStateFromError(message)
+    if (this._connectTimeout) clearTimeout(this._connectTimeout)
+    this._connecting = false
+    if (!this._connectPromiseSettled) {
+      this._connectPromiseSettled = true
+      this._connectReject?.(new Error(message))
+    }
+  }
+
+  /** Re-open socket for one-shot auth retry without settling the outer connect promise. */
+  private reopenForAuthRetry() {
+    // Detach old socket so its close handler cannot reject the connect promise.
+    const old = this.ws
+    this.ws = null
+    if (old) {
+      old.removeAllListeners()
+      old.on('error', () => {})
+      try {
+        old.close()
+      } catch {
+        // ignore
+      }
+    }
+
+    this._connected = false
+    try {
+      this.ws = new WebSocket(this.url)
+    } catch (e) {
+      this._connecting = false
+      if (!this._connectPromiseSettled) {
+        this._connectPromiseSettled = true
+        this._connectReject?.(new Error(`Failed to create WebSocket for auth retry: ${e}`))
+      }
+      return
+    }
+
+    this.ws.once('open', () => {
+      this.debugLog('auth-retry socket open, waiting for connect.challenge')
+    })
+
+    this.ws.on('message', (data) => {
+      try {
+        const msg = JSON.parse(data.toString())
+        if (msg.type === 'event' && msg.event === 'connect.challenge') {
+          this.handleChallenge(msg.payload as ConnectChallengePayload)
+          return
+        }
+        this.handleMessage(msg)
+      } catch (e) {
+        console.error('[openclaw] Failed to parse message:', e)
+      }
+    })
+
+    this.ws.on('error', (err) => {
+      this.debugLog('auth-retry socket error', err)
+      if (!this._connectPromiseSettled) {
+        this._connectPromiseSettled = true
+        this._connecting = false
+        this._connectReject?.(err instanceof Error ? err : new Error(String(err)))
+      }
+    })
+
+    this.ws.on('close', (code, reason) => {
+      this.debugLog('auth-retry socket close', {
+        code,
+        reason: reason?.toString?.() ?? '',
+      })
+      if (this._connecting && !this._connectPromiseSettled && !this._connected) {
+        this._connectPromiseSettled = true
+        this._connecting = false
+        this._connectReject?.(
+          new Error(
+            `Gateway closed during auth retry (code ${code}${reason ? `, reason: ${reason.toString()}` : ''})`
+          )
+        )
+      }
+    })
+  }
+
+  private handleMessage(msg: GatewayFrame | HelloOk) {
     if ('type' in msg) {
       switch (msg.type) {
         case 'hello-ok':
-          if (connectTimeout) clearTimeout(connectTimeout)
+          if (this._connectTimeout) clearTimeout(this._connectTimeout)
+          this.updateAuthStateFromHello(msg)
           this._connected = true
-          connectResolve?.(msg)
+          this._connecting = false
+          this._connectPromiseSettled = true
+          this._connectResolve?.(msg)
           break
 
         case 'res':
           // Check if this is the hello-ok response to our connect request
           if (msg.ok && (msg.payload as HelloOk)?.type === 'hello-ok') {
-            if (connectTimeout) clearTimeout(connectTimeout)
+            if (this._connectTimeout) clearTimeout(this._connectTimeout)
+            this.updateAuthStateFromHello(msg.payload as HelloOk)
             this._connected = true
             this._connecting = false
-            connectResolve?.(msg.payload as HelloOk)
+            this._connectPromiseSettled = true
+            this._connectResolve?.(msg.payload as HelloOk)
+          } else if (!msg.ok && String(msg.id).startsWith('connect-')) {
+            this.handleConnectFailure(msg.error)
           } else {
             this.handleResponse(msg)
           }
@@ -162,12 +504,25 @@ export class ClawdbotClient {
       if (res.ok) {
         pending.resolve(res.payload)
       } else {
-        pending.reject(new Error(res.error?.message || 'Request failed'))
+        const message = res.error?.message || 'Request failed'
+        this.updateAuthStateFromError(message)
+        pending.reject(new Error(message))
       }
     }
   }
 
   private handleEvent(event: EventFrame) {
+    if (event.event.includes('pair') || event.event.includes('device')) {
+      const payload = event.payload as { requestId?: string; message?: string } | undefined
+      if (payload?.requestId || payload?.message) {
+        this._authState = 'unpaired'
+        this._pairingInfo = {
+          requestId: payload.requestId,
+          message: payload.message,
+        }
+      }
+    }
+
     for (const listener of this.eventListeners) {
       try {
         listener(event)
@@ -235,6 +590,80 @@ export class ClawdbotClient {
       this.ws = null
     }
     this._connected = false
+    this._authState = 'unknown'
+    this._scopes = []
+    this._pairingInfo = null
+  }
+
+  private updateAuthStateFromHello(hello: HelloOk) {
+    const scopes = hello.auth?.scopes
+    this._scopes = scopes ? [...scopes] : []
+
+    if (hello.auth?.deviceToken) {
+      const identity = getOrCreateIdentity()
+      saveStoredDeviceToken({
+        deviceId: identity.id,
+        token: hello.auth.deviceToken,
+        role: hello.auth.role,
+        scopes: hello.auth.scopes,
+        updatedAtMs: Date.now(),
+      })
+      this.debugLog('persisted device token')
+    }
+
+    if (!scopes) {
+      this._authState = 'authorized'
+      return
+    }
+
+    if (scopes.includes('operator.read')) {
+      this._authState = 'authorized'
+      this._pairingInfo = null
+      this.debugLog('authorized scopes', scopes)
+      return
+    }
+
+    this._authState = scopes.length === 0 ? 'unpaired' : 'degraded'
+    this.debugLog('non-authorized scopes', scopes)
+  }
+
+  private updateAuthStateFromError(message: string) {
+    const lowered = message.toLowerCase()
+    if (lowered.includes('missing scope') || lowered.includes('operator.read')) {
+      this._authState = 'unpaired'
+      const requestId = this.extractRequestId(message)
+      this._pairingInfo = {
+        requestId: requestId ?? this._pairingInfo?.requestId,
+        message,
+      }
+      return
+    }
+
+    if (lowered.includes('unauthorized') || lowered.includes('forbidden')) {
+      this._authState = 'unauthorized'
+      this._pairingInfo = { message }
+    }
+  }
+
+  private debugLog(message: string, payload?: unknown) {
+    if (!this.debugEnabled) return
+    if (payload !== undefined) {
+      console.log(`[openclaw][debug] ${message}`, payload)
+      return
+    }
+    console.log(`[openclaw][debug] ${message}`)
+  }
+
+  private extractRequestId(message: string): string | undefined {
+    const explicitMatch = message.match(/request(?:\s+id)?[:=\s]+([a-zA-Z0-9_-]+)/i)
+    if (explicitMatch?.[1]) {
+      return explicitMatch[1]
+    }
+
+    const uuidMatch = message.match(
+      /\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/i
+    )
+    return uuidMatch?.[0]
   }
 }
 

src/integrations/openclaw/device-auth.selfcheck.ts

@@ -0,0 +1,35 @@
+/**
+ * Self-check for v3 device-auth payload (no test framework).
+ * Run: node --experimental-strip-types src/integrations/openclaw/device-auth.selfcheck.ts
+ */
+import {
+  buildDeviceAuthPayloadV3,
+  normalizeDeviceMetadataForAuth,
+} from './device.ts'
+
+function assert(cond: unknown, msg: string): asserts cond {
+  if (!cond) throw new Error(msg)
+}
+
+const platform = normalizeDeviceMetadataForAuth('Linux')
+assert(platform === 'linux', `normalize DeviceMetadata: expected 'linux', got '${platform}'`)
+
+const payload = buildDeviceAuthPayloadV3({
+  deviceId: 'abc123',
+  clientId: 'cli',
+  clientMode: 'cli',
+  role: 'operator',
+  scopes: ['operator.read'],
+  signedAtMs: 1700000000000,
+  token: 'tok',
+  nonce: 'nonce-1',
+  platform: 'Linux',
+  deviceFamily: '',
+})
+
+const expected =
+  'v3|abc123|cli|cli|operator|operator.read|1700000000000|tok|nonce-1|linux|'
+
+assert(payload === expected, `payload mismatch:\n  got: ${payload}\n  exp: ${expected}`)
+
+console.log('device-auth.selfcheck: ok')

src/integrations/openclaw/device.ts

@@ -0,0 +1,242 @@
+import fs from 'fs'
+import path from 'path'
+import {
+  createHash,
+  createPrivateKey,
+  generateKeyPairSync,
+  sign,
+} from 'crypto'
+import type { ConnectChallengePayload, ConnectDevice } from './protocol'
+
+const DATA_DIR = path.join(process.cwd(), 'data')
+const DEVICE_IDENTITY_FILE = path.join(DATA_DIR, 'device-identity.json')
+const DEVICE_TOKEN_FILE = path.join(DATA_DIR, 'device-token.json')
+
+interface StoredDeviceIdentity {
+  id: string
+  publicKey: string
+  privateKeyPem: string
+  createdAt: number
+  lastUsedAt: number
+}
+
+export interface StoredDeviceToken {
+  deviceId: string
+  token: string
+  role?: string
+  scopes?: string[]
+  updatedAtMs: number
+}
+
+function base64UrlToBuffer(value: string): Buffer {
+  const padded = value.padEnd(value.length + ((4 - (value.length % 4)) % 4), '=')
+  const base64 = padded.replace(/-/g, '+').replace(/_/g, '/')
+  return Buffer.from(base64, 'base64')
+}
+
+function base64UrlEncode(value: Buffer): string {
+  return value.toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/g, '')
+}
+
+function decodePublicKey(value: string): Buffer {
+  try {
+    const raw = base64UrlToBuffer(value)
+    if (raw.length > 0) return raw
+  } catch {
+    // fallback below
+  }
+  return Buffer.from(value, 'base64')
+}
+
+function fingerprintFromPublicKey(publicKey: string): string {
+  const rawPublicKey = decodePublicKey(publicKey)
+  return createHash('sha256').update(rawPublicKey).digest('hex')
+}
+
+function ensureDataDir() {
+  if (!fs.existsSync(DATA_DIR)) {
+    fs.mkdirSync(DATA_DIR, { recursive: true })
+  }
+}
+
+function loadStoredIdentity(): StoredDeviceIdentity | null {
+  try {
+    if (!fs.existsSync(DEVICE_IDENTITY_FILE)) {
+      return null
+    }
+    const data = JSON.parse(fs.readFileSync(DEVICE_IDENTITY_FILE, 'utf-8')) as StoredDeviceIdentity
+    if (!data.publicKey || !data.privateKeyPem) {
+      return null
+    }
+    const canonicalId = fingerprintFromPublicKey(data.publicKey)
+    const normalized: StoredDeviceIdentity = {
+      ...data,
+      id: canonicalId,
+    }
+    // Auto-migrate legacy id formats to canonical fingerprint.
+    if (data.id !== canonicalId) {
+      saveStoredIdentity(normalized)
+    }
+    return normalized
+  } catch {
+    return null
+  }
+}
+
+function saveStoredIdentity(identity: StoredDeviceIdentity) {
+  ensureDataDir()
+  fs.writeFileSync(DEVICE_IDENTITY_FILE, JSON.stringify(identity, null, 2), { mode: 0o600 })
+  try {
+    fs.chmodSync(DEVICE_IDENTITY_FILE, 0o600)
+  } catch {
+    // ponytail: chmod best-effort on platforms that ignore mode
+  }
+}
+
+function generateStoredIdentity(): StoredDeviceIdentity {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519')
+  const publicJwk = publicKey.export({ format: 'jwk' })
+  if (!publicJwk.x) {
+    throw new Error('Failed to export Ed25519 public key')
+  }
+
+  const rawPublicKey = base64UrlToBuffer(publicJwk.x)
+  const fingerprint = createHash('sha256').update(rawPublicKey).digest('hex')
+  const now = Date.now()
+
+  return {
+    id: fingerprint,
+    publicKey: base64UrlEncode(rawPublicKey),
+    privateKeyPem: privateKey.export({ format: 'pem', type: 'pkcs8' }).toString(),
+    createdAt: now,
+    lastUsedAt: now,
+  }
+}
+
+/** Verbatim from openclaw gateway-client device-auth.ts */
+export function normalizeDeviceMetadataForAuth(value?: string | null): string {
+  if (typeof value !== 'string') {
+    return ''
+  }
+  const trimmed = value.trim()
+  if (!trimmed) {
+    return ''
+  }
+  return trimmed.replace(/[A-Z]/g, (char) => String.fromCharCode(char.charCodeAt(0) + 32))
+}
+
+export function buildDeviceAuthPayloadV3(params: {
+  deviceId: string
+  clientId: string
+  clientMode: string
+  role: string
+  scopes: string[]
+  signedAtMs: number
+  token?: string | null
+  nonce: string
+  platform?: string | null
+  deviceFamily?: string | null
+}): string {
+  const scopes = params.scopes.join(',')
+  const token = params.token ?? ''
+  const platform = normalizeDeviceMetadataForAuth(params.platform)
+  const deviceFamily = normalizeDeviceMetadataForAuth(params.deviceFamily)
+  return [
+    'v3',
+    params.deviceId,
+    params.clientId,
+    params.clientMode,
+    params.role,
+    scopes,
+    String(params.signedAtMs),
+    token,
+    params.nonce,
+    platform,
+    deviceFamily,
+  ].join('|')
+}
+
+interface BuildSignedDeviceParams {
+  challenge: ConnectChallengePayload
+  token: string | null
+  role: string
+  scopes: string[]
+  clientId: string
+  clientMode: string
+  platform?: string | null
+  deviceFamily?: string | null
+}
+
+export function getOrCreateIdentity(): StoredDeviceIdentity {
+  const existing = loadStoredIdentity()
+  if (existing) {
+    return existing
+  }
+  const generated = generateStoredIdentity()
+  saveStoredIdentity(generated)
+  return generated
+}
+
+export function buildSignedDevice(params: BuildSignedDeviceParams): ConnectDevice {
+  const nonce = params.challenge.nonce?.trim()
+  if (!nonce) {
+    throw new Error('connect.challenge nonce is empty — refusing to sign (would fall back to v1)')
+  }
+
+  const identity = getOrCreateIdentity()
+  const privateKey = createPrivateKey(identity.privateKeyPem)
+  const signedAt = Date.now()
+  const payload = buildDeviceAuthPayloadV3({
+    deviceId: identity.id,
+    clientId: params.clientId,
+    clientMode: params.clientMode,
+    role: params.role,
+    scopes: params.scopes,
+    signedAtMs: signedAt,
+    token: params.token,
+    nonce,
+    platform: params.platform,
+    deviceFamily: params.deviceFamily ?? '',
+  })
+  const signature = base64UrlEncode(sign(null, Buffer.from(payload, 'utf8'), privateKey))
+
+  identity.lastUsedAt = signedAt
+  saveStoredIdentity(identity)
+
+  return {
+    id: identity.id,
+    publicKey: identity.publicKey,
+    signature,
+    signedAt,
+    nonce,
+  }
+}
+
+export function loadStoredDeviceToken(): StoredDeviceToken | null {
+  try {
+    if (!fs.existsSync(DEVICE_TOKEN_FILE)) return null
+    const data = JSON.parse(fs.readFileSync(DEVICE_TOKEN_FILE, 'utf-8')) as StoredDeviceToken
+    if (!data.token || !data.deviceId) return null
+    return data
+  } catch {
+    return null
+  }
+}
+
+export function saveStoredDeviceToken(entry: StoredDeviceToken) {
+  ensureDataDir()
+  fs.writeFileSync(DEVICE_TOKEN_FILE, JSON.stringify(entry, null, 2), { mode: 0o600 })
+  try {
+    fs.chmodSync(DEVICE_TOKEN_FILE, 0o600)
+  } catch {
+    // ponytail: chmod best-effort
+  }
+}
+
+export function clearStoredDeviceToken() {
+  try {
+    if (fs.existsSync(DEVICE_TOKEN_FILE)) fs.unlinkSync(DEVICE_TOKEN_FILE)
+  } catch {
+    // ignore
+  }
+}

src/integrations/openclaw/parser.ts

@@ -55,7 +55,13 @@ export function chatEventToAction(event: ChatEvent): MonitorAction {
     }
   }
 
-  if (event.message) {
+  // v4: deltaText when replace===true or message absent; else cumulative message path
+  if (
+    typeof event.deltaText === 'string' &&
+    (event.replace === true || event.message == null)
+  ) {
+    action.content = event.deltaText
+  } else if (event.message) {
     if (typeof event.message === 'string') {
       action.content = event.message
     } else if (typeof event.message === 'object') {

src/integrations/openclaw/protocol.ts

@@ -1,4 +1,4 @@
-// Clawdbot Gateway Protocol v3 types
+// Clawdbot Gateway Protocol v4 types
 
 // Frame types
 export interface RequestFrame {
@@ -13,7 +13,7 @@ export interface ResponseFrame {
   id: string
   ok: boolean
   payload?: unknown
-  error?: { code: string; message: string }
+  error?: { code: string; message: string; details?: unknown }
 }
 
 export interface EventFrame {
@@ -32,14 +32,34 @@ export interface ClientInfo {
   displayName: string
   version: string
   platform: string
-  mode: 'ui' | 'cli' | 'bot'
+  mode: 'ui' | 'cli' | 'bot' | 'operator' | 'node'
 }
 
 export interface ConnectParams {
-  minProtocol: 3
-  maxProtocol: 3
+  minProtocol: 3 | 4
+  maxProtocol: 3 | 4
   client: ClientInfo
-  auth?: { token?: string }
+  auth?: { token?: string; deviceToken?: string }
+  device?: ConnectDevice
+}
+
+export interface ConnectChallengePayload {
+  nonce: string
+  ts: number
+}
+
+export interface ConnectDevice {
+  id: string
+  publicKey: string
+  signature: string
+  signedAt: number
+  nonce: string
+}
+
+export interface HelloAuth {
+  role?: string
+  scopes?: string[]
+  deviceToken?: string
 }
 
 export interface HelloOk {
@@ -51,6 +71,7 @@ export interface HelloOk {
     stateVersion: { presence: number; health: number }
   }
   features: { methods: string[]; events: string[] }
+  auth?: HelloAuth
 }
 
 export interface PresenceEntry {
@@ -59,14 +80,15 @@ export interface PresenceEntry {
   connectedAt: number
 }
 
-// Chat events
-// Note: gateway sends cumulative message content with each delta, not incremental chars
+// Chat events — v4 may send deltaText (incremental) and/or cumulative message
 export interface ChatEvent {
   runId: string
   sessionKey: string
   seq: number
   state: 'delta' | 'final' | 'aborted' | 'error'
   message?: unknown
+  deltaText?: string
+  replace?: boolean
   errorMessage?: string
   usage?: {
     inputTokens?: number
@@ -231,24 +253,66 @@ export function parseSessionKey(key: string): {
   return { agentId, platform, recipient, isGroup }
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function createConnectParams(token?: string): any {
+export type CreateConnectOptions = {
+  token?: string
+  deviceToken?: string
+  device?: ConnectDevice
+  scopes?: string[]
+}
+
+export function createConnectParams(
+  tokenOrOpts?: string | CreateConnectOptions,
+  device?: ConnectDevice
+): ConnectParams & {
+  role: string
+  scopes: string[]
+  caps: unknown[]
+  commands: unknown[]
+  permissions: Record<string, unknown>
+  locale: string
+  userAgent: string
+} {
+  // ponytail: overload keeps call sites short; prefer opts object for deviceToken/scopes
+  const opts: CreateConnectOptions =
+    typeof tokenOrOpts === 'string' || tokenOrOpts === undefined
+      ? { token: tokenOrOpts, device }
+      : tokenOrOpts
+
+  const platformMap: Record<string, string> = {
+    win32: 'windows',
+    darwin: 'macos',
+    linux: 'linux',
+  }
+  const platform = platformMap[process.platform] ?? process.platform
+
+  const authToken = opts.token
+  const authDeviceToken = opts.deviceToken
+  const auth =
+    authToken || authDeviceToken
+      ? {
+          ...(authToken ? { token: authToken } : {}),
+          ...(authDeviceToken ? { deviceToken: authDeviceToken } : {}),
+        }
+      : undefined
+
   return {
-    minProtocol: 3,
-    maxProtocol: 3,
+    minProtocol: 4,
+    maxProtocol: 4,
     client: {
       id: 'cli',
+      displayName: 'crabwalk-monitor',
       version: '0.1.0',
-      platform: 'linux',
+      platform,
       mode: 'cli',
     },
     role: 'operator',
-    scopes: ['operator.read'],
+    scopes: opts.scopes ?? ['operator.read'],
     caps: [],
     commands: [],
     permissions: {},
     locale: 'en-US',
     userAgent: 'crabwalk-monitor/0.1.0',
-    auth: token ? { token } : undefined,
+    auth,
+    device: opts.device,
   }
 }

src/integrations/trpc/router.ts

@@ -43,7 +43,12 @@ const openclawRouter = router({
   connect: publicProcedure.mutation(async () => {
     const client = getClawdbotClient()
     if (client.connected) {
-      return { status: 'already_connected' as const }
+      return {
+        status: 'already_connected' as const,
+        authState: client.authState,
+        scopes: client.scopes,
+        pairing: client.pairingInfo,
+      }
     }
     try {
       const hello = await client.connect()
@@ -52,11 +57,17 @@ const openclawRouter = router({
         protocol: hello.protocol,
         features: hello.features,
         presenceCount: hello.snapshot?.presence?.length ?? 0,
+        authState: client.authState,
+        scopes: client.scopes,
+        pairing: client.pairingInfo,
       }
     } catch (error) {
       return {
         status: 'error' as const,
         message: error instanceof Error ? error.message : 'Connection failed',
+        authState: client.authState,
+        scopes: client.scopes,
+        pairing: client.pairingInfo,
       }
     }
   }),
@@ -72,6 +83,16 @@ const openclawRouter = router({
     return { connected: client.connected }
   }),
 
+  authStatus: publicProcedure.query(() => {
+    const client = getClawdbotClient()
+    return {
+      connected: client.connected,
+      authState: client.authState,
+      scopes: client.scopes,
+      pairing: client.pairingInfo,
+    }
+  }),
+
   gatewayEndpoint: publicProcedure.query(() => {
     return { url: getClawdbotEndpoint() }
   }),
@@ -134,7 +155,7 @@ const openclawRouter = router({
       const client = getClawdbotClient()
       const persistence = getPersistenceService()
       if (!client.connected) {
-        return { sessions: [], error: 'Not connected' }
+        return { sessions: [], error: 'Not connected', authState: client.authState }
       }
       try {
         const sessions = await client.listSessions(input)
@@ -143,11 +164,14 @@ const openclawRouter = router({
         for (const session of monitorSessions) {
           persistence.upsertSession(session)
         }
-        return { sessions: monitorSessions }
+        return { sessions: monitorSessions, authState: client.authState, scopes: client.scopes }
       } catch (error) {
         return {
           sessions: [],
           error: error instanceof Error ? error.message : 'Failed to list sessions',
+          authState: client.authState,
+          scopes: client.scopes,
+          pairing: client.pairingInfo,
         }
       }
     }),

src/routes/monitor/index.tsx

@@ -65,10 +65,19 @@ function MonitorPageWrapper() {
 const RETRY_DELAY = 3000
 const MAX_RETRIES = 10
 const DEFAULT_GATEWAY_ENDPOINT = 'ws://127.0.0.1:18789'
+type AuthState = 'unknown' | 'authorized' | 'unpaired' | 'unauthorized' | 'degraded'
+
+interface PairingState {
+  requestId?: string
+  message?: string
+}
 
 function MonitorPage() {
   const [connected, setConnected] = useState(false)
   const [connecting, setConnecting] = useState(false)
+  const [authState, setAuthState] = useState<AuthState>('unknown')
+  const [scopes, setScopes] = useState<string[]>([])
+  const [pairing, setPairing] = useState<PairingState | null>(null)
   const [retryCount, setRetryCount] = useState(0)
   const [historicalMode, setHistoricalMode] = useState(false)
   const [debugMode, setDebugMode] = useState(false)
@@ -117,6 +126,7 @@ function MonitorPage() {
   // Check connection status and persistence on mount
   useEffect(() => {
     checkStatus()
+    checkAuthStatus()
     checkPersistenceStatus()
     loadGatewayEndpoint()
   }, [])
@@ -151,18 +161,43 @@ function MonitorPage() {
     }
   }
 
+  const checkAuthStatus = useCallback(async () => {
+    try {
+      const status = await trpc.openclaw.authStatus.query()
+      setConnected(status.connected)
+      setAuthState(status.authState as AuthState)
+      setScopes(status.scopes ?? [])
+      setPairing(status.pairing ?? null)
+    } catch {
+      // ignore
+    }
+  }, [])
+
+  const canPollSessions = useMemo(() => {
+    if (!connected) return false
+    if (authState === 'unpaired' || authState === 'unauthorized' || authState === 'degraded') {
+      return false
+    }
+    return true
+  }, [connected, authState])
+
   const handleConnect = async (retry = 0) => {
     setConnecting(true)
     setRetryCount(retry)
     try {
       const result = await trpc.openclaw.connect.mutate()
+      setAuthState((result.authState as AuthState) ?? 'unknown')
+      setScopes(result.scopes ?? [])
+      setPairing(result.pairing ?? null)
       if (result.status === 'connected' || result.status === 'already_connected') {
         setConnected(true)
         setRetryCount(0)
         setConnecting(false)
-        // Hydrate from persistence if enabled
-        await hydrateFromPersistence()
-        await loadSessions()
+        if (result.authState === 'authorized' || result.authState === 'unknown') {
+          // Hydrate from persistence if enabled
+          await hydrateFromPersistence()
+          await loadSessions()
+        }
         return
       }
     } catch {
@@ -199,17 +234,24 @@ function MonitorPage() {
     try {
       await trpc.openclaw.disconnect.mutate()
       setConnected(false)
+      setAuthState('unknown')
+      setScopes([])
+      setPairing(null)
       clearCollections()
     } catch (e) {
       console.error('Disconnect error:', e)
     }
   }
 
-  const loadSessions = async () => {
+  const loadSessions = useCallback(async () => {
     try {
       const result = await trpc.openclaw.sessions.query(
         historicalMode ? { activeMinutes: 1440 } : { activeMinutes: 60 }
       )
+      setAuthState((prev) => (result.authState as AuthState) ?? prev)
+      setScopes((prev) => result.scopes ?? prev)
+      setPairing((prev) => result.pairing ?? prev)
+
       if (result.sessions) {
         for (const session of result.sessions) {
           upsertSession(session)
@@ -218,15 +260,18 @@ function MonitorPage() {
     } catch (e) {
       console.error('Failed to load sessions:', e)
     }
-  }
+  }, [historicalMode])
 
   const handleRefresh = useCallback(async () => {
-    await loadSessions()
-  }, [historicalMode])
+    await checkAuthStatus()
+    if (canPollSessions) {
+      await loadSessions()
+    }
+  }, [checkAuthStatus, canPollSessions, loadSessions])
 
   const handleHistoricalModeChange = (enabled: boolean) => {
     setHistoricalMode(enabled)
-    if (connected) {
+    if (canPollSessions) {
       loadSessions()
     }
   }
@@ -337,6 +382,15 @@ function MonitorPage() {
     return () => clearInterval(interval)
   }, [])
 
+  // Poll lightweight auth status while connected
+  useEffect(() => {
+    if (!connected) return
+    const interval = setInterval(() => {
+      checkAuthStatus()
+    }, 10000)
+    return () => clearInterval(interval)
+  }, [connected, checkAuthStatus])
+
   const handleToggleSidebar = useCallback(() => {
     setSidebarCollapsed((prev) => !prev)
   }, [])
@@ -350,16 +404,16 @@ function MonitorPage() {
 
   // Poll for sessions while connected
   useEffect(() => {
-    if (!connected) return
+    if (!canPollSessions) return
     const interval = setInterval(() => {
       loadSessions()
     }, 5000) // Poll every 5 seconds
     return () => clearInterval(interval)
-  }, [connected, historicalMode])
+  }, [canPollSessions, loadSessions])
 
   // Subscribe to real-time events
   useEffect(() => {
-    if (!connected) return
+    if (!canPollSessions) return
 
     const subscription = trpc.openclaw.events.subscribe(undefined, {
       onData: (data) => {
@@ -381,7 +435,11 @@ function MonitorPage() {
     return () => {
       subscription.unsubscribe()
     }
-  }, [connected])
+  }, [canPollSessions])
+
+  const pairingHint = pairing?.requestId
+    ? `openclaw devices approve ${pairing.requestId}`
+    : 'openclaw devices list && openclaw devices approve <requestId>'
 
   return (
     <div className="h-screen flex flex-col bg-shell-950 text-white overflow-hidden">
@@ -498,6 +556,17 @@ function MonitorPage() {
         </div>
       </header>
 
+      {connected && !canPollSessions && (
+        <div className="px-4 py-2 border-y border-neon-peach/30 bg-neon-peach/10">
+          <div className="font-console text-xs text-neon-peach">
+            Authentication pending. Session polling is paused to avoid missing-scope errors.
+          </div>
+          <div className="font-console text-[11px] text-shell-300 mt-1">
+            {pairing?.message ?? `Approve this device in OpenClaw: ${pairingHint}`}
+          </div>
+        </div>
+      )}
+
       {/* Main content */}
       <div className="flex-1 flex overflow-hidden">
         {/* Sidebar - desktop only */}