@openparachute/agent 0.1.1 → 0.2.0

package/src/registry.test.ts

@@ -0,0 +1,227 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  resolveChannelEntries,
+  instantiateTransport,
+  loadRegistry,
+  defaultStateDir,
+  type ChannelEntry,
+} from "./registry.ts";
+
+let dir: string;
+const savedToken = process.env.TELEGRAM_BOT_TOKEN;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "channel-registry-"));
+  delete process.env.TELEGRAM_BOT_TOKEN;
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+  if (savedToken === undefined) delete process.env.TELEGRAM_BOT_TOKEN;
+  else process.env.TELEGRAM_BOT_TOKEN = savedToken;
+});
+
+describe("no env synthesis — channels are always explicit", () => {
+  test("no channels.json + TELEGRAM_BOT_TOKEN set → [] (env is NOT a token source)", () => {
+    process.env.TELEGRAM_BOT_TOKEN = "dummy-token";
+    const entries = resolveChannelEntries({ stateDir: dir, loadEnv: false });
+    expect(entries).toEqual([]);
+  });
+
+  test("no channels.json + token only in state-dir .env → still [] after loadEnv", () => {
+    // .env is still loaded (generic vars may live there), but a TELEGRAM_BOT_TOKEN
+    // there no longer synthesizes a channel — per-channel config is required.
+    writeFileSync(join(dir, ".env"), "TELEGRAM_BOT_TOKEN=from-env-file\n");
+    const entries = resolveChannelEntries({ stateDir: dir, loadEnv: true });
+    expect(entries).toEqual([]);
+  });
+
+  test("no channels.json + no token → empty list (caller decides to error)", () => {
+    const entries = resolveChannelEntries({ stateDir: dir, loadEnv: false });
+    expect(entries).toEqual([]);
+  });
+});
+
+describe("explicit channels.json parsing", () => {
+  test("parses multiple named channels", () => {
+    const file = {
+      channels: [
+        { name: "tele-aaron", transport: "telegram", config: { token: "t1" } },
+        { name: "ops", transport: "telegram", config: { token: "t2" } },
+      ],
+    };
+    writeFileSync(join(dir, "channels.json"), JSON.stringify(file));
+    const entries = resolveChannelEntries({ stateDir: dir, loadEnv: false });
+    expect(entries).toHaveLength(2);
+    expect(entries[0]!.name).toBe("tele-aaron");
+    expect(entries[1]!.transport).toBe("telegram");
+  });
+
+  test("channels.json takes precedence over the token fallback", () => {
+    process.env.TELEGRAM_BOT_TOKEN = "dummy";
+    writeFileSync(
+      join(dir, "channels.json"),
+      JSON.stringify({ channels: [{ name: "explicit", transport: "telegram", config: { token: "x" } }] }),
+    );
+    const entries = resolveChannelEntries({ stateDir: dir, loadEnv: false });
+    expect(entries).toEqual([{ name: "explicit", transport: "telegram", config: { token: "x" } }]);
+  });
+
+  test("missing 'channels' array throws clearly", () => {
+    writeFileSync(join(dir, "channels.json"), JSON.stringify({ nope: true }));
+    expect(() => resolveChannelEntries({ stateDir: dir, loadEnv: false })).toThrow(/channels/);
+  });
+
+  test("entry missing name or transport throws clearly", () => {
+    writeFileSync(join(dir, "channels.json"), JSON.stringify({ channels: [{ name: "x" }] }));
+    expect(() => resolveChannelEntries({ stateDir: dir, loadEnv: false })).toThrow(/transport/);
+  });
+});
+
+describe("instantiateTransport", () => {
+  test("telegram entry yields a telegram transport", () => {
+    const entry: ChannelEntry = { name: "t", transport: "telegram", config: { token: "tok" } };
+    const t = instantiateTransport(entry);
+    expect(t.kind).toBe("telegram");
+  });
+
+  test("unknown transport kind errors clearly", () => {
+    const entry: ChannelEntry = { name: "weird", transport: "carrier-pigeon" };
+    expect(() => instantiateTransport(entry)).toThrow(/unknown transport kind "carrier-pigeon"/);
+  });
+
+  test("telegram entry with no token errors clearly (names the channel)", () => {
+    const entry: ChannelEntry = { name: "t", transport: "telegram" };
+    expect(() => instantiateTransport(entry)).toThrow(
+      /telegram channel t requires a per-channel bot token/,
+    );
+  });
+});
+
+describe("loadRegistry", () => {
+  test("builds a live channel map keyed by name", () => {
+    writeFileSync(
+      join(dir, "channels.json"),
+      JSON.stringify({
+        channels: [
+          { name: "a", transport: "telegram", config: { token: "t1", stateDir: dir } },
+          { name: "b", transport: "telegram", config: { token: "t2", stateDir: dir } },
+        ],
+      }),
+    );
+    const reg = loadRegistry({ stateDir: dir, loadEnv: false });
+    expect([...reg.keys()].sort()).toEqual(["a", "b"]);
+    expect(reg.get("a")!.transport.kind).toBe("telegram");
+  });
+
+  test("duplicate channel names throw", () => {
+    writeFileSync(
+      join(dir, "channels.json"),
+      JSON.stringify({
+        channels: [
+          { name: "dup", transport: "telegram", config: { token: "t1", stateDir: dir } },
+          { name: "dup", transport: "telegram", config: { token: "t2", stateDir: dir } },
+        ],
+      }),
+    );
+    expect(() => loadRegistry({ stateDir: dir, loadEnv: false })).toThrow(/duplicate channel name/);
+  });
+
+  test("unknown transport kind surfaces from loadRegistry", () => {
+    writeFileSync(
+      join(dir, "channels.json"),
+      JSON.stringify({ channels: [{ name: "x", transport: "smoke-signal" }] }),
+    );
+    expect(() => loadRegistry({ stateDir: dir, loadEnv: false })).toThrow(/unknown transport kind/);
+  });
+});
+
+// ===========================================================================
+// defaultStateDir — channel→agent rename + back-compat resolution.
+//
+// Resolution order (registry.ts):
+//   1. PARACHUTE_AGENT_STATE_DIR env → legacy PARACHUTE_CHANNEL_STATE_DIR (via
+//      env-compat.agentEnv) — explicit override.
+//   2. ~/.parachute/agent (the NEW default) if it exists.
+//   3. Back-compat: ~/.parachute/channel (legacy) if it exists and agent does not.
+//   4. ~/.parachute/agent (the new default) when neither exists.
+//
+// `defaultStateDir(home?)` takes an injectable home so we exercise the
+// home-dir-default + legacy-fallback branches against a throwaway dir WITHOUT a
+// process-wide `mock.module("os")` — which would leak a faked `homedir()` into
+// other test files (it broke the live-Seatbelt path-confinement tests when an
+// earlier version did exactly that).
+// ===========================================================================
+
+describe("defaultStateDir — env override (new + legacy)", () => {
+  const savedAgent = process.env.PARACHUTE_AGENT_STATE_DIR;
+  const savedChannel = process.env.PARACHUTE_CHANNEL_STATE_DIR;
+  afterEach(() => {
+    if (savedAgent === undefined) delete process.env.PARACHUTE_AGENT_STATE_DIR;
+    else process.env.PARACHUTE_AGENT_STATE_DIR = savedAgent;
+    if (savedChannel === undefined) delete process.env.PARACHUTE_CHANNEL_STATE_DIR;
+    else process.env.PARACHUTE_CHANNEL_STATE_DIR = savedChannel;
+  });
+
+  test("PARACHUTE_AGENT_STATE_DIR (the new var) wins", () => {
+    delete process.env.PARACHUTE_CHANNEL_STATE_DIR;
+    process.env.PARACHUTE_AGENT_STATE_DIR = "/tmp/explicit-agent-state";
+    expect(defaultStateDir()).toBe("/tmp/explicit-agent-state");
+  });
+
+  test("back-compat: legacy PARACHUTE_CHANNEL_STATE_DIR is still honored when the new var is unset", () => {
+    delete process.env.PARACHUTE_AGENT_STATE_DIR;
+    process.env.PARACHUTE_CHANNEL_STATE_DIR = "/tmp/legacy-channel-state";
+    expect(defaultStateDir()).toBe("/tmp/legacy-channel-state");
+  });
+
+  test("the new PARACHUTE_AGENT_STATE_DIR takes precedence over the legacy one", () => {
+    process.env.PARACHUTE_AGENT_STATE_DIR = "/tmp/new-wins";
+    process.env.PARACHUTE_CHANNEL_STATE_DIR = "/tmp/legacy-loses";
+    expect(defaultStateDir()).toBe("/tmp/new-wins");
+  });
+});
+
+describe("defaultStateDir — home-dir default + legacy-dir back-compat", () => {
+  let home: string;
+  const savedAgent = process.env.PARACHUTE_AGENT_STATE_DIR;
+  const savedChannel = process.env.PARACHUTE_CHANNEL_STATE_DIR;
+
+  beforeEach(() => {
+    // A throwaway HOME passed straight to defaultStateDir(home); no env override so
+    // the existence checks drive resolution. No os mock — see the note above.
+    home = mkdtempSync(join(tmpdir(), "agent-home-"));
+    delete process.env.PARACHUTE_AGENT_STATE_DIR;
+    delete process.env.PARACHUTE_CHANNEL_STATE_DIR;
+  });
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+    if (savedAgent === undefined) delete process.env.PARACHUTE_AGENT_STATE_DIR;
+    else process.env.PARACHUTE_AGENT_STATE_DIR = savedAgent;
+    if (savedChannel === undefined) delete process.env.PARACHUTE_CHANNEL_STATE_DIR;
+    else process.env.PARACHUTE_CHANNEL_STATE_DIR = savedChannel;
+  });
+
+  test("the new default is ~/.parachute/agent when neither dir exists", () => {
+    expect(defaultStateDir(home)).toBe(join(home, ".parachute", "agent"));
+  });
+
+  test("uses the new ~/.parachute/agent when it exists", () => {
+    mkdirSync(join(home, ".parachute", "agent"), { recursive: true });
+    expect(defaultStateDir(home)).toBe(join(home, ".parachute", "agent"));
+  });
+
+  test("back-compat: uses legacy ~/.parachute/channel when ~/.parachute/agent is absent", () => {
+    mkdirSync(join(home, ".parachute", "channel"), { recursive: true });
+    expect(defaultStateDir(home)).toBe(join(home, ".parachute", "channel"));
+  });
+
+  test("the new agent dir wins even when the legacy channel dir also exists", () => {
+    mkdirSync(join(home, ".parachute", "agent"), { recursive: true });
+    mkdirSync(join(home, ".parachute", "channel"), { recursive: true });
+    expect(defaultStateDir(home)).toBe(join(home, ".parachute", "agent"));
+  });
+});

