ticlawk 0.1.12-dev.0

package/src/core/daemon-install.mjs

@@ -0,0 +1,246 @@
+/**
+ * Managed daemon installation.
+ *
+ * Owns the service files that keep ticlawk running in the background.
+ */
+
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir, userInfo } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AF_CONFIG_PATH, AF_LOG_PATH } from './config.mjs';
+
+function getPackageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+function getBinDir() {
+  return join(homedir(), '.local', 'bin');
+}
+
+export function getWrapperPath() {
+  return join(getBinDir(), 'ticlawk');
+}
+
+export function commandExists(command) {
+  return spawnSync('command', ['-v', command], { shell: true, stdio: 'ignore' }).status === 0;
+}
+
+function dedupePath(raw) {
+  const seen = new Set();
+  const out = [];
+  for (const part of String(raw || '').split(':')) {
+    if (!part || seen.has(part)) continue;
+    seen.add(part);
+    out.push(part);
+  }
+  return out.join(':');
+}
+
+function buildServicePath() {
+  const home = homedir();
+  return dedupePath([
+    getBinDir(),
+    join(home, '.local', 'bin'),
+    join(home, '.npm-global', 'bin'),
+    join(home, '.bun', 'bin'),
+    join(home, '.cargo', 'bin'),
+    '/opt/homebrew/bin',
+    '/opt/homebrew/sbin',
+    '/usr/local/bin',
+    '/usr/local/sbin',
+    process.env.PATH || '',
+    '/usr/bin',
+    '/bin',
+    '/usr/sbin',
+    '/sbin',
+  ].join(':'));
+}
+
+function xmlEscape(value) {
+  return String(value || '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+function run(command, args, { stdio = 'ignore' } = {}) {
+  return spawnSync(command, args, { stdio, encoding: 'utf8' });
+}
+
+function runRequired(label, command, args) {
+  const result = run(command, args, { stdio: 'inherit' });
+  if (result.status !== 0) {
+    throw new Error(`${label} failed`);
+  }
+}
+
+export function getCurrentUsername() {
+  return process.env.USER || userInfo().username;
+}
+
+export function getSystemdLinger(username = getCurrentUsername()) {
+  if (!commandExists('loginctl')) return 'unknown';
+  const result = run('loginctl', ['show-user', username, '-p', 'Linger'], { stdio: 'pipe' });
+  if (result.status !== 0) return 'unknown';
+  const match = String(result.stdout || '').match(/^Linger=(.+)$/m);
+  return match ? match[1].trim() : 'unknown';
+}
+
+function getCliScriptPath() {
+  const scriptPath = process.argv[1] ? resolve(process.argv[1]) : '';
+  if (!scriptPath || !existsSync(scriptPath)) {
+    throw new Error('could not resolve current ticlawk CLI path');
+  }
+  return realpathSync(scriptPath);
+}
+
+function getCliLaunchArgs() {
+  return [process.execPath, getCliScriptPath(), 'start'];
+}
+
+function systemdQuote(value) {
+  const raw = String(value || '');
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(raw)) return raw;
+  return `"${raw.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+function installSystemd() {
+  if (!commandExists('systemctl')) {
+    throw new Error('missing required command: systemctl');
+  }
+
+  const svcDir = join(homedir(), '.config', 'systemd', 'user');
+  const svcFile = join(svcDir, 'ticlawk.service');
+  mkdirSync(svcDir, { recursive: true });
+
+  writeFileSync(svcFile, `[Unit]
+Description=Ticlawk
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${getPackageRoot()}
+EnvironmentFile=-${AF_CONFIG_PATH}
+Environment="PATH=${buildServicePath()}"
+ExecStart=${getCliLaunchArgs().map(systemdQuote).join(' ')}
+Restart=always
+RestartSec=5
+StandardOutput=append:${AF_LOG_PATH}
+StandardError=append:${AF_LOG_PATH}
+
+[Install]
+WantedBy=default.target
+`);
+
+  runRequired('systemd daemon-reload', 'systemctl', ['--user', 'daemon-reload']);
+  run('systemctl', ['--user', 'stop', 'agent-freeway']);
+  run('systemctl', ['--user', 'disable', 'agent-freeway']);
+  runRequired('systemd enable', 'systemctl', ['--user', 'enable', 'ticlawk']);
+
+  if (run('systemctl', ['--user', 'is-active', '--quiet', 'ticlawk']).status === 0) {
+    runRequired('systemd restart', 'systemctl', ['--user', 'restart', 'ticlawk']);
+    console.log(`systemd service restarted: ${svcFile}`);
+  } else {
+    runRequired('systemd start', 'systemctl', ['--user', 'start', 'ticlawk']);
+    console.log(`systemd service started: ${svcFile}`);
+  }
+
+}
+
+function installLaunchd() {
+  if (!commandExists('launchctl')) {
+    throw new Error('missing required command: launchctl');
+  }
+
+  const plistDir = join(homedir(), 'Library', 'LaunchAgents');
+  const legacyLabels = ['agent-freeway', 'com.ticlawk.agent-freeway'];
+  const launchdLabel = 'ticlawk';
+  const plistFile = join(plistDir, `${launchdLabel}.plist`);
+  const uid = String(process.getuid?.() || '');
+  const launchdDomain = `gui/${uid}`;
+  const launchdService = `${launchdDomain}/${launchdLabel}`;
+  mkdirSync(plistDir, { recursive: true });
+
+  writeFileSync(plistFile, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${launchdLabel}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(process.execPath)}</string>
+    <string>${xmlEscape(getCliScriptPath())}</string>
+    <string>start</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(getPackageRoot())}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(AF_LOG_PATH)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(AF_LOG_PATH)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(buildServicePath())}</string>
+  </dict>
+</dict>
+</plist>
+`);
+
+  if (commandExists('plutil')) {
+    runRequired('launchd plist validation', 'plutil', ['-lint', plistFile]);
+  }
+
+  for (const legacyLabel of legacyLabels) {
+    run('launchctl', ['bootout', `${launchdDomain}/${legacyLabel}`]);
+  }
+  if (run('launchctl', ['print', launchdService]).status === 0) {
+    runRequired('launchd kickstart', 'launchctl', ['kickstart', '-k', launchdService]);
+    console.log(`launchd service restarted: ${launchdService}`);
+  } else {
+    runRequired('launchd bootstrap', 'launchctl', ['bootstrap', launchdDomain, plistFile]);
+    runRequired('launchd enable', 'launchctl', ['enable', launchdService]);
+    runRequired('launchd kickstart', 'launchctl', ['kickstart', '-k', launchdService]);
+    console.log(`launchd service installed: ${plistFile}`);
+  }
+}
+
+export function getInstallDaemonHelp() {
+  return `ticlawk install-daemon
+
+Install or refresh the background daemon for the current ticlawk package.
+
+Usage:
+  ticlawk install-daemon
+`;
+}
+
+export async function installDaemon() {
+  if (process.platform === 'linux') {
+    installSystemd();
+    return true;
+  }
+
+  if (process.platform === 'darwin') {
+    installLaunchd();
+    return true;
+  }
+
+  console.log(`No daemon installer is available for ${process.platform}.`);
+  console.log('Run manually: ticlawk start');
+  return false;
+}
+
+export async function runInstallDaemon() {
+  await installDaemon();
+  const { runSetupReadiness } = await import('./setup-readiness.mjs');
+  await runSetupReadiness({ phase: 'daemon', ensureDaemon: false });
+}

