ticlawk 0.1.12-dev.0

package/src/adapters/ticlawk/wake-client.mjs

@@ -0,0 +1,204 @@
+import WebSocket from 'ws';
+
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 30000;
+
+function parseMessage(data) {
+  const text = Buffer.isBuffer(data) ? data.toString('utf8') : String(data || '');
+  return JSON.parse(text);
+}
+
+function reconnectDelayMs(attempt) {
+  const base = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * (2 ** Math.max(0, attempt - 1)));
+  return Math.floor(base * (0.5 + Math.random()));
+}
+
+export class TiclawkWakeClient {
+  constructor({ getUrl, getApiKey, onEvent, onStatus, logger }) {
+    this.getUrl = getUrl;
+    this.getApiKey = getApiKey;
+    this.onEvent = onEvent;
+    this.onStatus = onStatus;
+    this.logger = logger;
+    this.ws = null;
+    this.stopped = true;
+    this.connected = false;
+    this.reconnectAttempt = 0;
+    this.reconnectTimer = null;
+    this.lastEventAt = null;
+    this.lastError = null;
+    this.currentUrl = '';
+  }
+
+  start() {
+    if (!this.stopped) return;
+    this.stopped = false;
+    this.connect();
+  }
+
+  stop() {
+    this.stopped = true;
+    this.connected = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      try { this.ws.close(); } catch {}
+      this.ws = null;
+    }
+  }
+
+  isConnected() {
+    return this.connected;
+  }
+
+  status() {
+    return {
+      connected: this.connected,
+      url: this.currentUrl,
+      lastEventAt: this.lastEventAt,
+      lastError: this.lastError,
+      reconnectAttempt: this.reconnectAttempt,
+    };
+  }
+
+  emitStatus(state, meta = {}) {
+    this.onStatus?.({
+      state,
+      connected: this.connected,
+      ...meta,
+    });
+  }
+
+  connect() {
+    if (this.stopped) return;
+    const apiKey = String(this.getApiKey?.() || '').trim();
+    this.currentUrl = String(this.getUrl?.() || '').trim();
+    if (!apiKey) {
+      this.lastError = 'missing connector api key';
+      this.emitStatus('error', { error: this.lastError, url: this.currentUrl });
+      this.scheduleReconnect();
+      return;
+    }
+    if (!this.currentUrl) {
+      this.lastError = 'missing connector wake url';
+      this.emitStatus('error', { error: this.lastError });
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.connected = false;
+    this.emitStatus('connecting', { url: this.currentUrl });
+
+    const ws = new WebSocket(this.currentUrl, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+    this.ws = ws;
+
+    ws.on('message', (data) => {
+      let msg;
+      try {
+        msg = parseMessage(data);
+      } catch (err) {
+        this.lastError = `invalid wake message: ${err?.message || String(err)}`;
+        this.logger?.debugError?.('ticlawk-wake', 'message.invalid', {
+          error: this.lastError,
+        });
+        return;
+      }
+      this.handleMessage(msg);
+    });
+
+    ws.on('error', (err) => {
+      this.lastError = err?.message || 'websocket error';
+      this.logger?.debugError?.('ticlawk-wake', 'socket.error', {
+        error: this.lastError,
+      });
+      this.emitStatus('error', { error: this.lastError });
+    });
+
+    ws.on('close', (code, reason) => {
+      const wasConnected = this.connected;
+      this.connected = false;
+      if (this.ws === ws) this.ws = null;
+      if (this.stopped) return;
+      this.emitStatus('closed', {
+        code,
+        reason: reason ? reason.toString('utf8') : '',
+        wasConnected,
+      });
+      this.scheduleReconnect();
+    });
+  }
+
+  handleMessage(msg) {
+    const type = msg?.type || 'unknown';
+    this.lastEventAt = new Date().toISOString();
+
+    if (type === 'hello') {
+      this.connected = true;
+      this.reconnectAttempt = 0;
+      this.lastError = null;
+      this.emitStatus('connected', {
+        protocol: msg.protocol ?? null,
+        connectionId: msg.connection_id || null,
+      });
+      this.onEvent?.(msg);
+      return;
+    }
+
+    if (type === 'heartbeat') {
+      this.send({ type: 'pong', ts: msg.ts || new Date().toISOString() });
+      this.onEvent?.(msg);
+      return;
+    }
+
+    if (type === 'auth.revoked') {
+      this.connected = false;
+      this.lastError = 'auth revoked';
+      this.emitStatus('auth.revoked', { error: this.lastError });
+      this.onEvent?.(msg);
+      this.stop();
+      return;
+    }
+
+    if (type === 'jobs.available' || type === 'bindings.changed') {
+      this.onEvent?.(msg);
+      return;
+    }
+
+    this.logger?.debugLog?.('ticlawk-wake', 'message.ignored', { type });
+  }
+
+  send(payload) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return false;
+    try {
+      this.ws.send(JSON.stringify(payload));
+      return true;
+    } catch (err) {
+      this.lastError = err?.message || 'websocket send failed';
+      this.logger?.debugError?.('ticlawk-wake', 'send.failed', {
+        error: this.lastError,
+      });
+      return false;
+    }
+  }
+
+  scheduleReconnect() {
+    if (this.stopped || this.reconnectTimer) return;
+    this.reconnectAttempt += 1;
+    const delayMs = reconnectDelayMs(this.reconnectAttempt);
+    this.emitStatus('reconnecting', {
+      attempt: this.reconnectAttempt,
+      delayMs,
+    });
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delayMs);
+    this.reconnectTimer.unref?.();
+  }
+}

