Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

20.1 KB
Raw Blame
/**
 * CommandSessionManager — registry and lifecycle management for long-running command sessions.
 *
 * Constructed by Environment (one per Session), injected via services and shared by the
 * `exec_command` and `input_command` tools. Registry responsibilities (id allocation, concurrency
 * cap, dispose, process 'exit' fallback) are handled by the generic `BackgroundRegistry` (shared
 * with subagent sessions, see `../background/registry.ts`); this class only retains
 * command-domain logic: spawning processes and assembling the child process environment (vault
 * injection + hardening).
 * Docs: /docs/tools § "Background session caps".
 */
import { statSync } from "node:fs";
import { ManagedSession } from "./session.js";
import { prependPathEnv } from "./path-prepend.js";
import { BackgroundRegistry } from "../background/index.js";
import type { ProxyEnvPolicy, SpawnConfiner } from "../../../interfaces/index.js";

/** Concurrent managed-session cap: evicts once exceeded (exited sessions first, otherwise LRU — killing a background process has bounded cost). */
const MAX_SESSIONS = 64;

/**
 * Hardening overrides applied to the child process environment: suppresses editor/credential
 * prompts/pagers/color etc. that could interact, avoiding a command hanging while waiting for
 * input. `GIT_EDITOR=true` prevents `git commit`/`rebase -i` from popping an editor;
 * `GIT_TERMINAL_PROMPT=0` prevents git from interactively asking for credentials; in pipe mode,
 * git and similar tools already auto-disable the pager, so the `PAGER` entries are just an extra
 * safeguard.
 */
const HARDENED_ENV: NodeJS.ProcessEnv = {
  GIT_EDITOR: "true",
  GIT_TERMINAL_PROMPT: "0",
  TERM: "dumb",
  NO_COLOR: "1",
  PAGER: "cat",
  GIT_PAGER: "cat",
};

/**
 * Variables **removed** from the child environment (removed, not blanked: a program that
 * checks `PORT` for presence rather than value must see nothing at all).
 *
 * `PORT` / `HOST` are stripped because they are never about the command being run. On the
 * serving paths they are the harness's own listener: `penguin web` / `penguin server` write both
 * into their own `process.env` as the channel to the server module (see the CLI's `startServer`).
 * On the CLI-only paths (`penguin run`, `penguin chat`, the REPL) nothing listens at all, but the
 * CLI still loads `dotenv/config`, so a `PORT` there is the one the *user's own project* picked
 * for *its* server. `npm run dev`, Vite, Next and most Express templates read `PORT`, so either
 * way an inherited value makes a server the Agent starts bind a port it was never asked to take —
 * the harness's own in the first case, one already spoken for in the second. A command that needs
 * a particular port should be told so in its own invocation (or through the vault), never by
 * ambient inheritance.
 *
 * `ADELIE_CLI_ENTRY` is internal plumbing: the CLI writes it to tell the server which script to
 * re-run for self-update (the by-name entry below still lists the pre-rename `PENGUIN_CLI_ENTRY`,
 * which is what the desktop shell hands the server). It means nothing to any other program and
 * leaks the install path.
 *
 * `PENGUIN_WEB_DIST` is *not* internal — it is a documented deployment override (see the
 * configuration reference and the server README) — and is stripped anyway because it names this
 * installation's front-end build. In the self-development case an Agent that starts a
 * Adelie server would otherwise serve the deployment's assets instead of the ones it just
 * built in the workspace, silently and with no error to read.
 *
 * `FORCE_COLOR` / `CLICOLOR_FORCE` are color-forcing overrides that Node (and the chalk-family
 * libraries) deliberately let defeat `NO_COLOR`, so an inherited value would cancel the
 * `NO_COLOR=1` + `TERM=dumb` hardening above and leak ANSI escapes into tool output (#102).
 * Removal, not blanking, matters here too: Node reads an *empty* `FORCE_COLOR` as "force 16
 * colors on". The vault still wins, so a user who genuinely wants forced color in commands can
 * set it there.
 *
 * Every `PENGUIN_*` and `ADELIE_*` variable is removed as well — see {@link HARNESS_ENV_PREFIXES}.
 * That covers `PENGUIN_HOME` / `ADELIE_HOME` and `PENGUIN_WEB_DB`, which select the *data* an
 * Agent-started harness works against. They were once left inheriting on the grounds that the
 * self-development case may legitimately want the same data root, but inheriting them is not that
 * decision being made — it
 * is an accident of where this process happens to be running. Whenever an Agent spawns a command
 * the harness is by definition up, holding `<root>/server.lock`, so an Agent-started server on the
 * inherited root cannot start at all; it exits 3 against a lock whose owner is the very process
 * that handed it the root.
 *
 * Any of it really wanted is asked for rather than inherited: the vault is applied after this
 * environment (see the spread in `spawn`), so a `PENGUIN_HOME` set there reaches commands exactly
 * as before. Same escape hatch as `FORCE_COLOR` above.
 */
