@mecha.im/cli 0.3.4

package/agent/entry.ts

@@ -0,0 +1,168 @@
+import { serve } from "@hono/node-server";
+import { readFileSync, existsSync, writeFileSync } from "node:fs";
+import { mkdirSync } from "node:fs";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { botConfigSchema } from "./types.js";
+import { createApp } from "./server.js";
+import { Scheduler } from "./scheduler.js";
+import { createPtyManager } from "./pty-manager.js";
+import { attachTerminalWs } from "./ws-terminal.js";
+import { log } from "../shared/logger.js";
+
+const CREDENTIALS_PATH = "/state/credentials.yaml";
+
+// Crash handlers — log before dying so we know what happened
+process.on("unhandledRejection", (reason) => {
+  log.error("Unhandled rejection", { error: reason instanceof Error ? reason.message : String(reason) });
+  process.exit(1);
+});
+process.on("uncaughtException", (err) => {
+  log.error("Uncaught exception", { error: err.message, stack: err.stack });
+  process.exit(1);
+});
+
+const DEFAULT_PORT = 3000;
+const portEnv = process.env.MECHA_PORT;
+let PORT = DEFAULT_PORT;
+if (portEnv) {
+  const parsed = parseInt(portEnv, 10);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+    log.error(`Invalid MECHA_PORT: "${portEnv}" (must be 1-65535)`);
+    process.exit(1);
+  }
+  PORT = parsed;
+}
+const STATE_DIR = process.env.MECHA_STATE_DIR ?? "/state";
+const CONFIG_PATH = process.env.MECHA_CONFIG_PATH ?? "/config/bot.yaml";
+
+function loadConfig() {
+  const name = process.env.MECHA_BOT_NAME;
+  if (!name) {
+    log.error("MECHA_BOT_NAME env var is required");
+    process.exit(1);
+  }
+
+  // Re-resolve auth from credentials.yaml if available (supports runtime auth switching)
+  // Read config.auth first to determine if credentials resolution is required
+  let configAuth: string | undefined;
+  try {
+    const configRaw = readFileSync(CONFIG_PATH, "utf-8");
+    const configParsed = parseYaml(configRaw) as { auth?: string };
+    configAuth = configParsed.auth;
+  } catch { /* config will be parsed again below */ }
+
+  if (configAuth && existsSync(CREDENTIALS_PATH)) {
+    // Profile is set — clear old env vars and resolve from credentials (fail fast on any error)
+    delete process.env.ANTHROPIC_API_KEY;
+    delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
+    try {
+      const credsRaw = readFileSync(CREDENTIALS_PATH, "utf-8");
+      const credsParsed = parseYaml(credsRaw) as { credentials?: Array<{ name: string; type: string; env: string; key: string }> };
+      const cred = credsParsed.credentials?.find((c) => c.name === configAuth);
+      if (cred && (cred.type === "api_key" || cred.type === "oauth_token")) {
+        process.env[cred.env] = cred.key;
+        log.info(`Auth resolved from credentials.yaml: profile="${configAuth}" type=${cred.type}`);
+      } else {
+        log.error(`Auth profile "${configAuth}" not found or not a Claude auth credential in credentials.yaml`);
+        process.exit(1);
+      }
+    } catch (err) {
+      log.error(`Failed to resolve auth profile "${configAuth}" from credentials.yaml`, {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      process.exit(1);
+    }
+  }
+
+  if (!process.env.ANTHROPIC_API_KEY && !process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+    log.error("ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN env var is required");
+    process.exit(1);
+  }
+
+  try {
+    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    const parsed = parseYaml(raw);
+    const result = botConfigSchema.safeParse(parsed);
+    if (!result.success) {
+      log.error("Invalid bot config", { detail: JSON.stringify(result.error.format()) });
+      process.exit(1);
+    }
+    return result.data;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      const result = botConfigSchema.safeParse({
+        name,
+        system: process.env.MECHA_SYSTEM_PROMPT ?? "You are a helpful assistant.",
+        model: process.env.MECHA_MODEL ?? "sonnet",
+      });
+      if (!result.success) {
+        log.error("Failed to build config from env", { detail: JSON.stringify(result.error.format()) });
+        process.exit(1);
+      }
+      return result.data;
+    }
+    throw err;
+  }
+}
+
+const config = loadConfig();
+const startedAt = Date.now();
+
+// Ensure state directories exist
+mkdirSync(`${STATE_DIR}/sessions`, { recursive: true });
+mkdirSync(`${STATE_DIR}/logs`, { recursive: true });
+
+// PTY manager for interactive terminal sessions (created before app so it can be passed)
+let ptyManager: ReturnType<typeof createPtyManager> | undefined;
+try {
+  const { createNodePtySpawn } = await import("./node-pty-adapter.js");
+  ptyManager = createPtyManager({ spawnFn: createNodePtySpawn(), botConfig: config });
+  log.info("PTY terminal support enabled (node-pty)");
+} catch (err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  log.info("PTY terminal support disabled", { reason: msg });
+}
+
+const { app, isBusy, handlePrompt, setScheduler, botToken } = createApp(config, startedAt, ptyManager);
+
+// Persist schedule changes back to bot.yaml
+function onScheduleConfigChange(entries: Array<{ cron: string; prompt: string }>) {
+  try {
+    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    const parsed = parseYaml(raw) as Record<string, unknown>;
+    parsed.schedule = entries.length > 0 ? entries : undefined;
+    writeFileSync(CONFIG_PATH, stringifyYaml(parsed));
+    log.info(`Schedule config persisted: ${entries.length} entries`);
+  } catch (err) {
+    log.error("Failed to persist schedule config", { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+// Start scheduler (always, so CRUD works even with no initial entries)
+const scheduler = new Scheduler(config.schedule ?? [], handlePrompt, isBusy, onScheduleConfigChange);
+setScheduler(scheduler);
+scheduler.start();
+
+const server = serve({ fetch: app.fetch, port: PORT }, () => {
+  log.info(`mecha-agent "${config.name}" listening on :${PORT}`);
+});
+
+// Attach WebSocket terminal server if PTY is available
+if (ptyManager) {
+  attachTerminalWs(server, ptyManager, botToken);
+}
+
+function gracefulShutdown(signal: string) {
+  log.info(`${signal} received, shutting down...`);
+  ptyManager?.shutdown();
+  scheduler?.stop();
+  const forceTimer = setTimeout(() => {
+    log.warn("Graceful shutdown timeout, forcing exit");
+    process.exit(1);
+  }, 5000);
+  forceTimer.unref();
+  server.close(() => process.exit(0));
+}
+
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));

package/agent/event-log.ts

@@ -0,0 +1,103 @@
+import { readFileSync, statSync, renameSync, openSync, readSync, closeSync } from "node:fs";
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { PATHS } from "./paths.js";
+import { log } from "../shared/logger.js";
+
+export interface EventEntry {
+  type: string;
+  timestamp: string;
+  [key: string]: unknown;
+}
+
+let writeFailureWarned = false;
+let dirEnsured = false;
+let writeChain: Promise<void> = Promise.resolve();
+
+const MAX_LOG_BYTES = 10 * 1024 * 1024; // 10MB
+const MAX_ROTATED_FILES = 5;
+
+function rotateIfNeeded(): void {
+  try {
+    const stats = statSync(PATHS.eventsLog);
+    if (stats.size < MAX_LOG_BYTES) return;
+
+    // Rotate: shift existing rotated files
+    for (let i = MAX_ROTATED_FILES - 1; i >= 1; i--) {
+      try {
+        renameSync(`${PATHS.eventsLog}.${i}`, `${PATHS.eventsLog}.${i + 1}`);
+      } catch { /* file may not exist */ }
+    }
+    renameSync(PATHS.eventsLog, `${PATHS.eventsLog}.1`);
+  } catch {
+    // File doesn't exist or can't stat — nothing to rotate
+  }
+}
+
+export function logEvent(entry: { type: string; [key: string]: unknown }): void {
+  const full: Record<string, unknown> = {
+    ...entry,
+    timestamp: new Date().toISOString(),
+  };
+  const line = JSON.stringify(full) + "\n";
+
+  // Serialize writes through a promise chain to prevent rotate/append races
+  writeChain = writeChain.then(async () => {
+    try {
+      if (!dirEnsured) {
+        await mkdir(dirname(PATHS.eventsLog), { recursive: true });
+        dirEnsured = true;
+      }
+      rotateIfNeeded();
+      await appendFile(PATHS.eventsLog, line);
+      writeFailureWarned = false;
+    } catch (err) {
+      if (!writeFailureWarned) {
+        log.warn("event-log: write failed", { error: err instanceof Error ? err.message : String(err) });
+        writeFailureWarned = true;
+      }
+    }
+  });
+}
+
+export function readEvents(limit = 100): EventEntry[] {
+  const safeLimit = Math.max(1, Math.min(Number.isFinite(limit) ? Math.floor(limit) : 100, 1000));
+  try {
+    // Read only the tail of the file to avoid loading large files entirely into memory
+    const stats = statSync(PATHS.eventsLog);
+    const READ_TAIL_BYTES = 512 * 1024; // 512KB should cover any reasonable limit
+    let raw: string;
+    if (stats.size > READ_TAIL_BYTES) {
+      const fd = openSync(PATHS.eventsLog, "r");
+      try {
+        const buf = Buffer.alloc(READ_TAIL_BYTES);
+        readSync(fd, buf, 0, READ_TAIL_BYTES, stats.size - READ_TAIL_BYTES);
+        raw = buf.toString("utf-8");
+        // Drop the first (likely partial) line
+        const firstNewline = raw.indexOf("\n");
+        if (firstNewline !== -1) raw = raw.slice(firstNewline + 1);
+      } finally {
+        closeSync(fd);
+      }
+    } else {
+      raw = readFileSync(PATHS.eventsLog, "utf-8");
+    }
+    const lines = raw.trimEnd().split("\n");
+    const tail = lines.slice(-safeLimit);
+    const entries: EventEntry[] = [];
+    for (const line of tail) {
+      if (!line) continue;
+      try {
+        entries.push(JSON.parse(line));
+      } catch {
+        // skip malformed lines
+      }
+    }
+    return entries;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return []; // no events yet — expected
+    log.warn("event-log: read failed", { error: err instanceof Error ? err.message : String(err) });
+    return [];
+  }
+}

package/agent/node-pty-adapter.ts

@@ -0,0 +1,39 @@
+import { createRequire } from "node:module";
+import type { MechaPty, PtySpawnFn, PtySpawnOpts } from "./pty-types.js";
+
+const require = createRequire(import.meta.url);
+
+/** Create a PtySpawnFn using node-pty. */
+export function createNodePtySpawn(): PtySpawnFn {
+  const nodePty = require("node-pty") as typeof import("node-pty");
+
+  return (file: string, args: string[], opts: PtySpawnOpts): MechaPty => {
+    const pty = nodePty.spawn(file, args, {
+      name: opts.name,
+      cols: opts.cols,
+      rows: opts.rows,
+      cwd: opts.cwd,
+      env: opts.env,
+    });
+
+    return {
+      onData(cb) {
+        const disposable = pty.onData(cb);
+        return { dispose: () => disposable.dispose() };
+      },
+      onExit(cb) {
+        const disposable = pty.onExit(cb);
+        return { dispose: () => disposable.dispose() };
+      },
+      write(data) {
+        pty.write(data);
+      },
+      resize(cols, rows) {
+        pty.resize(cols, rows);
+      },
+      kill(signal) {
+        pty.kill(signal);
+      },
+    };
+  };
+}

package/agent/paths.ts

@@ -0,0 +1,12 @@
+const STATE_DIR = process.env.MECHA_STATE_DIR ?? "/state";
+
+export const PATHS = {
+  state: STATE_DIR,
+  tasks: `${STATE_DIR}/tasks`,
+  taskIndex: `${STATE_DIR}/tasks/index.json`,
+  logs: `${STATE_DIR}/logs`,
+  eventsLog: `${STATE_DIR}/logs/events.jsonl`,
+  scheduleState: `${STATE_DIR}/logs/schedule-state.json`,
+  costs: `${STATE_DIR}/costs.json`,
+  characterConfig: `${STATE_DIR}/character.json`,
+} as const;

package/agent/pty-manager.ts

@@ -0,0 +1,265 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join, delimiter } from "node:path";
+import { homedir } from "node:os";
+import type { WebSocket } from "ws";
+import type { MechaPty, PtySpawnFn } from "./pty-types.js";
+import type { BotConfig } from "./types.js";
+import { log } from "../shared/logger.js";
+
+/** Resolve absolute path to `claude` binary. */
+function resolveClaudeBin(): string {
+  const home = homedir();
+  const candidates = [
+    join(home, ".npm-global", "bin", "claude"),
+    join(home, ".local", "bin", "claude"),
+    join(home, ".claude", "local", "bin", "claude"),
+    "/usr/local/bin/claude",
+    "/usr/bin/claude",
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  return "claude";
+}
+
+const SCROLLBACK_LIMIT = 200;
+const SCROLLBACK_MAX_BYTES = 512 * 1024;
+const MIN_COLS = 10;
+const MAX_COLS = 500;
+const MIN_ROWS = 2;
+const MAX_ROWS = 200;
+
+export interface PtySession {
+  id: string;
+  claudeSessionId: string;
+  pty: MechaPty;
+  clients: Set<WebSocket>;
+  createdAt: Date;
+  lastActivity: Date;
+  scrollback: string[];
+}
+
+export interface PtyManager {
+  spawn(sessionId: string | undefined, cols: number, rows: number): PtySession;
+  attach(sessionKey: string, ws: WebSocket): PtySession | null;
+  detach(sessionKey: string, ws: WebSocket): void;
+  resize(sessionKey: string, cols: number, rows: number): void;
+  getSession(sessionKey: string): PtySession | null;
+  listSessions(): Array<{ id: string; claudeSessionId: string; createdAt: string }>;
+  shutdown(): void;
+}
+
+export interface CreatePtyManagerOpts {
+  spawnFn: PtySpawnFn;
+  botConfig: BotConfig;
+  maxSessions?: number;
+  idleTimeoutMs?: number;
+  spawnCooldownMs?: number;
+}
+
+export function createPtyManager(opts: CreatePtyManagerOpts): PtyManager {
+  const {
+    spawnFn,
+    botConfig,
+    maxSessions = 10,
+    idleTimeoutMs = 300_000,
+    spawnCooldownMs = 2_000,
+  } = opts;
+
+  const sessions = new Map<string, PtySession>();
+  const idleTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  let lastSpawnTime = 0;
+
+  function clearIdleTimer(key: string): void {
+    const timer = idleTimers.get(key);
+    if (!timer) return;
+    clearTimeout(timer);
+    idleTimers.delete(key);
+  }
+
+  function startIdleTimer(key: string): void {
+    clearIdleTimer(key);
+    idleTimers.set(key, setTimeout(() => {
+      const session = sessions.get(key);
+      if (!session || session.clients.size > 0) {
+        idleTimers.delete(key);
+        return;
+      }
+      log.info(`PTY session ${key} idle timeout — killing`);
+      session.pty.kill();
+      sessions.delete(key);
+      idleTimers.delete(key);
+    }, idleTimeoutMs));
+  }
+
+  // Build env for claude CLI — inherit process env + set TERM
+  function buildPtyEnv(): Record<string, string> {
+    const env: Record<string, string> = {};
+    for (const [k, v] of Object.entries(process.env)) {
+      if (v !== undefined) env[k] = v;
+    }
+    env.TERM = "xterm-256color";
+    // Ensure user bin dirs are on PATH
+    const home = homedir();
+    const extraPaths = [
+      join(home, ".npm-global", "bin"),
+      join(home, ".local", "bin"),
+    ];
+    for (const p of extraPaths) {
+      if (env.PATH && !env.PATH.split(delimiter).includes(p)) {
+        env.PATH = `${p}${delimiter}${env.PATH}`;
+      }
+    }
+    return env;
+  }
+
+  return {
+    spawn(sessionId, cols, rows) {
+      if (sessions.size >= maxSessions) {
+        throw new Error(`Max PTY sessions (${maxSessions}) reached`);
+      }
+
+      const now = Date.now();
+      if (now - lastSpawnTime < spawnCooldownMs) {
+        throw new Error("Too many spawn requests — wait a moment");
+      }
+
+      const isNewSession = !sessionId || sessionId.startsWith("new-");
+      const claudeSessionId = isNewSession ? randomUUID() : sessionId;
+      const key = claudeSessionId;
+
+      // Kill existing session with same key
+      const existing = sessions.get(key);
+      if (existing) {
+        existing.pty.kill();
+        clearIdleTimer(key);
+        sessions.delete(key);
+      }
+
+      // Build claude CLI args from bot config
+      const args: string[] = [];
+      if (isNewSession) {
+        args.push("--session-id", claudeSessionId);
+      } else {
+        args.push("--resume", claudeSessionId);
+      }
+
+      // Permission mode — bypass permissions skips interactive trust/accept prompts
+      if (botConfig.permission_mode === "bypassPermissions") {
+        args.push("--dangerously-skip-permissions", "--allow-dangerously-skip-permissions");
+      } else if (botConfig.permission_mode && botConfig.permission_mode !== "default") {
+        args.push("--permission-mode", botConfig.permission_mode);
+      }
+
+      // Model
+      if (botConfig.model) {
+        args.push("--model", botConfig.model);
+      }
+
+      const safeCols = Math.max(MIN_COLS, Math.min(MAX_COLS, cols));
+      const safeRows = Math.max(MIN_ROWS, Math.min(MAX_ROWS, rows));
+
+      const cwd = process.env.MECHA_WORKSPACE_CWD
+        || (existsSync("/home/appuser/workspace") ? "/home/appuser/workspace" : "/state/home-workspace");
+
+      const claudeBin = resolveClaudeBin();
+      log.info(`Spawning PTY: ${claudeBin} ${args.join(" ")} (${safeCols}x${safeRows})`);
+
+      const pty = spawnFn(claudeBin, args, {
+        name: "xterm-256color",
+        cols: safeCols,
+        rows: safeRows,
+        cwd,
+        env: buildPtyEnv(),
+      });
+
+      lastSpawnTime = now;
+
+      const scrollback: string[] = [];
+      let scrollbackBytes = 0;
+      const session: PtySession = {
+        id: key,
+        claudeSessionId,
+        pty,
+        clients: new Set(),
+        createdAt: new Date(),
+        lastActivity: new Date(),
+        scrollback,
+      };
+      sessions.set(key, session);
+
+      // Capture PTY output into scrollback ring buffer
+      pty.onData((data) => {
+        session.lastActivity = new Date();
+        scrollback.push(data);
+        scrollbackBytes += Buffer.byteLength(data, "utf8");
+        while (scrollback.length > SCROLLBACK_LIMIT || scrollbackBytes > SCROLLBACK_MAX_BYTES) {
+          const removed = scrollback.shift();
+          if (removed) scrollbackBytes -= Buffer.byteLength(removed, "utf8");
+          else break;
+        }
+      });
+
+      pty.onExit(({ exitCode }) => {
+        log.info(`PTY session ${key} exited with code ${exitCode}`);
+        sessions.delete(key);
+        clearIdleTimer(key);
+      });
+
+      return session;
+    },
+
+    attach(sessionKey, ws) {
+      const session = sessions.get(sessionKey);
+      if (!session) return null;
+      // Single-client model: disconnect previous clients
+      for (const old of session.clients) {
+        old.close(4001, "Replaced by new client");
+      }
+      session.clients.clear();
+      session.clients.add(ws);
+      session.lastActivity = new Date();
+      clearIdleTimer(sessionKey);
+      return session;
+    },
+
+    detach(sessionKey, ws) {
+      const session = sessions.get(sessionKey);
+      if (!session) return;
+      session.clients.delete(ws);
+      if (session.clients.size === 0) {
+        startIdleTimer(sessionKey);
+      }
+    },
+
+    resize(sessionKey, cols, rows) {
+      const session = sessions.get(sessionKey);
+      if (!session) return;
+      const safeCols = Math.max(MIN_COLS, Math.min(MAX_COLS, cols));
+      const safeRows = Math.max(MIN_ROWS, Math.min(MAX_ROWS, rows));
+      session.pty.resize(safeCols, safeRows);
+      session.lastActivity = new Date();
+    },
+
+    getSession(sessionKey) {
+      return sessions.get(sessionKey) ?? null;
+    },
+
+    listSessions() {
+      return Array.from(sessions.values()).map((s) => ({
+        id: s.id,
+        claudeSessionId: s.claudeSessionId,
+        createdAt: s.createdAt.toISOString(),
+      }));
+    },
+
+    shutdown() {
+      for (const [key, session] of sessions) {
+        session.pty.kill();
+        clearIdleTimer(key);
+      }
+      sessions.clear();
+    },
+  };
+}

package/agent/pty-types.ts

@@ -0,0 +1,25 @@
+/** Disposable subscription returned by onData/onExit. */
+export interface PtyDisposable {
+  dispose(): void;
+}
+
+/** Platform-agnostic PTY handle. */
+export interface MechaPty {
+  onData(cb: (data: string) => void): PtyDisposable;
+  onExit(cb: (e: { exitCode: number; signal?: number }) => void): PtyDisposable;
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+}
+
+/** Options passed to a PTY spawn function. */
+export interface PtySpawnOpts {
+  name: string;
+  cols: number;
+  rows: number;
+  cwd: string;
+  env: Record<string, string>;
+}
+
+/** Factory signature for spawning a PTY process. */
+export type PtySpawnFn = (file: string, args: string[], opts: PtySpawnOpts) => MechaPty;