@txzy/automatic-bridge 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# automatic-bridge
+
+A small npm bridge that connects Automatic channels to Hermes or Codex CLI.
+
+## Commands
+
+- `automatic-bridge doctor`
+- `automatic-bridge init`
+- `automatic-bridge once`
+- `automatic-bridge smoke`
+- `automatic-bridge run`
+
+## Install locally
+
+```bash
+cd bridge
+npm install
+npm link
+```
+
+## Install from npm or git
+
+```bash
+npx @txzy/automatic-bridge doctor
+npx @txzy/automatic-bridge init
+npx @txzy/automatic-bridge run
+```
+
+## Configuration
+
+You can set config via env, config file, or CLI options.
+
+Required at minimum:
+
+- `AUTOMATIC_BASE_URL`
+- `AUTOMATIC_CHANNEL_IDS`
+
+Optional:
+
+- `BRIDGE_AGENT_KIND=hermes|codex`
+- `HERMES_CLI_BIN`
+- `CODEX_CLI_BIN`
+- `HERMES_CLI_ARGS`
+- `CODEX_CLI_ARGS`
+- `AGENT_API_KEY`
+- `BRIDGE_POLL_INTERVAL_MS`
+- `BRIDGE_HISTORY_LIMIT`
+- `BRIDGE_REPLY_LIMIT`
+- `BRIDGE_AGENT_TIMEOUT_MS`
+
+## Smoke test
+
+```bash
+npx automatic-bridge smoke
+```
+
+This sends a probe message to the first configured channel and waits for the bridge to process it.

package/bin/automatic-bridge.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/main.mjs";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error("[automatic-bridge] fatal", error?.stack || error?.message || error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@txzy/automatic-bridge",
+  "version": "0.1.0",
+  "description": "Bridge Automatic channels to Hermes or Codex CLI",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "automatic-bridge": "./bin/automatic-bridge.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "doctor": "node ./bin/automatic-bridge.js doctor",
+    "init": "node ./bin/automatic-bridge.js init",
+    "once": "node ./bin/automatic-bridge.js once",
+    "smoke": "node ./bin/automatic-bridge.js smoke",
+    "run": "node ./bin/automatic-bridge.js run",
+    "pack": "npm pack"
+  }
+}

package/src/client.mjs

@@ -0,0 +1,50 @@
+const JSON_HEADERS = { "Content-Type": "application/json" };
+
+export function authHeaders(apiKey) {
+  if (!apiKey) return JSON_HEADERS;
+  return { ...JSON_HEADERS, Authorization: `Bearer ${apiKey}` };
+}
+
+async function fetchJson(url, options = {}) {
+  const response = await fetch(url, options);
+  const text = await response.text();
+  let parsed = null;
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
+    }
+  }
+  if (!response.ok) {
+    const message = typeof parsed === "object" && parsed && "error" in parsed ? parsed.error : text || response.statusText;
+    throw new Error(`HTTP ${response.status} ${response.statusText}: ${message}`);
+  }
+  return parsed;
+}
+
+export async function getAuthStatus(baseUrl, channelId) {
+  return fetchJson(`${baseUrl}/api/channels/${channelId}/auth/status`, { cache: "no-store" });
+}
+
+export async function getMessages(baseUrl, channelId, sinceId = 0, role = "all") {
+  return fetchJson(`${baseUrl}/api/channels/${channelId}/messages?role=${encodeURIComponent(role)}&since_id=${encodeURIComponent(sinceId)}`, {
+    cache: "no-store",
+  });
+}
+
+export async function postUserMessage(baseUrl, channelId, content) {
+  return fetchJson(`${baseUrl}/api/channels/${channelId}/user-message`, {
+    method: "POST",
+    headers: JSON_HEADERS,
+    body: JSON.stringify({ content }),
+  });
+}
+
+export async function postAgentMessage(baseUrl, channelId, content, apiKey = "") {
+  return fetchJson(`${baseUrl}/api/channels/${channelId}/agent-message`, {
+    method: "POST",
+    headers: authHeaders(apiKey),
+    body: JSON.stringify({ content }),
+  });
+}

package/src/config.mjs