const STRIPPED_ENV_KEYS = new Set([
  "PORT",
  "HOST",
  "PENGUIN_CLI_ENTRY",
  "PENGUIN_WEB_DIST",
  "FORCE_COLOR",
  "CLICOLOR_FORCE",
  // Desktop-mode process credentials and wiring: the shell's token authorizes the
  // server shutdown endpoint (and the claim link until redeemed), and the port file is
  // the shell's private channel — neither is a user-facing setting, and leaking them
  // into Agent-run commands would let a prompt-injected command stop the server.
  "PENGUIN_DESKTOP_TOKEN",
  "PENGUIN_PORT_FILE",
  // Pinned seed password (tests/e2e): a credential, not a data-selection setting.
  "ADELIE_SEED_ADMIN_PASSWORD",
]);

/**
 * Every variable named `PENGUIN_*` or `ADELIE_*` is this installation's own configuration — where
 * its data lives, which shell it resolved, which release feed it checks, which language its UI
 * speaks — and none of it describes the command an Agent is running. Stripping by prefix rather
 * than by name is the point: the harness reads two dozen of them today and gains more with each
 * feature, and a list has to be remembered at exactly the moment nobody is thinking about it.
 * Twenty-five existed when this was written and a by-name list had caught seven.
 *
 * Two prefixes because the installation carries two spellings of the same settings today:
 * `ADELIE_*` is Adelie's own — the installed launcher exports `ADELIE_HOME`, `ADELIE_WEB_DIST`
 * and `ADELIE_BUNDLED_SHELL` — and `PENGUIN_*` is
 * the pre-rename spelling that existing deployments, systemd units and scripts still set, with
 * the data root read from either. It is not only history: the settings whose *other* end is a
 * program Adelie does not build in this repository (the desktop shell's launch environment, the
 * installer a running CLI downloads) are deliberately still spelled `PENGUIN_*`, so those names
 * are read as well as written today. Covering one and not the other would let the *other*
 * through, and the name that leaks would be the one naming the root this process is serving from.
 *
 * Outbound proxy settings are the deliberate exception to "the harness's environment stays out of
 * the child", and they are not `PENGUIN_*` — they are HTTP_PROXY and friends, governed by
 * {@link PROXY_ENV_KEYS} and the host's policy just below. `ADELIE_TRUST_PROXY` only looks like
 * one: it decides whether the server trusts an inbound `x-forwarded-proto`, and means nothing to
 * a child.
 *
 * The vault still wins, so any single variable that is genuinely wanted can be set there.
 */
const HARNESS_ENV_PREFIXES = ["PENGUIN_", "ADELIE_"] as const;

