ticlawk 0.1.12-dev.0

package/src/core/runtime-support.mjs

@@ -0,0 +1,197 @@
+import { getStreamingMode } from './config.mjs';
+const ERROR_MAX_CHARS = 500;
+const DEFAULT_DELTA_FLUSH_MS = 250;
+const DEFAULT_DELTA_FLUSH_CHARS = 64;
+
+function truncateError(text) {
+  if (!text) return null;
+  const trimmed = String(text).trim();
+  if (trimmed.length <= ERROR_MAX_CHARS) return trimmed;
+  return `${trimmed.slice(0, ERROR_MAX_CHARS)}…`;
+}
+
+function runtimeContextLines(binding, info = {}) {
+  const meta = binding?.runtimeMeta || {};
+  const lines = [];
+  if (meta.sessionId) lines.push(`Session: ${meta.sessionId}`);
+  if (info.turnId) lines.push(`Turn: ${info.turnId}`);
+  if (meta.cwd || meta.workdir) lines.push(`Workdir: ${meta.cwd || meta.workdir}`);
+  return lines;
+}
+
+export function isRuntimeGatewayFailure(info) {
+  return info?.kind === 'gateway-error';
+}
+
+function buildCodexGatewayFailureText({ binding, info, seconds }) {
+  const details = [
+    truncateError(info?.errorMessage),
+    info?.additionalDetails ? `Details: ${truncateError(info.additionalDetails)}` : null,
+  ].filter(Boolean);
+  const context = runtimeContextLines(binding, info);
+  return [
+    `⚠️ Codex returned an app-server error after ${seconds}s.`,
+    details.length ? details.join('\n') : null,
+    'Your message reached ticlawk, but Codex failed while running this session. Reconnect or reset this Codex agent session, then resend your message.',
+    context.length ? context.join('\n') : null,
+  ].filter(Boolean).join('\n\n');
+}
+
+export function shouldStreamRuntime(runtimeName, runtime) {
+  return Boolean(runtime?.runTurnStream) && getStreamingMode(runtimeName);
+}
+
+export async function sendAdapterMessage(adapter, binding, payload) {
+  await adapter.send(binding, payload);
+}
+
+export async function sendResult(adapter, binding, inbound, result) {
+  if (!result?.text && (!result?.mediaUrls || result.mediaUrls.length === 0)) return;
+  await sendAdapterMessage(adapter, binding, {
+    type: 'assistant',
+    text: result.text || '',
+    media: result.media || [],
+    turnId: inbound.messageId || result?.turnId || null,
+    replyToMessageId: inbound.messageId || null,
+  });
+}
+
+export async function reportSubprocessFailure({ adapter, binding, inbound, runtimeName, info }) {
+  if (!info || info.ok) return;
+  const seconds = ((info.durationMs || 0) / 1000).toFixed(1);
+  if (runtimeName === 'Codex' && isRuntimeGatewayFailure(info)) {
+    await sendAdapterMessage(adapter, binding, {
+      type: 'assistant',
+      text: buildCodexGatewayFailureText({ binding, info, seconds }),
+      media: [],
+      turnId: inbound?.messageId || null,
+      replyToMessageId: inbound?.messageId || null,
+    });
+    return;
+  }
+
+  let summary;
+  if (info.kind === 'killed') {
+    summary = `⚠️ ${runtimeName} was killed by signal ${info.signal} after ${seconds}s.`;
+  } else if (info.kind === 'spawn-failed') {
+    summary = `⚠️ ${runtimeName} failed to spawn: ${info.error || 'unknown error'}.`;
+  } else if (info.kind === 'gateway-timeout') {
+    summary = `⚠️ ${runtimeName} did not respond after ${seconds}s (timeout).`;
+  } else if (info.kind === 'gateway-error') {
+    summary = `⚠️ ${runtimeName} returned an error after ${seconds}s.`;
+  } else if (typeof info.code === 'number') {
+    summary = `⚠️ ${runtimeName} exited with code ${info.code} after ${seconds}s.`;
+  } else {
+    summary = `⚠️ ${runtimeName} failed after ${seconds}s.`;
+  }
+  const detail = truncateError(info.errorMessage);
+  const text = detail ? `${summary}\n\n${detail}` : `${summary}\n\nCheck ~/.ticlawk/ticlawk.log on the host for details.`;
+  await sendAdapterMessage(adapter, binding, {
+    type: 'assistant',
+    text,
+    media: [],
+    turnId: inbound?.messageId || null,
+    replyToMessageId: inbound?.messageId || null,
+  });
+}
+
+export function terminalRuntimeFailure(reason = 'runtime failure') {
+  return {
+    ok: false,
+    terminal: true,
+    reason,
+  };
+}
+
+export function isTerminalRuntimeFailure(result) {
+  return Boolean(result && typeof result === 'object' && result.ok === false && result.terminal === true);
+}
+
+export async function updateBindingRuntimeMeta(ctx, binding, runtimeMetaPatch, extra = {}) {
+  return ctx.upsertBinding({
+    ...binding,
+    runtimeMeta: {
+      ...binding.runtimeMeta,
+      ...runtimeMetaPatch,
+    },
+    ...extra,
+  });
+}
+
+export function createDeltaAggregator({
+  flushDelta,
+  flushMs = DEFAULT_DELTA_FLUSH_MS,
+  flushChars = DEFAULT_DELTA_FLUSH_CHARS,
+}) {
+  let buffer = '';
+  let pendingMeta = null;
+  let timer = null;
+  let flushChain = Promise.resolve();
+
+  const clearTimer = () => {
+    if (!timer) return;
+    clearTimeout(timer);
+    timer = null;
+  };
+
+  const startFlush = () => {
+    if (!buffer || typeof flushDelta !== 'function') return flushChain;
+    const text = buffer;
+    const meta = pendingMeta || {};
+    buffer = '';
+    pendingMeta = null;
+    clearTimer();
+    flushChain = flushChain
+      .catch(() => {})
+      .then(() => flushDelta({ text, ...meta }));
+    return flushChain;
+  };
+
+  const scheduleFlush = () => {
+    if (!buffer || timer) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void startFlush();
+    }, flushMs);
+    timer.unref?.();
+  };
+
+  return {
+    push(text, meta = {}) {
+      const normalized = typeof text === 'string' ? text : '';
+      if (!normalized) return;
+
+      const nextMeta = {
+        sessionId: meta.sessionId || null,
+        turnId: meta.turnId || null,
+        cwd: meta.cwd || '',
+      };
+
+      const sameContext = !pendingMeta
+        || (
+          pendingMeta.sessionId === nextMeta.sessionId
+          && pendingMeta.turnId === nextMeta.turnId
+          && pendingMeta.cwd === nextMeta.cwd
+        );
+
+      if (!sameContext && buffer) {
+        void startFlush();
+      }
+
+      pendingMeta = nextMeta;
+      buffer += normalized;
+
+      if (buffer.length >= flushChars) {
+        void startFlush();
+        return;
+      }
+
+      scheduleFlush();
+    },
+
+    async flush() {
+      clearTimer();
+      await startFlush();
+    },
+  };
+}