package/src/registry.ts

@@ -0,0 +1,228 @@
+/**
+ * Channel registry.
+ *
+ * Loads named channels from `channels.json` in the channel state dir and
+ * instantiates a Transport per entry. A channel is a name bound to a transport
+ * kind plus optional transport config.
+ *
+ * Every channel is explicit: with no `channels.json` the daemon resolves to
+ * zero channels. There is NO daemon-global TELEGRAM_BOT_TOKEN synthesis — each
+ * telegram channel carries its own per-channel bot token in its config.
+ */
+
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { agentEnv } from "./env-compat.ts";
+import type { Transport } from "./transport.ts";
+import { TelegramTransport, type TelegramTransportConfig } from "./transports/telegram.ts";
+import { HttpUiTransport, type HttpUiTransportConfig } from "./transports/http-ui.ts";
+import { VaultTransport, type VaultTransportConfig } from "./transports/vault.ts";
+
+export interface ChannelEntry {
+  name: string;
+  transport: string;
+  config?: Record<string, unknown>;
+}
+
+export interface ChannelsFile {
+  channels: ChannelEntry[];
+}
+
+/** A live channel: its config entry plus the instantiated transport. */
+export interface Channel {
+  name: string;
+  transport: Transport;
+  entry: ChannelEntry;
+}
+
+/**
+ * The agent module's state dir. Resolution, in order:
+ *
+ *   1. `PARACHUTE_AGENT_STATE_DIR` env → its legacy alias
+ *      `PARACHUTE_CHANNEL_STATE_DIR` (via {@link agentEnv}) — the explicit override.
+ *   2. The new default `~/.parachute/agent`.
+ *   3. **Back-compat:** if `~/.parachute/agent` does NOT exist but the legacy
+ *      `~/.parachute/channel` DOES, use the legacy dir — so an operator's existing
+ *      config/credentials/sessions keep working with no manual move across the
+ *      channel→agent rename. Once `~/.parachute/agent` exists (a fresh install, or
+ *      after a manual move) it wins and the legacy dir is ignored.
+ *
+ * `home` is injectable for tests (default `homedir()`) so the home-dir-default +
+ * legacy-fallback branches can be exercised against a throwaway dir WITHOUT a
+ * process-wide `mock.module("os")` (which leaks `homedir()` into other test files
+ * — it broke the live-Seatbelt path-confinement tests when it did).
+ *
+ * (Migration `parachute-patterns/migrations/2026-06-17-channel-to-agent.md`.)
+ */
+export function defaultStateDir(home: string = homedir()): string {
+  const explicit = agentEnv("STATE_DIR");
+  if (explicit) return explicit;
+  const agentDir = join(home, ".parachute", "agent");
+  if (existsSync(agentDir)) return agentDir;
+  const legacyDir = join(home, ".parachute", "channel");
+  if (existsSync(legacyDir)) return legacyDir;
+  return agentDir;
+}
+
+/**
+ * Load the state dir's `.env` into process.env if not already set. Generic —
+ * an operator may keep arbitrary vars there (e.g. PARACHUTE_HUB_ORIGIN). The
+ * daemon no longer consumes TELEGRAM_BOT_TOKEN; telegram tokens live per-channel
+ * in channels.json. Mirrors the original daemon's `.env` loading behavior.
+ */
+export function loadEnvFile(stateDir: string): void {
+  const envFile = join(stateDir, ".env");
+  try {
+    if (existsSync(envFile)) {
+      chmodSync(envFile, 0o600);
+      for (const line of readFileSync(envFile, "utf8").split("\n")) {
+        const m = line.match(/^(\w+)=(.*)$/);
+        if (m && process.env[m[1]!] === undefined) process.env[m[1]!] = m[2]!;
+      }
+    }
+  } catch {}
+}
+
+/** Instantiate the Transport for a single channel entry. */
+export function instantiateTransport(entry: ChannelEntry): Transport {
+  switch (entry.transport) {
+    case "telegram":
+      // Thread the channel name in so a missing-token error names the channel.
+      return new TelegramTransport({
+        ...(entry.config ?? {}),
+        name: entry.name,
+      } as TelegramTransportConfig);
+    case "http-ui":
+      // http-ui needs no secret — just a channel name (taken from ctx at start).
+      return new HttpUiTransport((entry.config ?? {}) as HttpUiTransportConfig);
+    case "vault":
+      // vault needs vault name + a write token + the inbound-webhook secret.
+      return new VaultTransport((entry.config ?? {}) as unknown as VaultTransportConfig);
+    default:
+      throw new Error(
+        `registry: unknown transport kind "${entry.transport}" for channel "${entry.name}" ` +
+          `(known: telegram, http-ui, vault)`,
+      );
+  }
+}
+
+/**
+ * Resolve the channel entries for this install. Reads channels.json if present;
+ * otherwise resolves to `[]` (no channels) — explicit per-channel config is
+ * required, there is no env-token synthesis.
+ *
+ * `loadEnv` (default true) still loads the state-dir `.env` for any generic vars
+ * an operator keeps there. Tests pass `loadEnv: false` to stay hermetic.
+ */
+export function resolveChannelEntries(opts: {
+  stateDir?: string;
+  loadEnv?: boolean;
+} = {}): ChannelEntry[] {
+  const stateDir = opts.stateDir ?? defaultStateDir();
+  if (opts.loadEnv !== false) loadEnvFile(stateDir);
+
+  const channelsFile = join(stateDir, "channels.json");
+  if (existsSync(channelsFile)) {
+    const parsed = JSON.parse(readFileSync(channelsFile, "utf8")) as ChannelsFile;
+    if (!parsed || !Array.isArray(parsed.channels)) {
+      throw new Error(`registry: ${channelsFile} must have a "channels" array`);
+    }
+    for (const entry of parsed.channels) {
+      if (!entry.name || !entry.transport) {
+        throw new Error(
+          `registry: each channel needs "name" and "transport" (got ${JSON.stringify(entry)})`,
+        );
+      }
+    }
+    return parsed.channels;
+  }
+
+  // No channels.json → no channels. Explicit per-channel config is now
+  // required; there is no daemon-global TELEGRAM_BOT_TOKEN synthesis. Each
+  // telegram channel carries its OWN bot token in channels.json (created via
+  // the admin UI), so the daemon never depends on a global env token.
+  return [];
+}
+
+/** Absolute path to the channels.json registry file in a state dir. */
+export function channelsFilePath(stateDir?: string): string {
+  return join(stateDir ?? defaultStateDir(), "channels.json");
+}
+
+/**
+ * Read the channels.json registry as a plain `ChannelsFile`, WITHOUT
+ * instantiating transports or synthesizing the telegram fallback. Returns an
+ * empty `{ channels: [] }` if the file is absent. Used by the config-management
+ * API to read-modify-write the file while the daemon holds the live channels.
+ */
+export function readChannelsFile(stateDir?: string): ChannelsFile {
+  const file = channelsFilePath(stateDir);
+  if (!existsSync(file)) return { channels: [] };
+  const parsed = JSON.parse(readFileSync(file, "utf8")) as ChannelsFile;
+  if (!parsed || !Array.isArray(parsed.channels)) {
+    throw new Error(`registry: ${file} must have a "channels" array`);
+  }
+  return parsed;
+}
+
+/**
+ * Upsert a channel entry into channels.json (preserving every other entry) and
+ * write it back with 0600 perms — the file holds transport tokens/secrets. If an
+ * entry with the same name exists it's REPLACED in place (same position);
+ * otherwise the new entry is appended. Creates the state dir if needed. Returns
+ * the persisted file contents.
+ */
+export function upsertChannelEntry(entry: ChannelEntry, stateDir?: string): ChannelsFile {
+  const dir = stateDir ?? defaultStateDir();
+  mkdirSync(dir, { recursive: true });
+  const file = channelsFilePath(dir);
+  const current = readChannelsFile(dir);
+  const idx = current.channels.findIndex((c) => c.name === entry.name);
+  if (idx >= 0) current.channels[idx] = entry;
+  else current.channels.push(entry);
+  writeFileSync(file, JSON.stringify(current, null, 2) + "\n", { mode: 0o600 });
+  // writeFileSync's mode only applies on CREATE; chmod unconditionally so an
+  // existing file (created before this code, or with a looser umask) is tightened.
+  chmodSync(file, 0o600);
+  return current;
+}
+
+/**
+ * Remove a channel entry from channels.json by name, preserving the rest. Returns
+ * the persisted file contents, or null if the file didn't exist. A no-op (name
+ * absent) still rewrites the file (idempotent) when the file exists.
+ */
+export function removeChannelEntry(name: string, stateDir?: string): ChannelsFile | null {
+  const dir = stateDir ?? defaultStateDir();
+  const file = channelsFilePath(dir);
+  if (!existsSync(file)) return null;
+  const current = readChannelsFile(dir);
+  current.channels = current.channels.filter((c) => c.name !== name);
+  writeFileSync(file, JSON.stringify(current, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(file, 0o600);
+  return current;
+}
+
+/**
+ * Build the live channel map: resolve entries, instantiate each transport.
+ * Throws if an entry names an unknown transport kind.
+ */
+export function loadRegistry(opts: {
+  stateDir?: string;
+  loadEnv?: boolean;
+} = {}): Map<string, Channel> {
+  const entries = resolveChannelEntries(opts);
+  const channels = new Map<string, Channel>();
+  for (const entry of entries) {
+    if (channels.has(entry.name)) {
+      throw new Error(`registry: duplicate channel name "${entry.name}"`);
+    }
+    channels.set(entry.name, {
+      name: entry.name,
+      transport: instantiateTransport(entry),
+      entry,
+    });
+  }
+  return channels;
+}

package/src/resolve-port.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Port-resolution tests (channel#41).
+ *
+ * The hub supervisor injects `PORT` from the module's services.json `entry.port`
+ * and PROBES that same port for readiness (and reverse-proxies `/agent/*` to
+ * it). Pre-#41 the daemon read only `PARACHUTE_AGENT_PORT` (default 1941), so
+ * it ignored the supervisor's `PORT` and could bind a different port than the
+ * supervisor probed — the supervisor then reported `started_but_unbound` and the
+ * proxy routed to a dead port. `resolvePort` now honors `PORT` first so the bound
+ * port (which is also the self-registered port) matches what the supervisor
+ * assigned.
+ *
+ * Resolution order: `PORT > PARACHUTE_AGENT_PORT > PARACHUTE_CHANNEL_PORT > 1941`.
+ * The legacy `PARACHUTE_CHANNEL_PORT` stays a recognized fallback (back-compat
+ * for pre-rename operator setups) but the new `PARACHUTE_AGENT_PORT` wins over it.
+ */
+import { describe, test, expect } from "bun:test";
+import { resolvePort } from "./daemon.ts";
+
+describe("resolvePort — PORT > PARACHUTE_AGENT_PORT > PARACHUTE_CHANNEL_PORT > 1941", () => {
+  test("honors the supervisor-injected PORT first", () => {
+    expect(resolvePort({ PORT: "19415" })).toBe(19415);
+  });
+
+  test("PORT wins even when PARACHUTE_AGENT_PORT is also set", () => {
+    expect(resolvePort({ PORT: "1941", PARACHUTE_AGENT_PORT: "19415" })).toBe(1941);
+  });
+
+  test("falls back to PARACHUTE_AGENT_PORT when PORT is unset", () => {
+    expect(resolvePort({ PARACHUTE_AGENT_PORT: "2025" })).toBe(2025);
+  });
+
+  test("the legacy PARACHUTE_CHANNEL_PORT STILL works as a fallback (back-compat)", () => {
+    // Pre-rename operator setups exported PARACHUTE_CHANNEL_PORT; it stays a
+    // recognized tier so those installs keep binding the intended port.
+    expect(resolvePort({ PARACHUTE_CHANNEL_PORT: "2030" })).toBe(2030);
+  });
+
+  test("PARACHUTE_AGENT_PORT wins over the legacy PARACHUTE_CHANNEL_PORT", () => {
+    // Both present → the NEW var takes precedence; the legacy var is only a
+    // fallback for when the new one is absent.
+    expect(resolvePort({ PARACHUTE_AGENT_PORT: "2040", PARACHUTE_CHANNEL_PORT: "2050" })).toBe(2040);
+  });
+
+  test("falls back to the canonical 1941 default when none is set", () => {
+    expect(resolvePort({})).toBe(1941);
+  });
+
+  test("an EMPTY PORT='' falls through to PARACHUTE_AGENT_PORT (|| not ??)", () => {
+    // With `??` an empty string is "defined" → parseInt("") = NaN → bind port 0.
+    // `||` skips the empty string to the next tier.
+    expect(resolvePort({ PORT: "", PARACHUTE_AGENT_PORT: "2000" })).toBe(2000);
+  });
+
+  test("an EMPTY PARACHUTE_AGENT_PORT='' falls through to the legacy PARACHUTE_CHANNEL_PORT", () => {
+    expect(resolvePort({ PARACHUTE_AGENT_PORT: "", PARACHUTE_CHANNEL_PORT: "2060" })).toBe(2060);
+  });
+
+  test("a non-numeric PORT='abc' falls through to the canonical default", () => {
+    // parseInt("abc") = NaN → falsy → falls through past PARACHUTE_AGENT_PORT +
+    // PARACHUTE_CHANNEL_PORT (also unset here) to 1941. No garbage port.
+    expect(resolvePort({ PORT: "abc" })).toBe(1941);
+  });
+});