package/src/core/diagnostics.mjs

@@ -0,0 +1,79 @@
+/**
+ * Process-level crash diagnostics.
+ *
+ * Installs listeners for unhandledRejection / uncaughtException / SIGINT /
+ * SIGTERM / exit and appends a structured payload to
+ * ~/.ticlawk/ticlawk-crash.log so a dead daemon leaves a forensic trail.
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { AF_HOME, AF_CRASH_LOG_PATH } from './config.mjs';
+
+let diagnosticsInstalled = false;
+
+function formatDiagnosticValue(value) {
+  if (value instanceof Error) {
+    return value.stack || `${value.name}: ${value.message}`;
+  }
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+function writeExitDiagnostic(kind, value) {
+  const lines = [
+    `[${new Date().toISOString()}] ${kind}`,
+    `pid=${process.pid}`,
+  ];
+
+  if (value !== undefined) {
+    lines.push(formatDiagnosticValue(value));
+  }
+
+  const payload = `${lines.join('\n')}\n\n`;
+
+  try {
+    mkdirSync(AF_HOME, { recursive: true });
+    appendFileSync(AF_CRASH_LOG_PATH, payload, 'utf8');
+  } catch {
+    // Best-effort logging only.
+  }
+
+  try {
+    process.stderr.write(payload);
+  } catch {
+    // Ignore stderr failures during shutdown.
+  }
+}
+
+export function installProcessDiagnostics() {
+  if (diagnosticsInstalled) return;
+  diagnosticsInstalled = true;
+
+  process.on('unhandledRejection', (reason) => {
+    writeExitDiagnostic('unhandledRejection', reason);
+    process.exit(1);
+  });
+
+  process.on('uncaughtException', (err) => {
+    writeExitDiagnostic('uncaughtException', err);
+    process.exit(1);
+  });
+
+  process.on('SIGINT', () => {
+    writeExitDiagnostic('signal SIGINT');
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    writeExitDiagnostic('signal SIGTERM');
+    process.exit(0);
+  });
+
+  process.on('exit', (code) => {
+    writeExitDiagnostic(`exit diagnostic code=${code}`);
+  });
+}

package/src/core/events/worker-events.mjs

@@ -0,0 +1,80 @@
+import { createHash } from 'node:crypto';
+
+const workerEventSeq = new Map();
+const DELTA_LOG_PREVIEW_CHARS = 48;
+
+function shortId(value) {
+  return value ? String(value).slice(0, 8) : null;
+}
+
+function hashText(text) {
+  return createHash('sha1').update(String(text)).digest('hex').slice(0, 12);
+}
+
+function previewDelta(text) {
+  const normalized = String(text).replace(/\n/g, '\\n');
+  if (normalized.length <= DELTA_LOG_PREVIEW_CHARS) return normalized;
+  return normalized.slice(0, DELTA_LOG_PREVIEW_CHARS) + '…';
+}
+
+function nextWorkerEventMeta({ agent, sessionId, turnId }) {
+  const key = `${agent}:${sessionId || ''}:${turnId || 'session'}`;
+  const seq = (workerEventSeq.get(key) || 0) + 1;
+  workerEventSeq.set(key, seq);
+  return {
+    key,
+    seq,
+    originTs: new Date().toISOString(),
+  };
+}
+
+function clearWorkerEventMeta(key) {
+  if (!key) return;
+  workerEventSeq.delete(key);
+}
+
+export async function emitWorkerEvent({ adapter, binding, agent, sessionId, cwd = '', turnId = null, replyToMessageId = null, event, logger }) {
+  if (!sessionId || typeof adapter.emitEvent !== 'function') return;
+  const eventName = event?.worker_event_name || event?.hook_event_name || 'unknown';
+  const logicalTurnId = replyToMessageId || turnId || event?.turn_id || null;
+  const { key, seq, originTs } = nextWorkerEventMeta({ agent, sessionId, turnId: logicalTurnId });
+  const enrichedEvent = {
+    ...event,
+    turn_id: logicalTurnId,
+    reply_to_message_id: replyToMessageId || null,
+    event_seq: seq,
+    origin_ts: originTs,
+  };
+  if (typeof event?.delta === 'string' && event.delta) {
+    enrichedEvent.delta_chars = event.delta.length;
+    enrichedEvent.delta_hash = hashText(event.delta);
+    logger?.debugLog?.('events', 'delta.recv', {
+      bindingId: binding.id,
+      agent,
+      sessionId: shortId(sessionId),
+      turnId: shortId(logicalTurnId),
+      seq,
+      chars: event.delta.length,
+      hash: enrichedEvent.delta_hash,
+      preview: previewDelta(event.delta),
+    });
+  } else {
+    logger?.debugLog?.('events', 'event.recv', {
+      bindingId: binding.id,
+      agent,
+      sessionId: shortId(sessionId),
+      turnId: shortId(logicalTurnId),
+      seq,
+      eventName,
+    });
+  }
+  await adapter.emitEvent(binding, {
+    agent,
+    sessionId,
+    cwd,
+    event: enrichedEvent,
+  });
+  if (eventName === 'worker.turn.complete' || eventName === 'worker.turn.error') {
+    clearWorkerEventMeta(key);
+  }
+}

package/src/core/executables.mjs

@@ -0,0 +1,106 @@
+import { accessSync, constants } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { delimiter } from 'node:path';
+import { isAbsolute, join } from 'node:path';
+import { buildRuntimeEnv } from './runtime-env.mjs';
+
+export const COMMON_EXECUTABLE_DIRS = [
+  `${homedir()}/.local/bin`,
+  `${homedir()}/.npm-global/bin`,
+  `${homedir()}/.bun/bin`,
+  `${homedir()}/.cargo/bin`,
+  '/opt/homebrew/bin',
+  '/opt/homebrew/sbin',
+  '/usr/local/bin',
+  '/usr/local/sbin',
+  '/usr/bin',
+  '/bin',
+  '/usr/sbin',
+  '/sbin',
+];
+
+export function isExecutablePath(filePath) {
+  if (!filePath || !isAbsolute(filePath)) return false;
+  try {
+    accessSync(filePath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildLookupPath(extraDirs = []) {
+  const seen = new Set();
+  return [
+    ...String(process.env.PATH || '').split(delimiter),
+    ...extraDirs,
+    ...COMMON_EXECUTABLE_DIRS,
+  ]
+    .map(part => String(part || '').trim())
+    .filter(Boolean)
+    .filter((part) => {
+      if (seen.has(part)) return false;
+      seen.add(part);
+      return true;
+    })
+    .join(delimiter);
+}
+
+function commandFromPath(command, extraDirs = []) {
+  if (!command || String(command).includes('/')) return null;
+  const result = spawnSync('sh', ['-c', 'command -v "$1"', 'sh', String(command)], {
+    env: buildRuntimeEnv({ PATH: buildLookupPath(extraDirs) }),
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) return null;
+  const resolved = String(result.stdout || '').split('\n').map(line => line.trim()).find(Boolean);
+  return isExecutablePath(resolved) ? resolved : null;
+}
+
+export function resolveExecutable({
+  command,
+  preferredPath = null,
+  envKey = null,
+  configuredPath = null,
+  extraDirs = [],
+} = {}) {
+  const candidates = [
+    preferredPath,
+    configuredPath,
+    envKey ? process.env[envKey] : null,
+    command,
+  ].map(value => String(value || '').trim()).filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (isAbsolute(candidate) && isExecutablePath(candidate)) {
+      return candidate;
+    }
+    const fromPath = commandFromPath(candidate, extraDirs);
+    if (fromPath) return fromPath;
+  }
+
+  for (const dir of extraDirs) {
+    const candidate = join(dir, command);
+    if (isExecutablePath(candidate)) return candidate;
+  }
+
+  for (const dir of COMMON_EXECUTABLE_DIRS) {
+    const candidate = join(dir, command);
+    if (isExecutablePath(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+export function getExecutableVersion(executablePath, args = ['--version']) {
+  if (!executablePath) return null;
+  const result = spawnSync(executablePath, args, {
+    env: buildRuntimeEnv(),
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  if (result.error || result.status !== 0) return null;
+  const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+  return output.split('\n').map(line => line.trim()).find(Boolean) || null;
+}

package/src/core/host-id.mjs

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { AF_HOME } from './config.mjs';
+
+const HOST_ID_PATH = join(AF_HOME, 'host-id');
+
+let cachedHostId = null;
+
+export function getHostId() {
+  if (cachedHostId) return cachedHostId;
+
+  try {
+    if (existsSync(HOST_ID_PATH)) {
+      const current = readFileSync(HOST_ID_PATH, 'utf8').trim();
+      if (current) {
+        cachedHostId = current;
+        return cachedHostId;
+      }
+    }
+  } catch {}
+
+  const next = `afh_${randomUUID()}`;
+  try {
+    mkdirSync(dirname(HOST_ID_PATH), { recursive: true });
+    writeFileSync(HOST_ID_PATH, `${next}\n`, { mode: 0o600 });
+  } catch {}
+  cachedHostId = next;
+  return cachedHostId;
+}
+
+export function getHostLabel() {
+  return hostname();
+}
+
+export function getBindingRuntimeHostId(binding) {
+  return String(
+    binding?.runtime_host_id
+    || binding?.targetMeta?.runtime_host_id
+    || ''
+  ).trim();
+}
+
+export function belongsToRuntimeHost(binding, hostId = getHostId()) {
+  const bindingHostId = getBindingRuntimeHostId(binding);
+  return !bindingHostId || bindingHostId === hostId;
+}

package/src/core/http.mjs

@@ -0,0 +1,65 @@
+import { createServer } from 'node:http';
+
+function writeJson(res, statusCode, body) {
+  res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+async function readBody(req) {
+  let body = '';
+  for await (const chunk of req) {
+    body += chunk;
+  }
+  return body;
+}
+
+export function startLocalHttpServer({ port, adapter }) {
+  const server = createServer(async (req, res) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    if (req.method === 'GET' && req.url === '/health') {
+      try {
+        const health = await adapter.health();
+        writeJson(res, 200, {
+          ok: true,
+          adapter: adapter.id,
+          ...health,
+        });
+      } catch (err) {
+        writeJson(res, 500, {
+          ok: false,
+          adapter: adapter.id,
+          error: err?.message || 'health check failed',
+        });
+      }
+      return;
+    }
+
+    writeJson(res, 404, { error: 'not found' });
+  });
+
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`ticlawk is already running on port ${port}.`);
+      console.error('Check with: ticlawk health');
+      console.error(`If it is not, free the port (lsof -i :${port}) or set FEED_RELAY_PORT to a different port.`);
+      process.exit(1);
+    }
+    throw err;
+  });
+
+  server.listen(port, () => {
+    console.log(`[relay] HTTP server listening on :${port}`);
+    console.log(`[relay]   adapter: ${adapter.id}`);
+    console.log('[relay]   GET  /health   - daemon status check');
+  });
+
+  return server;
+}

package/src/core/logger.mjs

@@ -0,0 +1,34 @@
+/**
+ * Bus-level structured logging helpers.
+ *
+ * Pure utility module with no dependencies on other core modules. Used by
+ * runtimes, adapters, and the bus itself.
+ */
+
+export function isoNow() {
+  return new Date().toISOString();
+}
+
+export function parseTimeMs(value) {
+  if (!value) return null;
+  if (typeof value === 'number') return value > 1e12 ? value : null;
+  const ms = Date.parse(String(value));
+  return Number.isFinite(ms) ? ms : null;
+}
+
+export function formatLogMeta(meta = {}) {
+  return Object.entries(meta)
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+    .join(' ');
+}
+
+export function debugLog(scope, message, meta = {}) {
+  const suffix = formatLogMeta(meta);
+  console.log(`[${isoNow()}] [${scope}] ${message}${suffix ? ` ${suffix}` : ''}`);
+}
+
+export function debugError(scope, message, meta = {}) {
+  const suffix = formatLogMeta(meta);
+  console.error(`[${isoNow()}] [${scope}] ${message}${suffix ? ` ${suffix}` : ''}`);
+}