@@ -0,0 +1,134 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { defaultAgentArgs, detectAgentBinary, detectAgentKind } from "./detect.mjs";
+import { defaultConfigFile, defaultStateFile, parseIntValue, parseList, pathExists, readJson, splitCommandLine, writeJson } from "./utils.mjs";
+
+function resolveOption(options, ...names) {
+  for (const name of names) {
+    if (options[name] !== undefined && options[name] !== null && options[name] !== "") return options[name];
+  }
+  return undefined;
+}
+
+function normalizeChannelIds(value) {
+  if (Array.isArray(value)) return value.map(String).map((s) => s.trim()).filter(Boolean);
+  return parseList(value);
+}
+
+function normalizeConfig(raw) {
+  const agentKind = String(raw.agentKind || raw.BRIDGE_AGENT_KIND || detectAgentKind()).toLowerCase();
+  const agentBin = raw.agentBin || raw.HERMES_CLI_BIN || raw.CODEX_CLI_BIN || detectAgentBinary(agentKind);
+  const agentArgs = Array.isArray(raw.agentArgs)
+    ? raw.agentArgs
+    : splitCommandLine(raw.agentArgs || raw.HERMES_CLI_ARGS || raw.CODEX_CLI_ARGS || defaultAgentArgs(agentKind).join(","));
+
+  return {
+    baseUrl: String(raw.baseUrl || raw.AUTOMATIC_BASE_URL || "http://127.0.0.1:3000").replace(/\/$/, ""),
+    channelIds: normalizeChannelIds(raw.channelIds || raw.AUTOMATIC_CHANNEL_IDS || raw.AUTOMATIC_CHANNEL_ID),
+    agentKind,
+    agentBin,
+    agentArgs,
+    pollIntervalMs: parseIntValue(raw.pollIntervalMs ?? raw.BRIDGE_POLL_INTERVAL_MS, 1500),
+    historyLimit: parseIntValue(raw.historyLimit ?? raw.BRIDGE_HISTORY_LIMIT, 12),
+    replyLimit: parseIntValue(raw.replyLimit ?? raw.BRIDGE_REPLY_LIMIT, 1900),
+    agentTimeoutMs: parseIntValue(raw.agentTimeoutMs ?? raw.BRIDGE_AGENT_TIMEOUT_MS, 120_000),
+    apiKey: String(raw.apiKey ?? raw.AGENT_API_KEY ?? ""),
+    promptTemplate: String(raw.promptTemplate || raw.HERMES_PROMPT_TEMPLATE || "You are Hermes connected to Automatic channel {channelId}. Reply as the agent in a lightweight channel.\n\nRecent conversation:\n{history}\n\nLatest user message:\n{message}\n\nReply concisely and naturally as the agent."),
+    configPath: raw.configPath || raw.AUTOMATIC_BRIDGE_CONFIG || defaultConfigFile(),
+    statePath: raw.statePath || raw.BRIDGE_STATE_FILE || defaultStateFile(),
+  };
+}
+
+function readCliOptions(argv) {
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const [flag, inline] = arg.slice(2).split(/=(.*)/s, 2);
+    const key = flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (inline !== undefined) {
+      options[key] = inline;
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next && !next.startsWith("--")) {
+      options[key] = next;
+      i += 1;
+    } else {
+      options[key] = true;
+    }
+  }
+  return options;
+}
+
+export async function loadConfig(argvOptions = {}, extra = {}) {
+  const cliOptions = { ...readCliOptions(extra.argv || []), ...argvOptions };
+  const configPath = path.resolve(String(resolveOption(cliOptions, "configPath", "config") || defaultConfigFile()));
+  let fileConfig = {};
+  if (await pathExists(configPath)) {
+    try {
+      fileConfig = await readJson(configPath);
+    } catch {
+      fileConfig = {};
+    }
+  }
+
+  const env = process.env;
+  const combined = {
+    ...fileConfig,
+    ...env,
+    ...cliOptions,
+    configPath,
+  };
+
+  const cfg = normalizeConfig(combined);
+  const cliChannelIds = resolveOption(cliOptions, "channelIds", "channelIdsCsv", "AUTOMATIC_CHANNEL_IDS");
+  cfg.channelIds = normalizeChannelIds(cliChannelIds || fileConfig.channelIds || env.AUTOMATIC_CHANNEL_IDS || env.AUTOMATIC_CHANNEL_ID);
+  const singleChannelId = resolveOption(cliOptions, "channelId");
+  if (singleChannelId) cfg.channelIds = [String(singleChannelId)];
+  if (cliChannelIds) cfg.channelIds = normalizeChannelIds(cliChannelIds);
+  const cliBaseUrl = resolveOption(cliOptions, "baseUrl");
+  if (cliBaseUrl) cfg.baseUrl = String(cliBaseUrl).replace(/\/$/, "");
+  const cliAgentKind = resolveOption(cliOptions, "agentKind");
+  if (cliAgentKind) cfg.agentKind = String(cliAgentKind).toLowerCase();
+  const cliAgentBin = resolveOption(cliOptions, "agentBin");
+  if (cliAgentBin) cfg.agentBin = String(cliAgentBin);
+  const cliAgentArgs = resolveOption(cliOptions, "agentArgs");
+  if (cliAgentArgs) cfg.agentArgs = splitCommandLine(cliAgentArgs);
+  const cliPollIntervalMs = resolveOption(cliOptions, "pollIntervalMs");
+  if (cliPollIntervalMs) cfg.pollIntervalMs = parseIntValue(cliPollIntervalMs, cfg.pollIntervalMs);
+  const cliHistoryLimit = resolveOption(cliOptions, "historyLimit");
+  if (cliHistoryLimit) cfg.historyLimit = parseIntValue(cliHistoryLimit, cfg.historyLimit);
+  const cliReplyLimit = resolveOption(cliOptions, "replyLimit");
+  if (cliReplyLimit) cfg.replyLimit = parseIntValue(cliReplyLimit, cfg.replyLimit);
+  const cliAgentTimeoutMs = resolveOption(cliOptions, "agentTimeoutMs");
+  if (cliAgentTimeoutMs) cfg.agentTimeoutMs = parseIntValue(cliAgentTimeoutMs, cfg.agentTimeoutMs);
+  const cliApiKey = resolveOption(cliOptions, "apiKey");
+  if (cliApiKey) cfg.apiKey = String(cliApiKey);
+  const cliPromptTemplate = resolveOption(cliOptions, "promptTemplate");
+  if (cliPromptTemplate) cfg.promptTemplate = String(cliPromptTemplate);
+  const cliStatePath = resolveOption(cliOptions, "statePath");
+  if (cliStatePath) cfg.statePath = String(cliStatePath);
+  cfg.configPath = configPath;
+  return cfg;
+}
+
+export async function writeInitConfig(targetPath, config) {
+  const payload = {
+    baseUrl: config.baseUrl,
+    channelIds: config.channelIds,
+    agentKind: config.agentKind,
+    agentBin: config.agentBin,
+    agentArgs: config.agentArgs,
+    pollIntervalMs: config.pollIntervalMs,
+    historyLimit: config.historyLimit,
+    replyLimit: config.replyLimit,
+    agentTimeoutMs: config.agentTimeoutMs,
+    apiKey: config.apiKey,
+    promptTemplate: config.promptTemplate,
+    statePath: config.statePath,
+  };
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await writeJson(targetPath, payload);
+  return payload;
+}