/**
 * Proxy variables removed IN ADDITION when the host supplies a proxy policy (`proxyEnv`,
 * see {@link CommandSessionManager}): the Web server's proxy settings must keep commands
 * from just inheriting the serving process's proxy environment.
 * In `strip` mode NO_PROXY is deliberately NOT removed — with no proxy variables left it
 * is inert, and removing it would change behavior for commands that set their own proxy.
 * In `inject` mode the inherited NO_PROXY is replaced too (the policy carries the merged
 * list), and ALL_PROXY stays removed rather than replaced: the explicit app-level proxy
 * outranks ambient env wholesale. Matched case-insensitively like
 * {@link STRIPPED_ENV_KEYS}, which also covers the conventional lowercase spellings
 * (http_proxy etc.).
 */
const PROXY_ENV_KEYS = new Set(["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY"]);

/**
 * The host environment minus {@link STRIPPED_ENV_KEYS}, with the proxy policy applied:
 * `strip` removes {@link PROXY_ENV_KEYS}; `inject` additionally replaces NO_PROXY and
 * sets the explicit proxy variables (both spellings — programs disagree on which they
 * read); null passes the proxy variables through untouched.
 */
function hostEnvForChild(policy: ProxyEnvPolicy | null): NodeJS.ProcessEnv {
  const env: NodeJS.ProcessEnv = {};
  // Matched case-insensitively rather than deleting the upper-case spellings: Windows resolves
  // environment names without regard to case but stores whatever casing was written, so a
  // `set Port=3000` before `penguin web` would survive a `delete env.PORT` and still reach the
  // child as PORT. On POSIX the two are distinct names and only the exact one exists.
  for (const [key, value] of Object.entries(process.env)) {
    const name = key.toUpperCase();
    if (STRIPPED_ENV_KEYS.has(name) || HARNESS_ENV_PREFIXES.some((p) => name.startsWith(p)))
      continue;
    if (policy !== null && PROXY_ENV_KEYS.has(name)) continue;
    if (policy?.mode === "inject" && name === "NO_PROXY") continue;
    env[key] = value;
  }
  if (policy?.mode === "inject") {
    env.HTTP_PROXY = policy.url;
    env.http_proxy = policy.url;
    env.HTTPS_PROXY = policy.url;
    env.https_proxy = policy.url;
    env.NO_PROXY = policy.noProxy;
    env.no_proxy = policy.noProxy;
  }
  return env;
}

/**
 * Rejects a working directory that cannot be spawned into, before the spawn.
 *
 * Node reports a missing or unusable `cwd` as `spawn <shell> ENOENT` — the error names the
 * COMMAND, not the directory, so a Workspace that has been deleted or moved reads exactly
 * like a missing shell and sends the reader hunting for a `bash` that was there all along.
 * The directory is therefore checked here, where the real reason can still be named.
 *
 * Never auto-created: Agent.createSession and the server's Workspace guard both refuse to
 * create a Workspace so a typo cannot silently start working in the wrong place, and a
 * directory that disappeared under a live Session is a fact to report rather than paper over.
 *
 * A check before a spawn cannot close the gap between them: a directory removed in that
 * window still produces the old ENOENT. That is the rare case, and the only alternative is
 * re-reading Node's error after the fact, which is the string this exists to stop trusting.
 */
function assertUsableCwd(cwd: string): void {
  let stat;
  try {
    stat = statSync(cwd);
  } catch {
    throw new Error(
      `working directory does not exist: ${cwd}. That is the Session's Workspace unless a workdir was given — restore the directory, or run the command somewhere that exists.`,
    );
  }
  if (!stat.isDirectory()) {
    throw new Error(`working directory is not a directory: ${cwd}.`);
  }
}

export class CommandSessionManager {
  private readonly registry = new BackgroundRegistry<ManagedSession>({
    idPrefix: "proc",
    maxTasks: MAX_SESSIONS,
  });

