ticlawk 0.1.12-dev.0

package/src/adapters/ticlawk/index.mjs

@@ -0,0 +1,1229 @@
+import { parseOptionArgs } from '../../core/argv.mjs';
+import { createHash, randomBytes } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { basename } from 'node:path';
+import { AF_ADAPTER_KEY, LEGACY_TICLAWK_API_KEY, loadPersistentConfig, persistConfig, TICLAWK_CONNECTOR_API_KEY, TICLAWK_CONNECTOR_WS_URL } from '../../core/config.mjs';
+import { belongsToRuntimeHost, getBindingRuntimeHostId, getHostId, getHostLabel } from '../../core/host-id.mjs';
+import { debugError, debugLog } from '../../core/logger.mjs';
+import { getActiveProfile, ensureLegacyProfile, readProfileMeta, saveAndActivateProfile } from '../../core/profiles.mjs';
+import { isTerminalRuntimeFailure } from '../../core/runtime-support.mjs';
+import { clearUpdateRequiredState, readUpdateState, setUpdateRequiredState } from '../../core/update-state.mjs';
+import { isManagedInstall, startDetachedSelfUpdate } from '../../core/update.mjs';
+import { resolveOpenClawWorkspace } from '../../runtimes/openclaw/target.mjs';
+import * as api from './api.mjs';
+import { processAndSaveResult } from './cards.mjs';
+import { persistApiCredential } from './credentials.mjs';
+import { TiclawkWakeClient } from './wake-client.mjs';
+
+const require = createRequire(import.meta.url);
+const qrcode = require('qrcode-terminal');
+const JOBS_WAKE_DEBOUNCE_MS = 100;
+const BINDINGS_WAKE_DEBOUNCE_MS = 500;
+const RECOVERY_AUDIT_INTERVAL_MS = 5 * 60 * 1000;
+const BINDING_AUDIT_INTERVAL_MS = 5 * 60 * 1000;
+const UPDATE_RETRY_COOLDOWN_MS = 15 * 60 * 1000;
+const UPDATE_REQUIRED_LOG_INTERVAL_MS = 60 * 1000;
+
+function connectError(statusCode, error) {
+  return { statusCode, body: { ok: false, error } };
+}
+
+function normalizeInboundMediaAssets(msg) {
+  if (!Array.isArray(msg?.media_assets)) return [];
+  return msg.media_assets
+    .map((asset) => {
+      const url = String(asset?.url || '').trim();
+      if (!url) return null;
+      return {
+        kind: 'remote_url',
+        value: url,
+        mime: asset.content_type || null,
+        assetId: asset.asset_id || null,
+        expiresAt: asset.expires_at || null,
+      };
+    })
+    .filter(Boolean);
+}
+
+function normalizeInboundMessage(msg) {
+  const messageId = msg.id || msg.message_id || null;
+  const media = normalizeInboundMediaAssets(msg);
+  return {
+    bindingId: msg.agent_id || '',
+    messageId,
+    text: msg.text || '',
+    action: msg.action || (media.length > 0 ? 'image' : 'task'),
+    media,
+    raw: {
+      ...msg,
+      id: messageId,
+    },
+  };
+}
+
+function getBindingSessionId(binding) {
+  return binding?.runtimeMeta?.sessionId || binding?.runtimeMeta?.sessionKey || binding?.runtimeMeta?.agentId || binding?.id || null;
+}
+
+function getWorkdir(meta = {}) {
+  return String(meta.workdir || meta.projectDir || meta.cwd || '').trim();
+}
+
+function getRuntimeVersion(bindingOrMeta) {
+  const value = bindingOrMeta?.runtimeMeta?.runtimeVersion ?? bindingOrMeta?.runtimeVersion ?? bindingOrMeta?.agent_runtime_version ?? null;
+  return Number.isInteger(value) ? Number(value) : null;
+}
+
+function buildSyncableRuntimeMeta(binding) {
+  const meta = (binding?.runtimeMeta && typeof binding.runtimeMeta === 'object')
+    ? { ...binding.runtimeMeta }
+    : {};
+  delete meta.runtimeVersion;
+  return Object.keys(meta).length > 0 ? meta : null;
+}
+
+function getRuntimeHostIdFromPayload(payload) {
+  return String(payload?.runtime_host_id || '').trim();
+}
+
+function getRuntimeHostLabelFromPayload(payload) {
+  return String(payload?.runtime_host_label || '').trim();
+}
+
+function getAgentIdFromPayload(payload) {
+  return String(payload?.agent_id || payload?.agentId || '').trim();
+}
+
+function buildBindingFromClaimedMessage(msg) {
+  const agentId = getAgentIdFromPayload(msg);
+  const runtime = msg.agent_service_type || msg.service_type;
+  const rawMeta = msg.agent_meta || msg.meta;
+  const sourceMeta = (rawMeta && typeof rawMeta === 'object') ? { ...rawMeta } : {};
+  const fallbackWorkdir = runtime === 'openclaw' && sourceMeta.agentId
+    ? resolveOpenClawWorkspace(sourceMeta.agentId)
+    : '';
+  const workdir = getWorkdir(sourceMeta) || fallbackWorkdir;
+  if (workdir) {
+    sourceMeta.workdir = workdir;
+    sourceMeta.projectDir = sourceMeta.projectDir || workdir;
+    sourceMeta.cwd = sourceMeta.cwd || workdir;
+  }
+  const rawRuntimeVersion = msg.agent_runtime_version ?? msg.runtime_version;
+  const runtimeVersion = Number.isInteger(rawRuntimeVersion) ? Number(rawRuntimeVersion) : 0;
+
+  return {
+    id: agentId,
+    adapter: 'ticlawk',
+    targetKey: agentId,
+    targetMeta: {
+      agentId,
+      runtime_host_id: getRuntimeHostIdFromPayload(msg) || undefined,
+    },
+    runtime_host_id: getRuntimeHostIdFromPayload(msg) || undefined,
+    runtime_host_label: getRuntimeHostLabelFromPayload(msg) || undefined,
+    runtime,
+    runtimeMeta: {
+      ...sourceMeta,
+      runtimeVersion,
+    },
+    displayName: msg.agent_display_name || msg.agent_name || agentId,
+    status: msg.agent_status || msg.status || 'connected',
+  };
+}
+
+function buildBindingFromChannelSnapshot(agent) {
+  return buildBindingFromClaimedMessage({
+    agent_id: agent.id || agent.agent_id,
+    agent_name: agent.name,
+    agent_display_name: agent.display_name,
+    agent_status: agent.status,
+    agent_service_type: agent.service_type,
+    agent_meta: agent.meta,
+    agent_runtime_version: agent.runtime_version,
+    runtime_host_id: agent.runtime_host_id,
+    runtime_host_label: agent.runtime_host_label,
+  });
+}
+
+function maskIdentity(identity = {}) {
+  return {
+    userId: identity.userId || identity.user_id || identity.id || null,
+    emailMasked: identity.emailMasked || identity.email_masked || null,
+    phoneMasked: identity.phoneMasked || identity.phone_masked || null,
+  };
+}
+
+function formatIdentityLines(identity = {}) {
+  const normalized = maskIdentity(identity);
+  return [
+    `  user: ${normalized.userId || 'unknown'}`,
+    normalized.emailMasked ? `  email: ${normalized.emailMasked}` : null,
+    normalized.phoneMasked ? `  phone: ${normalized.phoneMasked}` : null,
+  ].filter(Boolean);
+}
+
+function formatAffectedAgents(agents = []) {
+  if (!agents.length) return ['  - none found for this host'];
+  return agents.map((agent) => {
+    const display = agent.display_name || agent.name || agent.id;
+    const runtime = agent.service_type || 'unknown';
+    return `  - ${display} (${runtime}) ${agent.id}`;
+  });
+}
+
+function sha256Hex(value) {
+  return createHash('sha256').update(String(value)).digest('hex');
+}
+
+function makeClientSecret() {
+  return randomBytes(32).toString('base64url');
+}
+
+function getRuntimeWorkdir(runtimeMeta = {}) {
+  return String(runtimeMeta.workdir || runtimeMeta.cwd || runtimeMeta.projectDir || '').trim();
+}
+
+function runtimeLabel(runtime) {
+  if (runtime === 'claude_code') return 'Claude Code';
+  if (runtime === 'opencode') return 'OpenCode';
+  if (runtime === 'openclaw') return 'OpenClaw';
+  if (runtime === 'codex') return 'Codex';
+  if (runtime === 'pi') return 'Pi';
+  return runtime || 'Agent';
+}
+
+async function buildAutoRuntimeOptions(ctx, payload = {}) {
+  const workdir = getRuntimeWorkdir(payload) || process.cwd();
+  const candidates = ['codex', 'claude_code', 'opencode', 'pi'];
+  const options = [];
+  for (const serviceType of candidates) {
+    try {
+      const resolved = await ctx.resolveRuntimeBinding({
+        ...payload,
+        serviceType,
+        workdir,
+      });
+      const runtimeMeta = resolved.runtimeMeta || {};
+      const optionWorkdir = getRuntimeWorkdir(runtimeMeta) || workdir;
+      options.push({
+        runtime: resolved.runtime,
+        runtime_label: runtimeLabel(resolved.runtime),
+        display_name: resolved.displayName || basename(optionWorkdir) || runtimeLabel(resolved.runtime),
+        workdir: optionWorkdir,
+        binding_key: optionWorkdir,
+        runtime_meta: runtimeMeta,
+      });
+    } catch (err) {
+      debugLog('ticlawk-pairing', 'auto-runtime.skip', {
+        runtime: serviceType,
+        reason: err?.message || String(err),
+      });
+    }
+  }
+  return options;
+}
+
+function printPairingChallenge(session) {
+  console.log();
+  console.log('Open Ticlawk and scan the QR code below, or enter the pairing code.');
+  console.log();
+  console.log(`Pairing code: ${session.display_code}`);
+  if (session.expires_at) {
+    console.log(`Expires: ${session.expires_at}`);
+  }
+  console.log();
+  qrcode.generate(session.qr_payload, { small: true });
+  console.log();
+}
+
+async function waitForPairingApproval({ pairingId, clientSecret, pollAfterMs = 1500, expiresAt }) {
+  const deadline = expiresAt ? Date.parse(expiresAt) + 5000 : Date.now() + 10 * 60 * 1000;
+  let lastStatus = null;
+  while (Date.now() < deadline) {
+    await new Promise(resolve => setTimeout(resolve, pollAfterMs));
+    const result = await api.pollPairingSession({
+      pairing_id: pairingId,
+      client_secret: clientSecret,
+    });
+    if (!result?.ok) {
+      throw new Error(result?.error || `ticlawk pairing poll failed (${result?.code || result?.statusCode || 'unknown'})`);
+    }
+    if (result.status && result.status !== lastStatus) {
+      lastStatus = result.status;
+      if (result.status === 'scanned') {
+        console.log('[connect] scanned; waiting for approval...');
+      }
+    }
+    if (result.status === 'approved') return result;
+    if (['rejected', 'expired', 'cancelled', 'claimed'].includes(result.status)) {
+      throw new Error(`ticlawk pairing ${result.status}`);
+    }
+    pollAfterMs = Number(result.poll_after_ms || pollAfterMs || 1500);
+  }
+  throw new Error('ticlawk pairing expired');
+}
+
+export function createTiclawkAdapter(ctx) {
+  const processingChannels = new Map();
+  const hostId = getHostId();
+  const hostLabel = getHostLabel();
+  const wakeState = {
+    connected: false,
+    lastStatus: 'idle',
+    lastEventAt: null,
+    lastError: null,
+    lastConnectedAt: null,
+    lastCloseAt: null,
+    lastCloseCode: null,
+    lastCloseReason: null,
+    reconnectCount: 0,
+  };
+  let connectorSocket = null;
+  let recoveryTimer = null;
+  let bindingAuditTimer = null;
+  let jobsWakeTimer = null;
+  let bindingsWakeTimer = null;
+  let drainPromise = null;
+  let drainRequested = false;
+  let lastJobsWakeAt = 0;
+  let lastBindingsWakeAt = 0;
+  let updateRequired = null;
+  let lastUpdateRequiredLogAt = 0;
+
+  function clearDebounce(timer) {
+    if (timer) clearTimeout(timer);
+    return null;
+  }
+
+  function getUpdateRequiredHealth() {
+    const state = updateRequired || readUpdateState();
+    if (!state?.updateRequired) {
+      return {
+        updateRequired: false,
+        agentFreewayVersion: api.getAgentFreewayVersion(),
+        managedInstall: isManagedInstall(),
+      };
+    }
+    return {
+      updateRequired: true,
+      agentFreewayVersion: api.getAgentFreewayVersion(),
+      currentAgentFreewayVersion: state.currentAgentFreewayVersion || api.getAgentFreewayVersion(),
+      requiredAgentFreewayVersion: state.requiredAgentFreewayVersion || null,
+      autoUpdateStatus: state.autoUpdateStatus || null,
+      autoUpdateError: state.autoUpdateError || null,
+      managedInstall: isManagedInstall(),
+    };
+  }
+
+  function shouldAttemptAutoUpdate(previousState) {
+    const lastAttemptMs = Date.parse(previousState?.lastAutoUpdateAttemptAt || '');
+    if (Number.isFinite(lastAttemptMs) && Date.now() - lastAttemptMs < UPDATE_RETRY_COOLDOWN_MS) {
+      return false;
+    }
+    return true;
+  }
+
+  function recordUpdateRequired(err, reason) {
+    const now = Date.now();
+    const currentVersion = err?.currentAgentFreewayVersion || api.getAgentFreewayVersion();
+    const requiredVersion = err?.requiredAgentFreewayVersion || null;
+    const previousState = readUpdateState();
+    let autoUpdateStatus = previousState?.autoUpdateStatus || 'not_started';
+    let autoUpdateError = null;
+    let lastAutoUpdateAttemptAt = previousState?.lastAutoUpdateAttemptAt || null;
+
+    if (!requiredVersion) {
+      autoUpdateStatus = 'missing_required_version';
+      autoUpdateError = 'backend did not provide required_agent_freeway_version';
+    } else if (shouldAttemptAutoUpdate(previousState)) {
+      lastAutoUpdateAttemptAt = new Date().toISOString();
+      try {
+        const result = startDetachedSelfUpdate({
+          reason,
+          currentVersion,
+          requiredVersion,
+        });
+        autoUpdateStatus = result.started ? 'started' : result.reason;
+        if (result.started) {
+          debugLog('ticlawk', 'update.auto-started', {
+            reason,
+            currentAgentFreewayVersion: currentVersion,
+            requiredAgentFreewayVersion: requiredVersion,
+            pid: result.pid || null,
+            logPath: result.logPath || null,
+          });
+        }
+      } catch (updateErr) {
+        autoUpdateStatus = 'failed_to_start';
+        autoUpdateError = updateErr?.message || 'unknown error';
+      }
+    } else {
+      autoUpdateStatus = 'cooldown';
+    }
+
+    updateRequired = setUpdateRequiredState({
+      adapter: 'ticlawk',
+      currentVersion,
+      requiredVersion,
+      autoUpdateStatus,
+      autoUpdateError,
+      lastAutoUpdateAttemptAt,
+    });
+
+    if (now - lastUpdateRequiredLogAt > UPDATE_REQUIRED_LOG_INTERVAL_MS) {
+      lastUpdateRequiredLogAt = now;
+      debugError('ticlawk', 'update.required', {
+        reason,
+        currentAgentFreewayVersion: currentVersion,
+        requiredAgentFreewayVersion: requiredVersion,
+        autoUpdateStatus,
+        managedInstall: isManagedInstall(),
+        message: `Ticlawk requires ticlawk >= ${requiredVersion || 'unknown'}, current version is ${currentVersion || 'unknown'}. Please update ticlawk.`,
+      });
+    }
+  }
+
+  function clearUpdateRequired(reason) {
+    if (!updateRequired?.updateRequired && !readUpdateState()?.updateRequired) return;
+    updateRequired = null;
+    clearUpdateRequiredState('ticlawk');
+    debugLog('ticlawk', 'update.cleared', {
+      reason,
+      currentAgentFreewayVersion: api.getAgentFreewayVersion(),
+    });
+  }
+
+  function isLowFrequencyRecovery(reason) {
+    return String(reason || '').startsWith('audit');
+  }
+
+  function getRemoteAgentId(agent) {
+    return String(agent?.id || agent?.agent_id || '').trim();
+  }
+
+  function isTiclawkBindingForCurrentHost(binding) {
+    if (binding?.adapter !== 'ticlawk') return false;
+    return getBindingRuntimeHostId(binding) === hostId;
+  }
+
+  async function pruneDeletedBindings(channels, reason) {
+    if (typeof ctx.deleteBinding !== 'function') return 0;
+    if (typeof ctx.listBindings !== 'function') return 0;
+    const activeProfile = getActiveProfile();
+    if (activeProfile?.adapter !== 'ticlawk') return 0;
+
+    const remoteAgentIds = new Set(channels.map(getRemoteAgentId).filter(Boolean));
+    let pruned = 0;
+    for (const binding of ctx.listBindings({ adapter: 'ticlawk' })) {
+      if (!binding?.id) continue;
+      if (!isTiclawkBindingForCurrentHost(binding)) continue;
+      const bindingAgentIds = [
+        binding.id,
+        binding.targetKey,
+        binding.targetMeta?.agentId,
+      ].map((value) => String(value || '').trim()).filter(Boolean);
+      if (bindingAgentIds.some((id) => remoteAgentIds.has(id))) continue;
+      try {
+        await ctx.deleteBinding(binding.id);
+        pruned += 1;
+        debugLog('ticlawk', 'binding.pruned', {
+          reason,
+          bindingId: binding.id,
+          runtime: binding.runtime || null,
+          runtime_host_id: getBindingRuntimeHostId(binding) || null,
+        });
+      } catch (err) {
+        debugError('ticlawk', 'binding.prune-failed', {
+          reason,
+          bindingId: binding.id,
+          error: err?.message || 'unknown error',
+        });
+      }
+    }
+    return pruned;
+  }
+
+  async function processPendingMessagesForAgent(agentId, messages) {
+    for (const msg of messages) {
+      try {
+        const messageHostId = getRuntimeHostIdFromPayload(msg);
+        if (messageHostId && messageHostId !== hostId) {
+          await api.releaseMessage(msg.message_id, hostId);
+          debugError('ticlawk', 'message.host-mismatch', {
+            agentId,
+            messageId: msg.message_id,
+            hostId,
+            runtime_host_id: messageHostId,
+          });
+          continue;
+        }
+
+        const binding = await ctx.cacheBinding(buildBindingFromClaimedMessage(msg));
+        if (!binding?.runtime) {
+          throw new Error('claimed message missing runtime binding');
+        }
+        if (!belongsToRuntimeHost(binding, hostId)) {
+          await api.releaseMessage(msg.message_id, hostId);
+          debugError('ticlawk', 'message.binding-host-mismatch', {
+            agentId,
+            messageId: msg.message_id,
+            hostId,
+            runtime_host_id: getBindingRuntimeHostId(binding),
+          });
+          continue;
+        }
+
+        const completed = await ctx.bus.dispatchToAgent(binding.runtime, binding.id, normalizeInboundMessage(msg));
+        if (completed !== true) {
+          if (isTerminalRuntimeFailure(completed)) {
+            await api.completeMessage(msg.message_id, hostId);
+            void requestDrain('message.terminal-completed');
+            debugError('ticlawk', 'message.terminal-failed', {
+              agentId,
+              messageId: msg.message_id,
+              runtime: binding.runtime,
+              runtimeVersion: getRuntimeVersion(binding),
+              reason: completed.reason || 'runtime terminal failure',
+            });
+            continue;
+          }
+          throw new Error('runtime did not complete turn');
+        }
+        await api.completeMessage(msg.message_id, hostId);
+        void requestDrain('message.completed');
+        debugLog('ticlawk', 'message.completed', {
+          agentId,
+          messageId: msg.message_id,
+          runtime: binding.runtime,
+          runtimeVersion: getRuntimeVersion(binding),
+        });
+      } catch (err) {
+        if (api.isUpdateRequiredError(err)) {
+          recordUpdateRequired(err, 'message.dispatch');
+        }
+        try {
+          await api.releaseMessage(msg.message_id, hostId);
+        } catch (releaseErr) {
+          debugError('ticlawk', 'message.release-failed', {
+            agentId,
+            messageId: msg.message_id,
+            hostId,
+            runtime: msg.agent_service_type || null,
+            runtimeVersion: msg.agent_runtime_version ?? null,
+            error: releaseErr?.message || 'unknown error',
+          });
+        }
+        debugError('ticlawk', 'message.dispatch-failed', {
+          agentId,
+          messageId: msg.message_id,
+          hostId,
+          runtime: msg.agent_service_type || null,
+          runtimeVersion: msg.agent_runtime_version ?? null,
+          error: err?.message || 'unknown error',
+        });
+      }
+    }
+  }
+
+  async function refreshBindings(reason = 'manual') {
+    let channels = [];
+    const startedAt = Date.now();
+    try {
+      channels = await api.getAgents({ hostId });
+    } catch (err) {
+      if (api.isUpdateRequiredError(err)) {
+        recordUpdateRequired(err, 'binding.refresh');
+      }
+      debugError('ticlawk', 'binding.refresh-failed', {
+        reason,
+        durationMs: Date.now() - startedAt,
+        error: err?.message || 'unknown error',
+      });
+      return 0;
+    }
+
+    let hydrated = 0;
+    for (const agent of channels) {
+      if (!agent?.id || !agent?.service_type || !ctx.runtimes[agent.service_type]) continue;
+      const agentHostId = getRuntimeHostIdFromPayload(agent);
+      if (agentHostId && agentHostId !== hostId) {
+        debugError('ticlawk', 'binding.host-mismatch', {
+          agentId: agent.id,
+          hostId,
+          runtime_host_id: agentHostId,
+        });
+        continue;
+      }
+      try {
+        await ctx.cacheBinding(buildBindingFromChannelSnapshot(agent));
+        hydrated += 1;
+      } catch (err) {
+        debugError('ticlawk', 'binding.hydrate-failed', {
+          agentId: agent.id,
+          error: err?.message || 'unknown error',
+        });
+      }
+    }
+    const pruned = await pruneDeletedBindings(channels, reason);
+    debugLog('ticlawk', 'binding.refresh-ok', {
+      reason,
+      hydrated,
+      pruned,
+      durationMs: Date.now() - startedAt,
+      wakeToRefreshMs: String(reason || '').startsWith('wake') && lastBindingsWakeAt
+        ? Date.now() - lastBindingsWakeAt
+        : null,
+    });
+    return hydrated;
+  }
+
+  async function releaseBlockedRows(agentId, messages, reason) {
+    for (const msg of messages) {
+      if (!msg?.message_id) continue;
+      try {
+        await api.releaseMessage(msg.message_id, hostId);
+      } catch (err) {
+        debugError('ticlawk', 'claim.blocked-release-failed', {
+          reason,
+          agentId,
+          messageId: msg.message_id,
+          error: err?.message || 'unknown error',
+        });
+      }
+    }
+  }
+
+  async function drainPendingOnce(reason) {
+    const startedAt = Date.now();
+    const excludedChannelIds = [...processingChannels.keys()];
+    let data = [];
+    if (updateRequired?.updateRequired && !isLowFrequencyRecovery(reason)) {
+      debugLog('ticlawk', 'claim.paused-update-required', {
+        reason,
+        hostId,
+        currentAgentFreewayVersion: updateRequired.currentAgentFreewayVersion || api.getAgentFreewayVersion(),
+        requiredAgentFreewayVersion: updateRequired.requiredAgentFreewayVersion || null,
+      });
+      return { failed: true, claimed: 0, launched: 0, updateRequired: true };
+    }
+    try {
+      data = await api.claimPendingMessages(hostId, 5, excludedChannelIds);
+      clearUpdateRequired('claim');
+    } catch (err) {
+      if (api.isUpdateRequiredError(err)) {
+        recordUpdateRequired(err, 'claim');
+        return { failed: true, claimed: 0, launched: 0, updateRequired: true };
+      }
+      debugError('ticlawk', 'claim.failed', {
+        reason,
+        hostId,
+        excludedChannelCount: excludedChannelIds.length,
+        durationMs: Date.now() - startedAt,
+        error: err?.message || 'unknown error',
+      });
+      return { failed: true, claimed: 0, launched: 0 };
+    }
+
+    const claimed = Array.isArray(data) ? data.length : 0;
+    debugLog('ticlawk', 'claim.result', {
+      reason,
+      hostId,
+      returnedRows: claimed,
+      excludedChannelCount: excludedChannelIds.length,
+      durationMs: Date.now() - startedAt,
+      wakeToClaimMs: String(reason || '').startsWith('wake') && lastJobsWakeAt
+        ? Date.now() - lastJobsWakeAt
+        : null,
+    });
+    if (String(reason || '').startsWith('audit') && claimed > 0) {
+      debugError('ticlawk', 'audit.found-jobs', {
+        reason,
+        returnedRows: claimed,
+        excludedChannelCount: excludedChannelIds.length,
+      });
+    }
+
+    if (!Array.isArray(data) || data.length === 0) {
+      return { failed: false, claimed: 0, launched: 0 };
+    }
+
+    const grouped = new Map();
+    for (const msg of data) {
+      const agentId = getAgentIdFromPayload(msg) || '__default__';
+      const bucket = grouped.get(agentId) || [];
+      bucket.push(msg);
+      grouped.set(agentId, bucket);
+    }
+
+    let launched = 0;
+    for (const [agentId, messages] of grouped.entries()) {
+      if (processingChannels.has(agentId)) {
+        debugError('ticlawk', 'claim.blocked-claimed-rows', {
+          reason,
+          agentId,
+          blockedRows: messages.length,
+        });
+        await releaseBlockedRows(agentId, messages, reason);
+        continue;
+      }
+      const run = processPendingMessagesForAgent(agentId, messages)
+        .catch(() => {})
+        .finally(() => {
+          processingChannels.delete(agentId);
+          void requestDrain('channel.completed');
+        });
+      processingChannels.set(agentId, run);
+      launched += messages.length;
+    }
+
+    return { failed: false, claimed: data.length, launched };
+  }
+
+  async function runDrain(reason) {
+    let totalClaimed = 0;
+    let iterations = 0;
+    while (true) {
+      iterations += 1;
+      const result = await drainPendingOnce(reason);
+      totalClaimed += result.claimed;
+      if (result.failed || result.claimed === 0 || result.launched === 0) {
+        break;
+      }
+    }
+    return { totalClaimed, iterations };
+  }
+
+  function requestDrain(reason) {
+    if (drainPromise) {
+      drainRequested = true;
+      return drainPromise;
+    }
+    drainPromise = (async () => {
+      let currentReason = reason;
+      do {
+        drainRequested = false;
+        await runDrain(currentReason);
+        currentReason = 'drain.requested-again';
+      } while (drainRequested);
+    })().finally(() => {
+      drainPromise = null;
+    });
+    return drainPromise;
+  }
+
+  function scheduleDrain(reason) {
+    jobsWakeTimer = clearDebounce(jobsWakeTimer);
+    jobsWakeTimer = setTimeout(() => {
+      jobsWakeTimer = null;
+      void requestDrain(reason);
+    }, JOBS_WAKE_DEBOUNCE_MS);
+    jobsWakeTimer.unref?.();
+  }
+
+  function scheduleRefreshAndDrain(reason) {
+    bindingsWakeTimer = clearDebounce(bindingsWakeTimer);
+    bindingsWakeTimer = setTimeout(() => {
+      bindingsWakeTimer = null;
+      void refreshBindings(reason)
+        .then(() => requestDrain(reason))
+        .catch(() => {});
+    }, BINDINGS_WAKE_DEBOUNCE_MS);
+    bindingsWakeTimer.unref?.();
+  }
+
+  function handleWakeEvent(event) {
+    wakeState.lastEventAt = new Date().toISOString();
+    if (event?.type === 'hello') {
+      void refreshBindings('wake.hello')
+        .then(() => requestDrain('wake.hello'))
+        .catch(() => {});
+      return;
+    }
+    if (event?.type === 'jobs.available') {
+      lastJobsWakeAt = Date.now();
+      debugLog('ticlawk-wake', 'jobs.available', {
+        agentId: event.agent_id || null,
+        reason: event.reason || null,
+      });
+      scheduleDrain('wake.jobs.available');
+      return;
+    }
+    if (event?.type === 'bindings.changed') {
+      lastBindingsWakeAt = Date.now();
+      debugLog('ticlawk-wake', 'bindings.changed', {
+        agentId: event.agent_id || null,
+        reason: event.reason || null,
+      });
+      scheduleRefreshAndDrain('wake.bindings.changed');
+      return;
+    }
+    if (event?.type === 'auth.revoked') {
+      wakeState.lastError = 'auth revoked';
+      debugError('ticlawk-wake', 'auth.revoked', {});
+    }
+  }
+
+  function handleWakeStatus(status) {
+    wakeState.connected = Boolean(status.connected);
+    wakeState.lastStatus = status.state || wakeState.lastStatus;
+    if (status.state === 'connected') {
+      wakeState.lastConnectedAt = new Date().toISOString();
+      wakeState.lastError = null;
+    }
+    if (status.state === 'closed') {
+      wakeState.lastCloseAt = new Date().toISOString();
+      wakeState.lastCloseCode = status.code ?? null;
+      wakeState.lastCloseReason = status.reason || null;
+    }
+    if (status.error) wakeState.lastError = status.error;
+    if (status.state === 'reconnecting') wakeState.reconnectCount += 1;
+    debugLog('ticlawk-wake', 'status', {
+      state: status.state,
+      connected: status.connected,
+      attempt: status.attempt || null,
+      delayMs: status.delayMs || null,
+      code: status.code || null,
+      reason: status.reason || null,
+      wasConnected: status.wasConnected ?? null,
+      error: status.error || null,
+    });
+  }
+
+  function connectWakeSocket() {
+    connectorSocket = new TiclawkWakeClient({
+      getUrl: api.getConnectorWsUrl,
+      getApiKey: api.getApiKey,
+      onEvent: handleWakeEvent,
+      onStatus: handleWakeStatus,
+      logger: { debugLog, debugError },
+    });
+    connectorSocket.start();
+  }
+
+  function restartWakeSocket(reason) {
+    if (connectorSocket) {
+      connectorSocket.stop();
+    }
+    debugLog('ticlawk-wake', 'restart', { reason });
+    connectWakeSocket();
+  }
+
+  function startAuditTimers() {
+    recoveryTimer = setInterval(() => {
+      void requestDrain('audit.recovery');
+    }, RECOVERY_AUDIT_INTERVAL_MS);
+    recoveryTimer.unref?.();
+    bindingAuditTimer = setInterval(() => {
+      void refreshBindings('audit.bindings');
+    }, BINDING_AUDIT_INTERVAL_MS);
+    bindingAuditTimer.unref?.();
+  }
+
+  async function finishPairing(resolved, pairData) {
+    const apiKey = pairData.connector_api_key || pairData.apiKey || pairData.api_key;
+    persistApiCredential(apiKey);
+    if (pairData.connector_ws_url) {
+      persistConfig({ [TICLAWK_CONNECTOR_WS_URL]: pairData.connector_ws_url });
+    }
+    const pairedIdentity = maskIdentity(pairData.user || pairData);
+    if (pairedIdentity.userId) {
+      saveAndActivateProfile({
+        adapter: 'ticlawk',
+        userId: pairedIdentity.userId,
+        config: loadPersistentConfig(),
+        meta: pairedIdentity,
+      });
+    }
+    if (connectorSocket) {
+      restartWakeSocket('connect.paired');
+    }
+
+    const bindingId = pairData.agent_id || pairData.agentId;
+    if (!bindingId) {
+      throw new Error('pairing did not return agent_id');
+    }
+    const runtimeMeta = pairData.runtime_meta || resolved.runtimeMeta;
+    const binding = await ctx.upsertBinding({
+      id: bindingId,
+      adapter: 'ticlawk',
+      targetKey: bindingId,
+      targetMeta: {
+        agentId: bindingId,
+        runtime_host_id: hostId,
+        binding_key: pairData.binding_key || null,
+      },
+      runtime_host_id: hostId,
+      runtime_host_label: hostLabel,
+      runtime: resolved.runtime,
+      runtimeMeta,
+      displayName: resolved.displayName,
+      status: 'connected',
+    });
+    return {
+      statusCode: 200,
+      body: {
+        ok: true,
+        agentId: binding.id,
+        serviceType: resolved.runtime,
+        name: binding.displayName,
+        bindingKey: pairData.binding_key || null,
+        user: pairedIdentity,
+      },
+    };
+  }
+
+  async function connectWithQrPairing(payload) {
+    const autoRuntime = Boolean(payload?.autoRuntime);
+    const runtimeOptions = autoRuntime ? await buildAutoRuntimeOptions(ctx, payload) : [];
+    if (autoRuntime && runtimeOptions.length === 0) {
+      throw new Error('No supported local agent runtime found in this terminal. Install or sign in to Codex, Claude Code, OpenCode, or pi, then try again.');
+    }
+    const resolved = autoRuntime ? null : await ctx.resolveRuntimeBinding(payload);
+    const runtimeMeta = resolved?.runtimeMeta || {};
+    const workdir = getRuntimeWorkdir(runtimeMeta) || getRuntimeWorkdir(payload) || process.cwd();
+    const clientSecret = makeClientSecret();
+    const created = await api.createPairingSession({
+      client: 'ticlawk',
+      client_version: api.getAgentFreewayVersion(),
+      host_id: hostId,
+      host_label: hostLabel,
+      ...(autoRuntime ? { runtime_options: runtimeOptions } : { runtime: resolved.runtime }),
+      workdir,
+      display_name: resolved?.displayName || basename(workdir) || 'Agent',
+      challenge_hash: sha256Hex(clientSecret),
+    });
+    if (!created?.ok) {
+      return {
+        statusCode: created?.statusCode || 400,
+        body: created || { ok: false, error: 'ticlawk pairing create failed' },
+      };
+    }
+    if (!created.pairing_id || !created.display_code || !created.qr_payload) {
+      return connectError(502, 'ticlawk pairing create response was incomplete');
+    }
+
+    printPairingChallenge(created);
+    try {
+      const approved = await waitForPairingApproval({
+        pairingId: created.pairing_id,
+        clientSecret,
+        pollAfterMs: Number(created.poll_after_ms || 1500),
+        expiresAt: created.expires_at,
+      });
+      const approvedRuntime = approved.runtime || approved.selected_runtime;
+      const approvedOption = runtimeOptions.find((option) => option.runtime === approvedRuntime) || null;
+      const finalResolved = resolved || {
+        runtime: approvedRuntime || approvedOption?.runtime,
+        displayName: approved.display_name || approvedOption?.display_name || runtimeLabel(approvedRuntime),
+        runtimeMeta: approved.runtime_meta || approvedOption?.runtime_meta || {},
+      };
+      if (!finalResolved.runtime) {
+        throw new Error('ticlawk pairing did not return a selected runtime');
+      }
+      return await finishPairing.call(this, finalResolved, {
+        ...created,
+        ...approved,
+        binding_key: approved.binding_key || created.binding_key || null,
+      });
+    } catch (err) {
+      await api.cancelPairingSession({
+        pairing_id: created.pairing_id,
+        client_secret: clientSecret,
+      });
+      throw err;
+    }
+  }
+
+  return {
+    id: 'ticlawk',
+
+    async start() {
+      try {
+        const recovered = await api.recoverClaimedMessages(hostId);
+        if (recovered?.recoveredCount) {
+          debugLog('ticlawk', 'message.recovered', {
+            recoveredCount: recovered.recoveredCount,
+            hostId,
+          });
+        }
+      } catch (err) {
+        if (api.isUpdateRequiredError(err)) {
+          recordUpdateRequired(err, 'recover');
+        }
+        debugError('ticlawk', 'message.recover-failed', {
+          hostId,
+          error: err?.message || 'unknown error',
+        });
+      }
+
+      await refreshBindings('startup');
+      await requestDrain('startup');
+      connectWakeSocket();
+      startAuditTimers();
+    },
+
+    async refreshBindings() {
+      return refreshBindings('manual');
+    },
+
+    async health() {
+      const config = loadPersistentConfig();
+      const runtimeHealthEntries = await Promise.all(Object.entries(ctx.runtimes || {})
+        .filter(([, runtime]) => typeof runtime?.health === 'function')
+        .map(async ([name, runtime]) => [name, await runtime.health()]));
+      const runtimesHealth = Object.fromEntries(runtimeHealthEntries);
+      const codexHealth = runtimesHealth.codex || {};
+      return {
+        apiKey: Boolean(process.env[TICLAWK_CONNECTOR_API_KEY] || config[TICLAWK_CONNECTOR_API_KEY] || config[LEGACY_TICLAWK_API_KEY]),
+        wakeUrl: api.getConnectorWsUrl(),
+        wakeConnected: Boolean(connectorSocket?.isConnected()),
+        wakeLastStatus: wakeState.lastStatus,
+        wakeLastEventAt: wakeState.lastEventAt,
+        wakeLastError: wakeState.lastError,
+        wakeLastConnectedAt: wakeState.lastConnectedAt,
+        wakeLastCloseAt: wakeState.lastCloseAt,
+        wakeLastCloseCode: wakeState.lastCloseCode,
+        wakeLastCloseReason: wakeState.lastCloseReason,
+        wakeReconnectCount: wakeState.reconnectCount,
+        ...getUpdateRequiredHealth(),
+        runtimes: runtimesHealth,
+        codexAvailable: codexHealth.available,
+        codexPath: codexHealth.path || null,
+        codexVersion: codexHealth.version || null,
+        gatewayConnected: ctx.runtimes.openclaw?.isReady?.() || undefined,
+      };
+    },
+
+    async connect(payload) {
+      const config = loadPersistentConfig();
+      const connectCode = String(payload?.code || config.TICLAWK_SETUP_CODE || '').trim();
+      if (!connectCode) {
+        try {
+          return await connectWithQrPairing.call(this, payload);
+        } catch (err) {
+          return connectError(err?.status || 500, err.message);
+        }
+      }
+
+      try {
+        const resolved = await ctx.resolveRuntimeBinding(payload);
+        const runtimeMeta = resolved.runtimeMeta;
+        let currentIdentity = null;
+        const activeProfile = getActiveProfile();
+        if (activeProfile?.adapter === 'ticlawk') {
+          currentIdentity = readProfileMeta(activeProfile.adapter, activeProfile.userId) || {
+            userId: activeProfile.userId,
+          };
+        } else if (config[TICLAWK_CONNECTOR_API_KEY] || config[LEGACY_TICLAWK_API_KEY]) {
+          try {
+            const me = await api.getMe();
+            if (me?.userId || me?.user_id) {
+              currentIdentity = maskIdentity(me);
+              ensureLegacyProfile({
+                adapter: 'ticlawk',
+                userId: currentIdentity.userId,
+                meta: currentIdentity,
+              });
+            }
+          } catch {}
+        }
+
+        let previewIdentity = null;
+        try {
+          const preview = await api.pairPreview({ code: connectCode });
+          if (preview?.ok) {
+            previewIdentity = maskIdentity(preview);
+          } else if (preview?.userId || preview?.user_id) {
+            previewIdentity = maskIdentity(preview);
+          }
+        } catch {}
+
+        if (currentIdentity?.userId && !previewIdentity?.userId && !payload.switchUser) {
+          return {
+            statusCode: 409,
+            body: {
+              ok: false,
+              code: 'ticlawk_pairing_user_unverified',
+              currentUser: currentIdentity,
+              error: [
+                'This ticlawk home is already paired to ticlawk user:',
+                ...formatIdentityLines(currentIdentity),
+                '',
+                'Could not verify which ticlawk user owns the new pairing code.',
+                'Refusing to switch users because existing agents may stop processing messages.',
+                '',
+                'If you want to switch user, please rerun this command with --switch-user.',
+              ].join('\n'),
+            },
+          };
+        }
+
+        if (
+          currentIdentity?.userId
+          && previewIdentity?.userId
+          && currentIdentity.userId !== previewIdentity.userId
+          && !payload.switchUser
+        ) {
+          let affectedAgents = [];
+          try {
+            affectedAgents = await api.getAgents({ hostId });
+          } catch {}
+          const message = [
+            'This ticlawk home is already paired to ticlawk user:',
+            ...formatIdentityLines(currentIdentity),
+            '',
+            'The pairing code belongs to a different ticlawk user:',
+            ...formatIdentityLines(previewIdentity),
+            '',
+            'Refusing to switch users because these agents are currently bound to this host:',
+            ...formatAffectedAgents(affectedAgents),
+            '',
+            'Switching would stop this daemon from processing messages for those agents.',
+            '',
+            'If you want to switch user, please rerun this command with --switch-user.',
+          ].join('\n');
+          return {
+            statusCode: 409,
+            body: {
+              ok: false,
+              error: message,
+              code: 'ticlawk_user_mismatch',
+              currentUser: currentIdentity,
+              pairingUser: previewIdentity,
+              affectedAgents,
+            },
+          };
+        }
+
+        const pairData = await api.pair({
+          code: connectCode,
+          name: resolved.displayName,
+          serviceType: resolved.runtime,
+          runtimeMeta,
+          runtime_host_id: hostId,
+          runtime_host_label: hostLabel,
+        });
+        if (!pairData?.ok) {
+          return { statusCode: pairData?.statusCode || 401, body: pairData };
+        }
+        return finishPairing.call(this, resolved, {
+          ...pairData,
+          agent_id: pairData.agentId,
+          connector_api_key: pairData.apiKey,
+        });
+      } catch (err) {
+        return connectError(err?.status || 500, err.message);
+      }
+    },
+
+    async send(binding, outbound) {
+      const localMediaPaths = (outbound.media || [])
+        .filter((item) => item.kind === 'local_path')
+        .map((item) => item.value);
+      await processAndSaveResult({
+        text: outbound.text || '',
+        mediaUrls: localMediaPaths,
+      }, {
+        agentId: binding.id,
+        hostId,
+        agent: binding.runtime,
+        sessionId: getBindingSessionId(binding),
+        runtimeVersion: getRuntimeVersion(binding),
+        turnId: outbound.turnId || outbound.replyToMessageId || null,
+        type: outbound.type || 'agent_message',
+        replyToMessageId: outbound.replyToMessageId || null,
+      });
+    },
+
+    async emitEvent(binding, payload) {
+      if (!payload?.event) return;
+      await api.postEvent({
+        agent: payload.agent,
+        agent_id: binding.id,
+        runtime_host_id: hostId,
+        session_id: payload.sessionId,
+        cwd: payload.cwd || '',
+        runtime_version: getRuntimeVersion(binding),
+        event: payload.event,
+      });
+    },
+
+    async syncBinding(binding) {
+      const updates = {
+        status: binding.status || 'connected',
+        runtime_host_id: hostId,
+        runtime_host_label: hostLabel,
+      };
+      const syncableMeta = buildSyncableRuntimeMeta(binding);
+      if (syncableMeta) {
+        updates.meta = syncableMeta;
+      }
+      try {
+        await api.updateAgent(binding.id, updates);
+      } catch (err) {
+        if (api.isUpdateRequiredError(err)) {
+          recordUpdateRequired(err, 'binding.sync');
+        }
+        debugError('ticlawk', err?.status === 409 ? 'binding.sync-host-mismatch' : 'binding.sync-failed', {
+          agentId: binding.id,
+          hostId,
+          runtime_host_id: getBindingRuntimeHostId(binding) || null,
+          error: err?.message || 'unknown error',
+        });
+        if (err?.status === 409) {
+          throw err;
+        }
+      }
+    },
+  };
+}
+
+export function getTiclawkAuthHelp() {
+  return `ticlawk auth ticlawk --code <6-digit-code> [--api-url <url>]
+
+Options:
+  --code <code>       6-digit setup code from the ticlawk app
+  --api-url <url>     optional ticlawk API base URL override
+`;
+}
+
+export async function runTiclawkAuth(rawArgs) {
+  const args = parseOptionArgs(rawArgs);
+  if (args.help || args.h) {
+    return {
+      statusCode: 200,
+      body: {
+        ok: true,
+        help: getTiclawkAuthHelp(),
+      },
+    };
+  }
+  const code = String(args.code || '').trim();
+  if (!code) {
+    return {
+      statusCode: 400,
+      body: {
+        ok: false,
+        error: 'ticlawk auth requires --code',
+      },
+    };
+  }
+  const updates = {
+    [AF_ADAPTER_KEY]: 'ticlawk',
+    TICLAWK_SETUP_CODE: code,
+  };
+  const apiUrl = String(args['api-url'] || '').trim();
+  if (apiUrl) {
+    updates.TICLAWK_API_URL = apiUrl;
+  }
+  persistConfig(updates);
+  return {
+    statusCode: 200,
+    body: {
+      ok: true,
+      adapter: 'ticlawk',
+      setupCode: 'set',
+      apiUrl: apiUrl || undefined,
+    },
+  };
+}