package/src/core/setup-readiness.mjs

@@ -0,0 +1,86 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname } from 'node:path';
+import { AF_LOG_PATH } from './config.mjs';
+import {
+  commandExists,
+  getCurrentUsername,
+  getSystemdLinger,
+  getWrapperPath,
+  installDaemon,
+} from './daemon-install.mjs';
+
+function pathContains(dir) {
+  return String(process.env.PATH || '')
+    .split(':')
+    .filter(Boolean)
+    .includes(dir);
+}
+
+function printPathActionIfNeeded() {
+  if (commandExists('ticlawk')) return false;
+
+  const wrapperPath = getWrapperPath();
+  const npmBinPath = getNpmGlobalTiclawkBin();
+  const binDir = existsSync(wrapperPath)
+    ? dirname(wrapperPath)
+    : dirname(npmBinPath || '');
+  if (!binDir || binDir === '.') return false;
+  if (pathContains(binDir)) return false;
+
+  console.log();
+  console.log('Action required');
+  console.log();
+  console.log(`${binDir} is not on your PATH.`);
+  console.log('Add this to your shell profile, then open a new shell:');
+  console.log(`  export PATH="${binDir}:$PATH"`);
+  return true;
+}
+
+function getNpmGlobalTiclawkBin() {
+  const result = spawnSync('npm', ['prefix', '-g'], { encoding: 'utf8' });
+  const prefix = String(result.stdout || '').trim();
+  if (!prefix) return '';
+  if (process.platform === 'win32') return `${prefix}\\ticlawk.cmd`;
+  return `${prefix}/bin/ticlawk`;
+}
+
+function printLingerActionIfNeeded() {
+  if (process.platform !== 'linux' || !commandExists('loginctl')) return false;
+  const username = getCurrentUsername();
+  if (getSystemdLinger(username) !== 'no') return false;
+
+  console.log();
+  console.log('Action required');
+  console.log();
+  console.log('ticlawk may stop when you log out because systemd linger is off.');
+  console.log();
+  console.log('Run this command to keep it running after logout and reboot:');
+  console.log(`  sudo loginctl enable-linger ${username}`);
+  return true;
+}
+
+function printReady() {
+  console.log();
+  console.log('Ready:');
+  console.log('  ticlawk health');
+  console.log(`Logs: ${AF_LOG_PATH}`);
+}
+
+export async function runSetupReadiness({ ensureDaemon = false, showActions = true, showReady = true } = {}) {
+  let daemonReady = true;
+  if (ensureDaemon) {
+    daemonReady = await installDaemon();
+  }
+
+  const hasPathAction = showActions ? printPathActionIfNeeded() : false;
+  const hasLingerAction = showActions ? printLingerActionIfNeeded() : false;
+
+  if (daemonReady && !hasPathAction && !hasLingerAction && showReady) {
+    printReady();
+  } else if (hasPathAction || hasLingerAction) {
+    console.log();
+    console.log(`Logs: ${AF_LOG_PATH}`);
+  }
+  return { daemonReady, hasPathAction, hasLingerAction };
+}