package/src/core/adapter-registry.mjs

@@ -0,0 +1,50 @@
+import {
+  createTiclawkAdapter,
+  getTiclawkAuthHelp,
+  runTiclawkAuth,
+} from '../adapters/ticlawk/index.mjs';
+import {
+  createTelegramAdapter,
+  getTelegramAuthHelp,
+  runTelegramAuth,
+} from '../adapters/telegram/index.mjs';
+
+const FACTORIES = {
+  ticlawk: createTiclawkAdapter,
+  telegram: createTelegramAdapter,
+};
+
+const AUTH_HANDLERS = {
+  ticlawk: {
+    help: getTiclawkAuthHelp,
+    run: runTiclawkAuth,
+  },
+  telegram: {
+    help: getTelegramAuthHelp,
+    run: runTelegramAuth,
+  },
+};
+
+export function createAdapter(adapterId, ctx) {
+  const factory = FACTORIES[adapterId];
+  if (!factory) {
+    throw new Error(`unsupported adapter: ${adapterId}`);
+  }
+  return factory(ctx);
+}
+
+export function getAdapterAuthHelp(adapterId) {
+  const handler = AUTH_HANDLERS[adapterId];
+  if (!handler?.help) {
+    throw new Error(`unsupported adapter: ${adapterId}`);
+  }
+  return handler.help();
+}
+
+export async function runAdapterAuth(adapterId, rawArgs) {
+  const handler = AUTH_HANDLERS[adapterId];
+  if (!handler?.run) {
+    throw new Error(`unsupported adapter: ${adapterId}`);
+  }
+  return handler.run(rawArgs);
+}

package/src/core/argv.mjs

@@ -0,0 +1,38 @@
+export function splitArgv(argv = []) {
+  const separatorIndex = argv.indexOf('--');
+  if (separatorIndex < 0) {
+    return {
+      mainArgv: [...argv],
+      passthroughArgv: [],
+    };
+  }
+  return {
+    mainArgv: argv.slice(0, separatorIndex),
+    passthroughArgv: argv.slice(separatorIndex + 1),
+  };
+}
+
+export function parseOptionArgs(argv = []) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '-h') {
+      args.help = true;
+      continue;
+    }
+    if (arg === '-y') {
+      args.y = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      const [rawKey, inlineValue] = arg.slice(2).split(/=(.*)/s, 2);
+      const value = inlineValue !== undefined
+        ? inlineValue
+        : argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : true;
+      args[rawKey] = value;
+      continue;
+    }
+    args._.push(arg);
+  }
+  return args;
+}