package/src/detect.mjs

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CANDIDATES = {
+  hermes: [
+    process.env.HERMES_CLI_BIN,
+    "hermes",
+    path.join(os.homedir(), ".hermes", "hermes-agent", "venv", "bin", "hermes"),
+  ],
+  codex: [
+    process.env.CODEX_CLI_BIN,
+    "codex",
+  ],
+};
+
+function isExecutable(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function commandExists(command) {
+  const result = spawnSync(command, ["--help"], { stdio: "ignore", shell: false });
+  return !result.error && result.status !== 127;
+}
+
+function probeCandidate(candidate) {
+  if (!candidate) return null;
+  if (path.isAbsolute(candidate)) {
+    return isExecutable(candidate) ? candidate : null;
+  }
+  return commandExists(candidate) ? candidate : null;
+}
+
+export function detectAgentKind(preferredKind) {
+  const kind = String(preferredKind || "").toLowerCase();
+  if (kind === "codex") return "codex";
+  if (kind === "hermes") return "hermes";
+  if (probeCandidate(process.env.CODEX_CLI_BIN) || commandExists("codex")) return "codex";
+  return "hermes";
+}
+
+export function detectAgentBinary(kind) {
+  const lower = String(kind || "hermes").toLowerCase();
+  const candidates = CANDIDATES[lower] || CANDIDATES.hermes;
+  for (const candidate of candidates) {
+    const resolved = probeCandidate(candidate);
+    if (resolved) return resolved;
+  }
+  return lower === "codex" ? "codex" : "hermes";
+}
+
+export function defaultAgentArgs(kind) {
+  if (String(kind).toLowerCase() === "codex") {
+    return ["exec", "--skip-git-repo-check", "--full-auto", "{prompt}"];
+  }
+  return ["chat", "-Q", "--source", "automatic-bridge", "-q", "{prompt}"];
+}
+
+export function commandAvailable(binary) {
+  if (!binary) return false;
+  if (path.isAbsolute(binary)) return isExecutable(binary);
+  return commandExists(binary);
+}

package/src/main.mjs

@@ -0,0 +1,198 @@
+import path from "node:path";
+import { commandAvailable, detectAgentBinary, detectAgentKind } from "./detect.mjs";
+import { getAuthStatus } from "./client.mjs";
+import { loadConfig, writeInitConfig } from "./config.mjs";
+import { bootstrapChannel, createState, runLoop, runSmoke, stepChannel } from "./runner.mjs";
+import { defaultConfigFile, log, pathExists } from "./utils.mjs";
+
+function printUsage() {
+  console.log(`automatic-bridge
+
+Usage:
+  automatic-bridge doctor [--config <path>]
+  automatic-bridge init [--config <path>] [--force]
+  automatic-bridge once [--config <path>]
+  automatic-bridge smoke [--config <path>] [--probe-text <text>]
+  automatic-bridge run [--config <path>]
+
+Options are also read from env and config file.
+`);
+}
+
+function parseArgv(argv) {
+  const args = [...argv];
+  const command = args.find((arg) => !arg.startsWith("--")) || "help";
+  const options = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) continue;
+    const [flag, inline] = arg.slice(2).split(/=(.*)/s, 2);
+    const key = flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (inline !== undefined) {
+      options[key] = inline;
+      continue;
+    }
+    const next = args[i + 1];
+    if (next && !next.startsWith("--")) {
+      options[key] = next;
+      i += 1;
+    } else {
+      options[key] = true;
+    }
+  }
+  return { command, options };
+}
+
+function summarizeConfig(config) {
+  return {
+    configPath: config.configPath,
+    baseUrl: config.baseUrl,
+    channelIds: config.channelIds,
+    agentKind: config.agentKind,
+    agentBin: config.agentBin,
+    agentArgs: config.agentArgs,
+    pollIntervalMs: config.pollIntervalMs,
+    historyLimit: config.historyLimit,
+    replyLimit: config.replyLimit,
+    agentTimeoutMs: config.agentTimeoutMs,
+    statePath: config.statePath,
+    apiKeyPresent: Boolean(config.apiKey),
+  };
+}
+
+async function commandDoctor(config) {
+  const report = {
+    ...summarizeConfig(config),
+    cliDetected: {
+      kind: detectAgentKind(config.agentKind),
+      binary: detectAgentBinary(config.agentKind),
+    },
+    checks: [],
+  };
+
+  if (!config.channelIds.length) {
+    report.checks.push({ ok: false, check: "channelIds", message: "No channel IDs configured" });
+  } else {
+    report.checks.push({ ok: true, check: "channelIds", message: config.channelIds.join(",") });
+  }
+
+  report.checks.push({
+    ok: Boolean(config.baseUrl),
+    check: "baseUrl",
+    message: config.baseUrl,
+  });
+
+  report.checks.push({
+    ok: Boolean(config.agentBin),
+    check: "agentBin",
+    message: config.agentBin,
+  });
+
+  report.checks.push({
+    ok: commandAvailable(config.agentBin),
+    check: "agentBin:available",
+    message: commandAvailable(config.agentBin) ? "available" : "not found",
+  });
+
+  if (config.channelIds[0]) {
+    try {
+      const auth = await getAuthStatus(config.baseUrl, config.channelIds[0]);
+      report.checks.push({ ok: true, check: "auth/status", message: auth });
+    } catch (error) {
+      report.checks.push({ ok: false, check: "auth/status", message: error?.message || String(error) });
+    }
+  }
+
+  const ok = report.checks.every((check) => check.ok);
+  console.log(JSON.stringify(report, null, 2));
+  process.exitCode = ok ? 0 : 1;
+}
+
+async function commandInit(config, options) {
+  const targetPath = path.resolve(String(options.configPath || config.configPath || defaultConfigFile()));
+  const force = Boolean(options.force);
+  if (!force && await pathExists(targetPath)) {
+    console.log(`[automatic-bridge] config exists: ${targetPath} (use --force to overwrite)`);
+    return;
+  }
+  const payload = await writeInitConfig(targetPath, config);
+  console.log(JSON.stringify({ written: targetPath, config: payload }, null, 2));
+}
+
+async function loadStates(config) {
+  return config.channelIds.map((channelId) => createState(channelId, config));
+}
+
+async function bootstrapAll(states, config) {
+  for (const state of states) {
+    await bootstrapChannel(state, config.baseUrl);
+  }
+}
+
+async function commandOnce(config) {
+  const states = await loadStates(config);
+  await bootstrapAll(states, config);
+  let processed = 0;
+  for (const state of states) {
+    const results = await stepChannel(state, config.baseUrl);
+    processed += results.filter(Boolean).length;
+  }
+  console.log(JSON.stringify({ ok: true, processed, channels: config.channelIds }, null, 2));
+}
+
+async function commandSmoke(config, options) {
+  if (!config.channelIds.length) {
+    throw new Error("smoke requires at least one channel id");
+  }
+  const state = createState(config.channelIds[0], config);
+  await bootstrapChannel(state, config.baseUrl);
+  const probeText = options.probeText || `automatic-bridge-smoke-${Date.now()}`;
+  const result = await runSmoke(config.baseUrl, state, probeText, Number(options.timeoutMs || config.agentTimeoutMs || 60_000));
+  console.log(JSON.stringify({ ok: true, probeText, result: { created: Boolean(result.created), replyCount: result.result.length } }, null, 2));
+}
+
+async function commandRun(config) {
+  if (!config.channelIds.length) {
+    throw new Error("No channel IDs configured");
+  }
+  const states = await loadStates(config);
+  await bootstrapAll(states, config);
+  const shutdown = () => {
+    log("shutdown requested");
+    for (const state of states) state.stopped = true;
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  await Promise.all(states.map((state) => runLoop(state, config.baseUrl, config.pollIntervalMs)));
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const { command, options } = parseArgv(argv);
+  if (command === "help" || options.help || options.h) {
+    printUsage();
+    return;
+  }
+
+  const config = await loadConfig(options, { argv });
+
+  switch (command) {
+    case "doctor":
+      await commandDoctor(config);
+      return;
+    case "init":
+      await commandInit(config, options);
+      return;
+    case "once":
+      await commandOnce(config);
+      return;
+    case "smoke":
+      await commandSmoke(config, options);
+      return;
+    case "run":
+      await commandRun(config);
+      return;
+    default:
+      printUsage();
+      process.exitCode = 1;
+  }
+}

package/src/runner.mjs

@@ -0,0 +1,217 @@
+import { spawn } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
+import { defaultAgentArgs, detectAgentBinary } from "./detect.mjs";
+import { getMessages, postAgentMessage, postUserMessage } from "./client.mjs";
+import { log, makePrompt, parseIntValue, splitCommandLine, truncate } from "./utils.mjs";
+
+export function buildTranscript(messages, limit) {
+  const tail = messages.slice(Math.max(0, messages.length - limit));
+  return tail
+    .map((message) => {
+      const role = message.sender === "agent" ? "AGENT" : "USER";
+      return `${role}: ${message.content}`;
+    })
+    .join("\n");
+}
+
+export function createState(channelId, config) {
+  return {
+    channelId,
+    history: [],
+    seenIds: new Set(),
+    lastId: 0,
+    errorStreak: 0,
+    stopped: false,
+    historyLimit: config.historyLimit,
+    replyLimit: config.replyLimit,
+    apiKey: config.apiKey,
+    agentKind: config.agentKind,
+    agentBin: config.agentBin,
+    agentArgs: config.agentArgs,
+    promptTemplate: config.promptTemplate,
+  };
+}
+
+function appendUniqueMessage(state, message) {
+  if (state.seenIds.has(message.id)) return false;
+  state.seenIds.add(message.id);
+  state.history.push(message);
+  return true;
+}
+
+function resolveAgentCommand(state, prompt) {
+  const kind = String(state.agentKind || "hermes").toLowerCase();
+  const bin = state.agentBin || detectAgentBinary(kind);
+  const templateArgs = state.agentArgs?.length ? state.agentArgs : defaultAgentArgs(kind);
+  const args = [];
+  let insertedPrompt = false;
+  for (const part of templateArgs) {
+    if (part === "{prompt}") {
+      args.push(prompt);
+      insertedPrompt = true;
+    } else {
+      args.push(part);
+    }
+  }
+  if (!insertedPrompt) args.push(prompt);
+  return { kind, bin, args };
+}
+
+function parseAgentOutput(kind, output) {
+  const text = String(output ?? "").replace(/\r/g, "").trim();
+  if (!text) return "";
+
+  if (kind === "codex") {
+    const lines = text.split("\n").map((line) => line.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      const line = lines[i];
+      if (!line.startsWith("tokens used") && !line.startsWith("warning:")) {
+        return line;
+      }
+    }
+    return lines[lines.length - 1] || "";
+  }
+
+  const lines = text.split("\n");
+  const cleaned = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      if (cleaned.length > 0 && cleaned[cleaned.length - 1] !== "") {
+        cleaned.push("");
+      }
+      continue;
+    }
+    if (trimmed.startsWith("session_id:")) break;
+    if (trimmed.startsWith("╭") || trimmed.startsWith("╰") || trimmed.startsWith("│")) continue;
+    cleaned.push(line.trimEnd());
+  }
+  while (cleaned.length && cleaned[0] === "") cleaned.shift();
+  while (cleaned.length && cleaned[cleaned.length - 1] === "") cleaned.pop();
+  return cleaned.join("\n").trim();
+}
+
+function runAgent(state, prompt) {
+  return new Promise((resolve, reject) => {
+    const { kind, bin, args } = resolveAgentCommand(state, prompt);
+    const child = spawn(bin, args, {
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+    });
+
+    let stdout = "";
+    let stderr = "";
+    const timeoutMs = parseIntValue(process.env.BRIDGE_AGENT_TIMEOUT_MS, 120_000);
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 3000).unref?.();
+      reject(new Error(`${kind} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+
+    child.on("error", (error) => {
+      clearTimeout(timeout);
+      reject(error);
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      if (code !== 0) {
+        reject(new Error(`${kind} exited with code ${code}: ${stderr.trim() || stdout.trim()}`));
+        return;
+      }
+      const reply = parseAgentOutput(kind, stdout || stderr);
+      resolve(reply);
+    });
+  });
+}
+
+export async function bootstrapChannel(state, baseUrl) {
+  const data = await getMessages(baseUrl, state.channelId, 0, "all");
+  const messages = Array.isArray(data?.messages) ? data.messages : [];
+  state.history = [];
+  state.seenIds = new Set();
+  for (const message of messages) appendUniqueMessage(state, message);
+  state.lastId = messages.length ? messages[messages.length - 1].id : 0;
+  log(`channel=${state.channelId}`, `bootstrapped last_id=${state.lastId} history=${state.history.length}`);
+}
+
+export async function processUserMessage(state, baseUrl, message) {
+  const transcript = buildTranscript(state.history, state.historyLimit);
+  const prompt = makePrompt(state.promptTemplate, {
+    channelId: state.channelId,
+    message: message.content,
+    history: transcript || "(no prior conversation)",
+    prompt: "",
+  });
+  log(`channel=${state.channelId}`, `asking agent for user message #${message.id}`);
+  const replyRaw = await runAgent(state, prompt);
+  const reply = truncate(replyRaw.trim(), state.replyLimit);
+  if (!reply) {
+    log(`channel=${state.channelId}`, `agent returned empty reply for message #${message.id}`);
+    return null;
+  }
+  const result = await postAgentMessage(baseUrl, state.channelId, reply, state.apiKey);
+  const posted = result?.message;
+  if (posted) appendUniqueMessage(state, posted);
+  log(`channel=${state.channelId}`, `posted agent reply${posted?.id ? ` #${posted.id}` : ""}`);
+  return posted ?? result ?? null;
+}
+
+export async function stepChannel(state, baseUrl) {
+  const data = await getMessages(baseUrl, state.channelId, state.lastId, "all");
+  const messages = Array.isArray(data?.messages) ? data.messages : [];
+  if (!messages.length) return [];
+
+  const userMessages = [];
+  for (const message of messages) {
+    appendUniqueMessage(state, message);
+    if (message.id > state.lastId) state.lastId = message.id;
+    if (message.sender === "user") userMessages.push(message);
+  }
+
+  const results = [];
+  for (const userMessage of userMessages) {
+    results.push(await processUserMessage(state, baseUrl, userMessage));
+  }
+  return results;
+}
+
+export async function runLoop(state, baseUrl, pollIntervalMs) {
+  while (!state.stopped) {
+    try {
+      await stepChannel(state, baseUrl);
+      state.errorStreak = 0;
+      await sleep(pollIntervalMs);
+    } catch (error) {
+      state.errorStreak += 1;
+      const backoff = Math.min(15_000, pollIntervalMs * Math.min(8, 2 ** state.errorStreak));
+      log(`channel=${state.channelId}`, `poll failed`, error?.message || error, `backoff=${backoff}ms`);
+      await sleep(backoff);
+    }
+  }
+}
+
+export async function runSmoke(baseUrl, state, probeText, timeoutMs = 60_000) {
+  const probe = probeText || `automatic-bridge-smoke-${Date.now()}`;
+  const startAt = Date.now();
+  const created = await postUserMessage(baseUrl, state.channelId, probe);
+  const createdId = created?.message?.id ?? created?.id ?? null;
+  log(`channel=${state.channelId}`, `probe sent${createdId ? ` #${createdId}` : ""}`, JSON.stringify(probe));
+
+  while (Date.now() - startAt < timeoutMs) {
+    const result = await stepChannel(state, baseUrl);
+    if (result.length > 0) return { probe, created, result };
+    await sleep(1000);
+  }
+
+  throw new Error(`Smoke test timed out after ${timeoutMs}ms`);
+}

package/src/utils.mjs

@@ -0,0 +1,85 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export const PREFIX = "[automatic-bridge]";
+
+export function log(...args) {
+  console.log(PREFIX, new Date().toISOString(), ...args);
+}
+
+export function warn(...args) {
+  console.warn(PREFIX, new Date().toISOString(), ...args);
+}
+
+export function parseList(value) {
+  return String(value ?? "")
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function parseIntValue(value, fallback) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+export function truncate(text, limit) {
+  const string = String(text ?? "");
+  if (string.length <= limit) return string;
+  return `${string.slice(0, Math.max(0, limit - 1))}…`;
+}
+
+export function expandHome(input) {
+  const value = String(input ?? "");
+  if (!value.startsWith("~")) return value;
+  return path.join(os.homedir(), value.slice(1));
+}
+
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readJson(filePath) {
+  const text = await fs.readFile(filePath, "utf8");
+  return JSON.parse(text);
+}
+
+export async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export function homeConfigDir() {
+  return path.join(os.homedir(), ".config", "automatic-bridge");
+}
+
+export function defaultStateFile() {
+  return path.join(homeConfigDir(), "state.json");
+}
+
+export function defaultConfigFile() {
+  return path.join(homeConfigDir(), "config.json");
+}
+
+export function splitCommandLine(value) {
+  return parseList(value).filter(Boolean);
+}
+
+export function replacePlaceholders(template, values) {
+  return String(template)
+    .replaceAll("{channelId}", values.channelId ?? "")
+    .replaceAll("{message}", values.message ?? "")
+    .replaceAll("{history}", values.history ?? "")
+    .replaceAll("{prompt}", values.prompt ?? "");
+}
+
+export function makePrompt(template, values) {
+  return replacePlaceholders(template, values);
+}