package/src/core/store/json-file-store.mjs

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export class JsonFileStore {
+  constructor(filePath, fallbackValue) {
+    this.filePath = filePath;
+    this.fallbackValue = fallbackValue;
+    this._pending = Promise.resolve();
+  }
+
+  read() {
+    if (!existsSync(this.filePath)) return structuredClone(this.fallbackValue);
+    try {
+      return JSON.parse(readFileSync(this.filePath, 'utf8'));
+    } catch {
+      return structuredClone(this.fallbackValue);
+    }
+  }
+
+  async write(nextValue) {
+    return this._queue(() => {
+      mkdirSync(dirname(this.filePath), { recursive: true });
+      const tempPath = `${this.filePath}.tmp`;
+      writeFileSync(tempPath, `${JSON.stringify(nextValue, null, 2)}\n`, { mode: 0o600 });
+      renameSync(tempPath, this.filePath);
+      return nextValue;
+    });
+  }
+
+  async update(updater) {
+    return this._queue(() => {
+      const current = this.read();
+      const next = updater(current);
+      mkdirSync(dirname(this.filePath), { recursive: true });
+      const tempPath = `${this.filePath}.tmp`;
+      writeFileSync(tempPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+      renameSync(tempPath, this.filePath);
+      return next;
+    });
+  }
+
+  async _queue(task) {
+    const run = this._pending.catch(() => undefined).then(task);
+    this._pending = run;
+    return run;
+  }
+}

package/src/core/ticlawk-control.mjs

@@ -0,0 +1,92 @@
+import { Bus } from './bus.mjs';
+import { getConfiguredAdapter } from './config.mjs';
+import { createAdapter } from './adapter-registry.mjs';
+import { getBinding, listBindings, upsertBinding, deleteBinding, findBindingByTarget } from './bindings/store.mjs';
+import { buildRuntimeContext, normalizeServiceType } from './runtime-registry.mjs';
+import * as logger from './logger.mjs';
+import { buildImageMessageFromInbound } from './media/inbound.mjs';
+
+function createResolveRuntimeBinding(runtimes) {
+  return async (payload) => {
+    const requested = normalizeServiceType(payload?.serviceType);
+    const runtime = runtimes[requested];
+    if (!runtime?.resolveBinding) {
+      throw new Error(`runtime does not support binding resolution: ${requested}`);
+    }
+    return runtime.resolveBinding(payload);
+  };
+}
+
+function createUpsertBindingWithSync(runtimes, adapter) {
+  return async (binding) => {
+    const nextBinding = await upsertBinding(binding);
+    const runtime = nextBinding?.runtime ? runtimes[nextBinding.runtime] : null;
+    if (typeof runtime?.onBindingUpdated === 'function') {
+      await runtime.onBindingUpdated(nextBinding, { adapter, logger });
+    }
+    if (typeof adapter.syncBinding === 'function') {
+      await adapter.syncBinding(nextBinding);
+    }
+    return nextBinding;
+  };
+}
+
+function createCacheBinding(runtimes, getAdapter) {
+  return async (binding) => {
+    const nextBinding = await upsertBinding(binding);
+    const runtime = nextBinding?.runtime ? runtimes[nextBinding.runtime] : null;
+    const adapter = getAdapter();
+    if (typeof runtime?.onBindingUpdated === 'function') {
+      await runtime.onBindingUpdated(nextBinding, { adapter, logger });
+    }
+    return nextBinding;
+  };
+}
+
+export async function createTiclawkController(adapterId = getConfiguredAdapter()) {
+  const { runtimes } = await buildRuntimeContext();
+  const resolveRuntimeBinding = createResolveRuntimeBinding(runtimes);
+  let adapter;
+  const cacheBinding = createCacheBinding(runtimes, () => adapter);
+  let syncBinding = async (binding) => {
+    if (!adapter) {
+      throw new Error('adapter not initialized');
+    }
+    return upsertBinding(binding);
+  };
+
+  adapter = createAdapter(adapterId, {
+    bus: new Bus(),
+    runtimes,
+    getBinding,
+    listBindings,
+    deleteBinding,
+    findBindingByTarget,
+    resolveRuntimeBinding,
+    cacheBinding: (binding) => cacheBinding(binding),
+    upsertBinding: (binding) => syncBinding(binding),
+    buildImageMessageFromInbound,
+    logger,
+  });
+  syncBinding = createUpsertBindingWithSync(runtimes, adapter);
+
+  return { adapter };
+}
+
+export async function runTiclawkConnect(payload) {
+  const adapterId = payload?.adapter || getConfiguredAdapter();
+  const { adapter } = await createTiclawkController(adapterId);
+  if (typeof adapter.connect !== 'function') {
+    return {
+      statusCode: 405,
+      body: {
+        ok: false,
+        error: `${adapterId} does not support connect`,
+      },
+    };
+  }
+  return adapter.connect({
+    ...payload,
+    adapter: adapterId,
+  });
+}

package/src/core/uninstall.mjs

@@ -0,0 +1,142 @@
+/**
+ * Service and legacy install cleanup.
+ *
+ * Removes the user service and legacy managed-install files while preserving
+ * ~/.ticlawk by default. The npm package is owned by npm.
+ */
+
+import { existsSync, rmSync, unlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { AF_HOME } from './config.mjs';
+
+function getInstallRoots() {
+  const dataHome = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share');
+  return [join(dataHome, 'ticlawk'), join(dataHome, 'agent-freeway')];
+}
+
+function getWrapperPaths() {
+  return [join(homedir(), '.local', 'bin', 'ticlawk'), join(homedir(), '.local', 'bin', 'agent-freeway')];
+}
+
+function commandExists(command) {
+  return spawnSync('command', ['-v', command], { shell: true, stdio: 'ignore' }).status === 0;
+}
+
+function promptYesNo(question) {
+  if (!process.stdin.isTTY) {
+    return Promise.resolve(false);
+  }
+  process.stdout.write(`${question} `);
+  return new Promise((resolveAnswer) => {
+    process.stdin.setEncoding('utf8');
+    const onData = (chunk) => {
+      process.stdin.removeListener('data', onData);
+      process.stdin.pause();
+      const answer = String(chunk).trim().toLowerCase();
+      resolveAnswer(answer === '' || answer === 'y' || answer === 'yes');
+    };
+    process.stdin.resume();
+    process.stdin.on('data', onData);
+  });
+}
+
+function runBestEffort(label, command, args, { warn = false } = {}) {
+  if (!commandExists(command)) return false;
+  const result = spawnSync(command, args, { stdio: 'ignore' });
+  if (result.status !== 0) {
+    if (warn) console.error(`warning: ${label} failed`);
+    return false;
+  }
+  return true;
+}
+
+function removePath(path, label, { recursive = false } = {}) {
+  if (!existsSync(path)) {
+    console.log(`kept missing ${label}: ${path}`);
+    return;
+  }
+  if (recursive) {
+    rmSync(path, { recursive: true, force: true });
+  } else {
+    unlinkSync(path);
+  }
+  console.log(`removed ${label}: ${path}`);
+}
+
+function uninstallSystemd() {
+  if (process.platform !== 'linux' || !commandExists('systemctl')) return;
+  for (const service of ['ticlawk', 'agent-freeway']) {
+    runBestEffort(`systemd stop ${service}`, 'systemctl', ['--user', 'stop', service]);
+    runBestEffort(`systemd disable ${service}`, 'systemctl', ['--user', 'disable', service]);
+    removePath(join(homedir(), '.config', 'systemd', 'user', `${service}.service`), 'systemd service');
+  }
+  runBestEffort('systemd daemon-reload', 'systemctl', ['--user', 'daemon-reload'], { warn: true });
+}
+
+function uninstallLaunchd() {
+  if (process.platform !== 'darwin' || !commandExists('launchctl')) return;
+  const uid = String(process.getuid?.() || '');
+  for (const label of ['ticlawk', 'agent-freeway', 'com.ticlawk.agent-freeway']) {
+    runBestEffort(`launchd unload ${label}`, 'launchctl', ['bootout', `gui/${uid}/${label}`]);
+  }
+  removePath(join(homedir(), 'Library', 'LaunchAgents', 'ticlawk.plist'), 'launchd plist');
+  removePath(join(homedir(), 'Library', 'LaunchAgents', 'agent-freeway.plist'), 'launchd plist');
+}
+
+export function getUninstallHelp() {
+  return `ticlawk uninstall
+
+Remove the ticlawk service and legacy install files while preserving local data.
+
+Removes:
+  - user service: systemd on Linux, launchd on macOS
+  - CLI wrappers: ~/.local/bin/ticlawk and legacy ~/.local/bin/agent-freeway
+  - legacy managed installs: ~/.local/share/ticlawk and ~/.local/share/agent-freeway
+
+Preserves:
+  - ~/.ticlawk and legacy ~/.agent-freeway
+
+To remove the npm package itself:
+  npm uninstall -g ticlawk
+
+Usage:
+  ticlawk uninstall
+  ticlawk uninstall -y
+`;
+}
+
+export async function runSelfUninstall(skipPrompt) {
+  const installRoots = getInstallRoots();
+  const wrapperPaths = getWrapperPaths();
+
+  console.log('ticlawk uninstall');
+  console.log('will remove the user service');
+  console.log(`will remove legacy install files under: ${installRoots.join(', ')}`);
+  console.log(`will remove CLI wrappers: ${wrapperPaths.join(', ')}`);
+  console.log(`will preserve data directory: ${AF_HOME}`);
+
+  if (!skipPrompt) {
+    if (!process.stdin.isTTY) {
+      console.error('refusing to uninstall non-interactively without -y');
+      process.exit(1);
+    }
+    const ok = await promptYesNo('Uninstall ticlawk? [y/N]');
+    if (!ok) {
+      console.log('aborted');
+      return;
+    }
+  }
+
+  uninstallSystemd();
+  uninstallLaunchd();
+  for (const wrapperPath of wrapperPaths) {
+    removePath(wrapperPath, 'CLI wrapper');
+  }
+  for (const installRoot of installRoots) {
+    removePath(installRoot, 'package install', { recursive: true });
+  }
+  console.log(`preserved data directory: ${AF_HOME}`);
+  console.log('uninstall complete');
+}

package/src/core/update-state.mjs

@@ -0,0 +1,62 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { AF_HOME } from './config.mjs';
+
+export const AF_UPDATE_STATE_PATH = join(AF_HOME, 'update-state.json');
+
+function readJsonFile(filePath) {
+  if (!existsSync(filePath)) return {};
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+function writeJsonFile(filePath, value) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}`;
+  writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tempPath, filePath);
+}
+
+export function readUpdateState() {
+  return readJsonFile(AF_UPDATE_STATE_PATH);
+}
+
+export function writeUpdateState(updates = {}) {
+  const current = readUpdateState();
+  const next = {
+    ...current,
+    ...updates,
+    updatedAt: new Date().toISOString(),
+  };
+  writeJsonFile(AF_UPDATE_STATE_PATH, next);
+  return next;
+}
+
+export function setUpdateRequiredState({ adapter, currentVersion, requiredVersion, autoUpdateStatus, autoUpdateError, lastAutoUpdateAttemptAt }) {
+  const updates = {
+    adapter,
+    updateRequired: true,
+    currentAgentFreewayVersion: currentVersion || null,
+    requiredAgentFreewayVersion: requiredVersion || null,
+  };
+  if (autoUpdateStatus) updates.autoUpdateStatus = autoUpdateStatus;
+  if (autoUpdateError) updates.autoUpdateError = autoUpdateError;
+  if (lastAutoUpdateAttemptAt) updates.lastAutoUpdateAttemptAt = lastAutoUpdateAttemptAt;
+  return writeUpdateState(updates);
+}
+
+export function clearUpdateRequiredState(adapter) {
+  const current = readUpdateState();
+  if (!current.updateRequired) return current;
+  if (adapter && current.adapter && current.adapter !== adapter) return current;
+  return writeUpdateState({
+    adapter: adapter || current.adapter || null,
+    updateRequired: false,
+    autoUpdateStatus: null,
+    autoUpdateError: null,
+    lastClearedAt: new Date().toISOString(),
+  });
+}