package/src/core/bindings/store.mjs

@@ -0,0 +1,81 @@
+import { join } from 'node:path';
+import { AF_HOME } from '../config.mjs';
+import { JsonFileStore } from '../store/json-file-store.mjs';
+import { getActiveBindingsPath } from '../profiles.mjs';
+
+const LEGACY_BINDINGS_PATH = join(AF_HOME, 'bindings.json');
+const stores = new Map();
+
+function getStore() {
+  const filePath = getActiveBindingsPath(LEGACY_BINDINGS_PATH);
+  let store = stores.get(filePath);
+  if (!store) {
+    store = new JsonFileStore(filePath, []);
+    stores.set(filePath, store);
+  }
+  return store;
+}
+
+function normalizeBinding(binding) {
+  const now = new Date().toISOString();
+  const hostId = binding.runtime_host_id || binding.targetMeta?.runtime_host_id;
+  const runtimeHostLabel = binding.runtime_host_label || binding.targetMeta?.runtime_host_label;
+  return {
+    id: binding.id || binding.targetKey,
+    adapter: binding.adapter,
+    targetKey: binding.targetKey,
+    targetMeta: binding.targetMeta || {},
+    ...(hostId ? { runtime_host_id: hostId } : {}),
+    ...(runtimeHostLabel ? { runtime_host_label: runtimeHostLabel } : {}),
+    runtime: binding.runtime,
+    runtimeMeta: binding.runtimeMeta || {},
+    displayName: binding.displayName || binding.targetKey,
+    status: binding.status || 'paired',
+    createdAt: binding.createdAt || now,
+    updatedAt: now,
+  };
+}
+
+export async function upsertBinding(binding) {
+  const normalized = normalizeBinding(binding);
+  let saved = normalized;
+  await getStore().update((current) => {
+    const next = Array.isArray(current) ? [...current] : [];
+    const index = next.findIndex((entry) => entry.id === normalized.id);
+    if (index >= 0) {
+      next[index] = {
+        ...next[index],
+        ...normalized,
+        createdAt: next[index].createdAt || normalized.createdAt,
+        updatedAt: normalized.updatedAt,
+      };
+      saved = next[index];
+    } else {
+      next.push(normalized);
+      saved = normalized;
+    }
+    return next;
+  });
+  return saved;
+}
+
+export function listBindings(filter = {}) {
+  const bindings = getStore().read();
+  return bindings.filter((binding) => {
+    if (filter.adapter && binding.adapter !== filter.adapter) return false;
+    if (filter.runtime && binding.runtime !== filter.runtime) return false;
+    return true;
+  });
+}
+
+export function getBinding(bindingId) {
+  return listBindings().find((binding) => binding.id === bindingId) || null;
+}
+
+export function findBindingByTarget(adapter, targetKey) {
+  return listBindings({ adapter }).find((binding) => binding.targetKey === targetKey) || null;
+}
+
+export async function deleteBinding(bindingId) {
+  await getStore().update((current) => current.filter((binding) => binding.id !== bindingId));
+}

package/src/core/bus.mjs