  /** Agent vault environment variables: injected into the child process on every spawn (values never enter the model context, only the environment). Replaced per model context, see `setVault`. */
  private vault: Record<string, string>;
  /**
   * Proxy policy for the child environment (see {@link ProxyEnvPolicy}: strip the proxy
   * variables, inject an explicit proxy over the inherited ones, or null = pass
   * through). A getter rather than a snapshot: the hosting server's proxy settings
   * change at runtime, and re-reading at every spawn makes a change reach Sessions that
   * are already running. Absent = pass through (SDK/CLI standalone use).
   */
  private readonly proxyEnv: (() => ProxyEnvPolicy | null) | undefined;
  /**
   * Harness-control variables (ADELIE_API_URL / ADELIE_API_TOKEN / the Session
   * coordinates, see {@link EnvironmentConfig.controlEnv}): injected on every spawn AFTER
   * the vault, so the host's sanctioned wiring wins over a vault entry of the same name.
   * A getter like `proxyEnv`, re-read at every spawn. Absent = nothing injected.
   */
  private readonly controlEnv: (() => Record<string, string>) | undefined;
  /**
   * Directories the host puts at the front of PATH for every command (see
   * {@link EnvironmentConfig.pathPrepend}): the hosting server points this at the shim
   * directory holding its own `penguin`, so an Agent's `penguin` is the harness it is
   * running inside rather than whatever the machine has installed globally. A getter like
   * `proxyEnv`, re-read at every spawn. Absent, or returning nothing = untouched PATH.
   */
  private readonly pathPrepend: (() => string[]) | undefined;
  /** Single change listener (see onChange); null until the Environment subscribes. */
  private changeListener: (() => void) | null = null;
  /**
   * Sandbox-confinement seam (see {@link SpawnConfiner}): rewrites the exact argv of
   * every spawn. A getter for the same reason as `proxyEnv`: the active confiner can
   * change at runtime (the hosting server's platform layer is hot-swappable), and
   * re-reading at every spawn makes the change reach Sessions that are already
   * running. Absent, or returning null = commands spawn unconfined.
   */
  private readonly confineSpawn: (() => SpawnConfiner | null) | undefined;
  /**
   * The Session's Workspace root, bound into every confiner call as
   * `opts.workspaceDir` (a workspace-scoped policy must key off the Workspace, not the
   * per-command cwd). Optional for standalone embedders without a Workspace concept;
   * those fall back to the spawn cwd.
   */
  private readonly workspaceDir: string | undefined;
  /** The Session's scratchpad, bound into every confiner call as `opts.scratchpadDir`: writable beside the Workspace under a workspace-write policy. */
  private readonly scratchpadDir: string | undefined;

  constructor(opts?: {
    vault?: Record<string, string>;
    proxyEnv?: () => ProxyEnvPolicy | null;
    controlEnv?: () => Record<string, string>;
    pathPrepend?: () => string[];
    confineSpawn?: () => SpawnConfiner | null;
    workspaceDir?: string;
    scratchpadDir?: string;
  }) {
    this.vault = opts?.vault ?? {};
    this.proxyEnv = opts?.proxyEnv;
    this.controlEnv = opts?.controlEnv;
    this.pathPrepend = opts?.pathPrepend;
    this.confineSpawn = opts?.confineSpawn;
    this.workspaceDir = opts?.workspaceDir;
    this.scratchpadDir = opts?.scratchpadDir;
    this.registry.onChange(() => this.changeListener?.());
  }

  /**
   * Attaches the single listener for changes to the set of running background commands: a
   * session registered, one removed (kill, reap, eviction, dispose), and a registered
   * process reaching its terminal state on its own. Payload-free; subscribers re-read
   * `list()`. A later call replaces the earlier one.
   */
  onChange(listener: () => void): void {
    this.changeListener = listener;
  }

  /**
   * Replaces the vault injected into commands spawned from now on — a new model context
   * re-reads the Agent's vault (see Environment.reconfigure). Sessions already running keep
   * the environment they were spawned with: a process environment cannot be changed after
   * the fact.
   */
  setVault(vault: Record<string, string>): void {
    this.vault = vault;
  }