@@ -0,0 +1,91 @@
+import { debugError } from './logger.mjs';
+
+/**
+ * The Bus.
+ *
+ * The Bus is the inbound serialization queue.
+ *
+ * Runtimes register themselves under a name (`claude_code`, `codex`,
+ * `openclaw`, ...). Adapters call `dispatchToAgent` to route an inbound
+ * message into the correct runtime.
+ *
+ * Inbound serialization (adapter → runtime) is enforced per
+ * `(runtimeName, key)` so the same agent session can't be poked
+ * concurrently. The key is opaque to the bus — adapters typically pass a
+ * channel id or a session id.
+ *
+ * Outbound delivery does not go through the bus; runtimes call adapter
+ * methods directly through the runtime context passed in by core.
+ */
+
+export class Bus {
+  constructor() {
+    this._runtimes = new Map(); // name -> async (msg) => any
+    this._inFlight = new Map(); // `${name}:${key}` -> Promise
+    this._listeners = new Map(); // event -> Set<fn>
+  }
+
+  /**
+   * Register a runtime handler under `name`.
+   * `handler(msg)` is invoked by `dispatchToAgent` and may return a
+   * Promise that resolves when the runtime has handled the message.
+   */
+  registerRuntime(name, handler) {
+    if (typeof handler !== 'function') {
+      throw new Error(`Bus.registerRuntime: handler for "${name}" must be a function`);
+    }
+    this._runtimes.set(name, handler);
+  }
+
+  hasRuntime(name) {
+    return this._runtimes.has(name);
+  }
+
+  /**
+   * Route an inbound message to a runtime, serialized per
+   * `(runtimeName, key)`. Subsequent calls with the same key wait for
+   * the previous one to settle (resolved or rejected).
+   */
+  async dispatchToAgent(runtimeName, key, msg) {
+    const handler = this._runtimes.get(runtimeName);
+    if (!handler) {
+      throw new Error(`Bus.dispatchToAgent: no runtime registered: ${runtimeName}`);
+    }
+
+    const lockKey = `${runtimeName}:${key || ''}`;
+    const prev = this._inFlight.get(lockKey) || Promise.resolve();
+    const next = prev.catch(() => undefined).then(() => handler(msg));
+    this._inFlight.set(lockKey, next);
+    try {
+      return await next;
+    } finally {
+      if (this._inFlight.get(lockKey) === next) {
+        this._inFlight.delete(lockKey);
+      }
+    }
+  }
+  on(event, fn) {
+    if (!this._listeners.has(event)) this._listeners.set(event, new Set());
+    this._listeners.get(event).add(fn);
+  }
+
+  off(event, fn) {
+    const set = this._listeners.get(event);
+    if (set) set.delete(fn);
+  }
+
+  emit(event, payload) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const fn of set) {
+      try {
+        fn(payload);
+      } catch (err) {
+        debugError('bus', 'listener threw during emit', {
+          event,
+          error: err?.message || String(err),
+        });
+      }
+    }
+  }
+}

package/src/core/config.mjs

@@ -0,0 +1,203 @@
+/**
+ * Persistent ticlawk configuration.
+ *
+ * Owns the on-disk paths under ~/.ticlawk/ and the dotenv-formatted
+ * `.config` file. Importing this module triggers a one-time dotenv load,
+ * so it MUST be imported before any module that reads `process.env` at
+ * module-eval time.
+ */
+
+import dotenv from 'dotenv';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { RUNTIME_DEFINITIONS, normalizeServiceType } from './runtime-registry.mjs';
+
+const DEFAULT_TICLAWK_HOME = join(homedir(), '.ticlawk');
+const LEGACY_AGENT_FREEWAY_HOME = join(homedir(), '.agent-freeway');
+
+function resolveTiclawkHome() {
+  if (process.env.TICLAWK_HOME) return process.env.TICLAWK_HOME;
+  if (process.env.AGENT_FREEWAY_HOME) return process.env.AGENT_FREEWAY_HOME;
+  if (existsSync(DEFAULT_TICLAWK_HOME)) return DEFAULT_TICLAWK_HOME;
+  if (existsSync(LEGACY_AGENT_FREEWAY_HOME)) return LEGACY_AGENT_FREEWAY_HOME;
+  return DEFAULT_TICLAWK_HOME;
+}
+
+export const AF_HOME = resolveTiclawkHome();
+export const AF_CONFIG_PATH = join(AF_HOME, '.config');
+export const AF_LOG_PATH = join(AF_HOME, 'ticlawk.log');
+export const AF_CRASH_LOG_PATH = join(AF_HOME, 'ticlawk-crash.log');
+export const AF_ADAPTER_KEY = 'AF_ADAPTER';
+export const AF_STREAMING_KEY = 'AF_STREAMING';
+export const AF_STREAMING_RUNTIME_KEYS = Object.fromEntries(
+  RUNTIME_DEFINITIONS
+    .filter((runtime) => runtime.streamingEnvKey)
+    .map((runtime) => [runtime.name, runtime.streamingEnvKey])
+);
+export const TICLAWK_CONNECTOR_API_KEY = 'TICLAWK_CONNECTOR_API_KEY';
+export const TICLAWK_CONNECTOR_WS_URL = 'TICLAWK_CONNECTOR_WS_URL';
+export const LEGACY_TICLAWK_API_KEY = 'TICLAWK_API_KEY';
+export const RUNTIME_EXECUTABLE_CONFIG_KEYS = Object.fromEntries(
+  RUNTIME_DEFINITIONS
+    .filter((runtime) => runtime.executableConfigKey)
+    .map((runtime) => [runtime.name, runtime.executableConfigKey])
+);
+export const SUPPORTED_ADAPTERS = ['ticlawk', 'telegram'];
+// Public CLI keys stay kebab/dotted for usability; the persisted .config file
+// stores env-style names because systemd/launchd load it directly.
+export const ADAPTER_CONFIG_KEYS = {
+  'telegram.bot-token': 'TELEGRAM_BOT_TOKEN',
+  'ticlawk.connector-api-key': TICLAWK_CONNECTOR_API_KEY,
+  // Backward-compatible CLI alias. This intentionally maps to the connector
+  // key instead of the generic publisher-facing TICLAWK_API_KEY name.
+  'ticlawk.api-key': TICLAWK_CONNECTOR_API_KEY,
+  'ticlawk.api-url': 'TICLAWK_API_URL',
+  'ticlawk.connector-ws-url': TICLAWK_CONNECTOR_WS_URL,
+};
+
+export function normalizeAdapterName(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/[-\s]+/g, '_');
+  if (!normalized) return null;
+  if (SUPPORTED_ADAPTERS.includes(normalized)) return normalized;
+  return null;
+}
+
+export function getConfiguredAdapter(config = null) {
+  const source = config || loadPersistentConfig();
+  return normalizeAdapterName(source[AF_ADAPTER_KEY]) || 'ticlawk';
+}
+
+export function normalizeAdapterConfigTarget(target) {
+  const normalized = String(target || '').trim().toLowerCase();
+  const configKey = ADAPTER_CONFIG_KEYS[normalized];
+  if (!configKey) return null;
+  return {
+    key: normalized,
+    configKey,
+  };
+}
+
+export function normalizeRuntimeConfigTarget(target) {
+  const normalized = String(target || '').trim().toLowerCase();
+  const match = normalized.match(/^runtimes\.([a-z0-9_-]+)\.path$/);
+  if (!match) return null;
+  const runtimeName = normalizeServiceType(match[1]) || match[1].replace(/-/g, '_');
+  const configKey = RUNTIME_EXECUTABLE_CONFIG_KEYS[runtimeName];
+  if (!configKey) return null;
+  return {
+    key: `runtimes.${runtimeName}.path`,
+    runtimeName,
+    configKey,
+  };
+}
+
+export function getRuntimeExecutableConfig(runtimeName, config = null) {
+  const configKey = RUNTIME_EXECUTABLE_CONFIG_KEYS[runtimeName];
+  if (!configKey) return null;
+  const source = config || loadPersistentConfig();
+  return source[configKey] || null;
+}
+
+dotenv.config({ path: AF_CONFIG_PATH, quiet: true });
+
+export function loadPersistentConfig() {
+  if (!existsSync(AF_CONFIG_PATH)) return {};
+  try {
+    return dotenv.parse(readFileSync(AF_CONFIG_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function persistConfig(updates) {
+  const current = loadPersistentConfig();
+  const next = { ...current, ...updates };
+  const lines = [
+    '# Persistent ticlawk config',
+    ...Object.entries(next)
+      .filter(([, value]) => value !== undefined && value !== null && value !== '')
+      .map(([key, value]) => `${key}=${String(value)}`),
+  ];
+
+  mkdirSync(dirname(AF_CONFIG_PATH), { recursive: true });
+  writeFileSync(AF_CONFIG_PATH, `${lines.join('\n')}\n`, { mode: 0o600 });
+  for (const [key, value] of Object.entries(updates || {})) {
+    if (value === undefined || value === null || value === '') {
+      delete process.env[key];
+      continue;
+    }
+    process.env[key] = String(value);
+  }
+}
+
+export function migrateLegacyTiclawkConnectorKey() {
+  const current = loadPersistentConfig();
+  const legacyKey = current[LEGACY_TICLAWK_API_KEY];
+  if (!legacyKey) return false;
+
+  const updates = {
+    [LEGACY_TICLAWK_API_KEY]: '',
+  };
+  if (!current[TICLAWK_CONNECTOR_API_KEY]) {
+    updates[TICLAWK_CONNECTOR_API_KEY] = legacyKey;
+  }
+
+  persistConfig(updates);
+  delete process.env[LEGACY_TICLAWK_API_KEY];
+  return true;
+}
+
+migrateLegacyTiclawkConnectorKey();
+
+function parseBooleanish(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'on', 'yes'].includes(normalized)) return true;
+  if (['0', 'false', 'off', 'no'].includes(normalized)) return false;
+  return null;
+}
+
+export function normalizeStreamingTarget(target) {
+  const normalized = String(target || '').trim().toLowerCase();
+  if (normalized === 'streaming') {
+    return { key: 'streaming', scope: 'default', configKey: AF_STREAMING_KEY };
+  }
+  if (normalized.startsWith('streaming.')) {
+    const runtimeName = normalizeServiceType(normalized.slice('streaming.'.length));
+    if (AF_STREAMING_RUNTIME_KEYS[runtimeName]) {
+      return { key: `streaming.${runtimeName}`, scope: runtimeName, configKey: AF_STREAMING_RUNTIME_KEYS[runtimeName] };
+    }
+  }
+  return null;
+}
+
+export function getStreamingMode(runtimeName, config = null) {
+  const source = config || loadPersistentConfig();
+  const defaultMode = parseBooleanish(source[AF_STREAMING_KEY]);
+  const runtimeKey = AF_STREAMING_RUNTIME_KEYS[runtimeName];
+  const runtimeMode = runtimeKey ? parseBooleanish(source[runtimeKey]) : null;
+  if (runtimeMode !== null) return runtimeMode;
+  if (defaultMode !== null) return defaultMode;
+  return true;
+}
+
+export function getStreamingConfigView(config = null) {
+  const source = config || loadPersistentConfig();
+  const defaultMode = getStreamingMode('__default__', source);
+  const view = {
+    streaming: {
+      value: defaultMode,
+      inherited: false,
+    },
+  };
+  for (const runtime of RUNTIME_DEFINITIONS) {
+    const runtimeKey = AF_STREAMING_RUNTIME_KEYS[runtime.name];
+    if (!runtimeKey) continue;
+    view[`streaming.${runtime.name}`] = {
+      value: getStreamingMode(runtime.name, source),
+      inherited: parseBooleanish(source[runtimeKey]) === null,
+    };
+  }
+  return view;
+}