  /** Starts a command, returning an **unregistered** session (no process_id yet). */
  spawn(opts: { cmd: string; cwd: string }): ManagedSession {
    if (this.registry.isDisposed) {
      throw new Error("command session manager disposed");
    }
    assertUsableCwd(opts.cwd);
    // The host's directories go onto the INHERITED PATH, before the vault is spread over
    // it below: a vault `PATH` is an explicit per-Agent decision and still replaces the
    // whole value, prepended directories included. The same list is handed to the session
    // so the command string can re-assert it after the login profile has run — that is the
    // half that actually decides which `penguin` a command resolves (see ManagedSession).
    const prepend = this.pathPrepend?.() ?? [];
    const hostEnv = prependPathEnv(hostEnvForChild(this.proxyEnv?.() ?? null), prepend);
    const confiner = this.confineSpawn?.() ?? null;
    return new ManagedSession({
      cmd: opts.cmd,
      cwd: opts.cwd,
      ...(prepend.length > 0 ? { pathPrepend: prepend } : {}),
      ...(confiner !== null
        ? {
            confine: (argv: readonly string[], o: { cwd: string }) =>
              confiner(argv, {
                cwd: o.cwd,
                workspaceDir: this.workspaceDir ?? o.cwd,
                ...(this.scratchpadDir !== undefined ? { scratchpadDir: this.scratchpadDir } : {}),
              }),
          }
        : {}),
      // Spread order is priority: vault overrides host variables of the same name; the
      // host's control variables (controlEnv) override the vault — they are the hosting
      // server's own wiring (API URL/token, Session coordinates) and a vault entry must
      // not silently point commands at another server; and HARDENED_ENV comes last — the
      // hardening entries (GIT_EDITOR/PAGER etc. that prevent interactive hangs) are never
      // overridable by anything. The host side is stripped of the harness's own variables
      // first (see STRIPPED_ENV_KEYS) and has the proxyEnv policy applied (strip or
      // inject); the vault still wins over the host env — over an injected proxy too — so
      // a user who genuinely wants PORT, or their own proxy, in commands can set it there.
      //
      // The strip governs inheritance only: it runs inside hostEnvForChild and never
      // re-applies to entries spread in after it, so the vault and controlEnv carry
      // authoritative values into the child — stripped names, PENGUIN_* included, and all.
      // Both guarantees hold because of that order: no PENGUIN_* reaches a command by
      // inheritance, while the control variables the host does sanction arrive as injected
      // values rather than as surviving copies. Pinned by the "an explicit injection
      // layered after the strip wins" test.
      env: {
        ...hostEnv,
        ...this.vault,
        ...(this.controlEnv?.() ?? {}),
        ...HARDENED_ENV,
      },
    });
  }

  /** Registers a still-running session as a background process, allocating and returning a unique `process_id`. */
  register(session: ManagedSession): string {
    this.registry.makeRoom(true);
    const id = this.registry.register(session);
    // A registered process that exits on its own leaves the running set without leaving the
    // registry (its row stays listed as exited until removed), so the exit itself is reported.
    session.setExitListener(() => this.changeListener?.());
    return id;
  }

  /** Looks up a session by process_id and refreshes its access time; returns undefined if it doesn't exist. */
  get(processId: string): ManagedSession | undefined {
    return this.registry.get(processId);
  }

  /** Removes from the registry and cleans up the process group (called after the session exits). */
  remove(processId: string): void {
    this.registry.remove(processId);
  }

  /** Snapshot of the registered background command sessions (id + session), registration order. */
  list(): Array<{ processId: string; session: ManagedSession }> {
    return this.registry.list().map(({ id, task }) => ({ processId: id, session: task }));
  }

  /** Kills a background process by id (SIGTERM→SIGKILL on the whole group) and drops it from the registry; false when the id is unknown. */
  kill(processId: string): boolean {
    if (this.registry.get(processId) === undefined) return false;
    this.registry.remove(processId);
    return true;
  }

  /** Disposes: removes the fallback registration and kills all sessions (the process 'exit' fallback is hooked up by the registry itself). Idempotent. */
  dispose(): void {
    this.registry.dispose();
  }
}