Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

21.4 KB
Raw Blame
import path from "node:path";
import type { AgentLaunchIntent, CustomAgent } from "../shared/types";
import {
  AGENT_CONFIG,
  agentLaunchProgram,
  canResume,
  hasPermissionMode,
  isPermissionMode,
  mintsSessionId,
  type AgentConfig,
  type AgentId,
  type BuiltinAgentId,
  type PromptInjectionMode,
} from "../shared/agents/config";
import { approvalFlags } from "../shared/agents/approval-mode";
import { CODEX_NO_DAEMON_FLAG } from "../shared/agents/codex-daemon";
import { SAFE_SESSION_ID } from "../shared/session-id";
import { isRecord } from "../shared/is-record";

/** The parser that owns a live local Windows-profile terminal. */
export type AgentLaunchDialect =
  "posix" | "pwsh" | "windows-powershell" | "cmd";

/**
 * How PowerShell must invoke the resolved agent entry point. A `.cmd`/`.bat` shim is deliberately
 * distinct: forwarding arbitrary Unicode/metacharacter-bearing argv through another cmd parser is
 * not lossless, so the planner refuses it instead of pretending native quoting applies.
 */
export type AgentLaunchExecutableKind =
  "native" | "powershell-script" | "cmd-script";

export interface AgentLaunchExecutableResolution {
  kind: AgentLaunchExecutableKind;
  /** Trusted currently-existing absolute path returned by the core resolver. */
  executable: string;
}

export type AgentLaunchExecutableKindResolver = (
  executable: string,
  dialect: Exclude<AgentLaunchDialect, "posix">,
) => Promise<AgentLaunchExecutableResolution | null>;

/** The one current custom-agent record selected from machine-local settings. */
export type TrustedCustomAgentLaunchConfig = Pick<
  CustomAgent,
  "id" | "launchCmd" | "promptInjectionMode"
>;

/**
 * Host-authoritative facts. None may be populated from a project file, canvas mutation, or relay
 * peer. In particular, the intent carries no executable and cannot select a different node owner.
 */
export interface AgentLaunchTrustedContext {
  expectedAgentId: AgentId;
  customAgent?: TrustedCustomAgentLaunchConfig;
  sharedIdentityAvailable: boolean;
  resolveExecutableKind?: AgentLaunchExecutableKindResolver;
  /** Trusted absolute Windows PowerShell executable used only as cmd's ASCII-safe wrapper. */
  windowsPowerShellPath?: string;
  /**
   * What the host's `codex` accepts for `--ask-for-approval`, from `core/codex-cli.ts`'s probe of
   * the binary this plan will exec. Host-authoritative like everything else here, and injected
   * rather than read inline so this planner stays pure and testable.
   *
   * Absent = unknown = the baseline vocabulary, which is the safe degrade everywhere: the launch
   * still happens, at worst `manual` falls back to codex's own default. The value that makes this
   * field necessary is `untrusted`, which codex removed in 0.149.0 — clap EXITS on a value it does
   * not know, so emitting it blind is a dead session, not a degraded one.
   */
  codexApprovalValues?: readonly string[] | null;
  /**
   * Does the host's `codex` accept `--no-daemon`? Same probe, same provenance. Only a literal
   * `true` adds the flag — see `withCodexNoDaemon` (shared/agents/codex-daemon.ts) for why every
   * plain Codex TUI nodeterm starts needs it from codex-cli 0.157.0 on.
   */
  codexNoDaemon?: boolean | null;
}

/** Core-private launch material. It must never cross the renderer/preload/relay boundary. */
export interface PreparedAgentLaunch {
  command: string;
  /** Literal follow-up data for an agent whose configured prompt mode is stdin-after-start. */
  stdinAfterStart?: string;
}

export type AgentLaunchPreparationErrorCode =
  "invalid-intent" | "agent-unavailable" | "unsupported-shell";

const SAFE_ERROR_MESSAGES: Record<AgentLaunchPreparationErrorCode, string> = {
  "invalid-intent": "The agent launch request is invalid.",
  "agent-unavailable": "The configured agent is unavailable on this machine.",
  "unsupported-shell":
    "This terminal shell cannot safely launch the configured agent.",
};

/** An error whose code and copy are safe to surface; it never embeds launch material. */
export class AgentLaunchPreparationError extends Error {
  readonly code: AgentLaunchPreparationErrorCode;

  constructor(code: AgentLaunchPreparationErrorCode) {
    super(SAFE_ERROR_MESSAGES[code]);
    this.name = "AgentLaunchPreparationError";
    this.code = code;
  }
}

interface LogicalAgentLaunch {
  executable: string;
  args: string[];
  stdinAfterStart?: string;
}

interface ResolvedAgentConfig {
  id: AgentId;
  launchCmd: string;
  promptInjectionMode: PromptInjectionMode;
  argvPromptSeparator?: string;
  /** `flag-interactive` only: the builtin's own interactive-prompt flag (agy's differs). */
  promptFlag?: string;
  builtin: boolean;
}

const SAFE_NEW_SESSION_UUID_V4 =
  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
// PowerShell and POSIX parsers also treat Unicode line/paragraph separators as command boundaries
// in contexts where JavaScript's Cc category does not catch them.
const FORBIDDEN_INLINE_CHARACTER = /[\p{Cc}\u2028\u2029]/u;
const MAX_PROMPT_LENGTH = 128 * 1024;
const MAX_LAUNCH_COMMAND_LENGTH = 32 * 1024;
// `posix` is shared by WSL and Git Bash. The latter ultimately launches a Windows process, so use
// the smaller portable byte budget instead of Linux's larger MAX_ARG_STRLEN and fail closed when
// the environment-specific transport cannot be distinguished here.
const MAX_PORTABLE_POSIX_ARGUMENT_BYTES = 30_000;
const MAX_PORTABLE_POSIX_COMMAND_BYTES = 32_000;
// CreateProcessW caps one native command line at 32,767 UTF-16 code units; cmd.exe caps one
// interactive line at 8,191. Leave a small fixed margin for implementation-added framing/NUL.
const MAX_WINDOWS_COMMAND_LINE = 32_700;
const MAX_CMD_INTERACTIVE_LINE = 8_100;
const START_FIELDS = new Set([
  "kind",
  "action",
  "agentId",
  "prompt",
  "permissionMode",
  "newSessionId",
]);
const RESUME_FIELDS = new Set([
  "kind",
  "action",
  "agentId",
  "sessionId",
  "permissionMode",
]);

function fail(code: AgentLaunchPreparationErrorCode): never {
  throw new AgentLaunchPreparationError(code);
}

function hasOnlyOwnFields(
  value: Record<string, unknown>,
  allowed: ReadonlySet<string>,
): boolean {
  return Object.keys(value).every((key) => allowed.has(key));
}

function safeText(value: unknown, maxLength: number): value is string {
  return (
    typeof value === "string" &&
    value.length <= maxLength &&
    !FORBIDDEN_INLINE_CHARACTER.test(value)
  );
}

function validateIntentRuntime(
  intent: AgentLaunchIntent,
  expectedAgentId: AgentId,
): void {
  if (!isRecord(intent)) fail("invalid-intent");
  if (intent.kind !== "agent") fail("invalid-intent");
  if (
    typeof intent.agentId !== "string" ||
    !intent.agentId ||
    intent.agentId !== expectedAgentId
  )
    fail("agent-unavailable");
  if (FORBIDDEN_INLINE_CHARACTER.test(intent.agentId))
    fail("agent-unavailable");
  if (
    intent.permissionMode !== undefined &&
    !isPermissionMode(intent.permissionMode)
  )
    fail("invalid-intent");

  if (intent.action === "start") {
    if (!hasOnlyOwnFields(intent, START_FIELDS)) fail("invalid-intent");
    if (
      intent.prompt !== undefined &&
      !safeText(intent.prompt, MAX_PROMPT_LENGTH)
    )
      fail("invalid-intent");
    if (
      intent.newSessionId !== undefined &&
      (typeof intent.newSessionId !== "string" ||
        !SAFE_NEW_SESSION_UUID_V4.test(intent.newSessionId))
    )
      fail("invalid-intent");
    return;
  }

  if (intent.action === "resume") {
    if (!hasOnlyOwnFields(intent, RESUME_FIELDS)) fail("invalid-intent");
    if (
      typeof intent.sessionId !== "string" ||
      !SAFE_SESSION_ID.test(intent.sessionId)
    )
      fail("invalid-intent");
    return;
  }

  fail("invalid-intent");
}

function isBuiltinAgentId(id: AgentId): id is BuiltinAgentId {
  return Object.hasOwn(AGENT_CONFIG, id);
}

function validPromptMode(value: unknown): value is PromptInjectionMode {
  return (
    value === "argv" || value === "flag-prompt" || value === "stdin-after-start"
  );
}

function resolveTrustedAgentConfig(
  intent: AgentLaunchIntent,
  context: AgentLaunchTrustedContext,
): ResolvedAgentConfig {
  if (isBuiltinAgentId(intent.agentId)) {
    const config: AgentConfig = AGENT_CONFIG[intent.agentId];
    return {
      id: intent.agentId,
      launchCmd: config.launchCmd,
      promptInjectionMode: config.promptInjectionMode,
      argvPromptSeparator: config.argvPromptSeparator,
      promptFlag: config.promptFlag,
      builtin: true,
    };
  }

  const custom = context.customAgent;
  if (
    !custom ||
    typeof custom.id !== "string" ||
    custom.id !== intent.agentId ||
    custom.id !== context.expectedAgentId ||
    !safeText(custom.launchCmd, MAX_LAUNCH_COMMAND_LENGTH) ||
    !custom.launchCmd.trim() ||
    !validPromptMode(custom.promptInjectionMode)
  )
    fail("agent-unavailable");

  return {
    id: intent.agentId,
    launchCmd: custom.launchCmd,
    promptInjectionMode: custom.promptInjectionMode,
    builtin: false,
  };
}

/**
 * A deliberately small shell-neutral argv grammar for the machine-local custom launch field.
 * Quotes group literal text; backslash escapes whitespace/quotes/backslash. Unquoted shell
 * operators are refused because silently turning a shell fragment into argv changes its meaning.
 */
function parseTrustedLaunchCommand(source: string): string[] {
  const tokens: string[] = [];
  let token = "";
  let tokenStarted = false;
  let quote: "'" | '"' | null = null;

  const push = (): void => {
    if (!tokenStarted) return;
    tokens.push(token);
    token = "";
    tokenStarted = false;
  };

  for (let i = 0; i < source.length; i++) {
    const ch = source[i];
    if (quote) {
      if (ch === quote) {
        quote = null;
        tokenStarted = true;
        continue;
      }
      if (ch === "\\") {
        const next = source[i + 1];
        if (next === quote || next === "\\") {
          token += next;
          tokenStarted = true;
          i++;
          continue;
        }
      }
      token += ch;
      tokenStarted = true;
      continue;
    }

    if (/\s/u.test(ch)) {
      push();
      continue;
    }
    if (ch === "'" || ch === '"') {
      quote = ch;
      tokenStarted = true;
      continue;
    }
    if (ch === "\\") {
      const next = source[i + 1];
      if (
        next &&
        (/\s/u.test(next) || next === "'" || next === '"' || next === "\\")
      ) {
        token += next;
        tokenStarted = true;
        i++;
        continue;
      }
      token += ch;
      tokenStarted = true;
      continue;
    }
    if (";&|<>()$`\r\n".includes(ch)) fail("agent-unavailable");
    token += ch;
    tokenStarted = true;
  }

  if (quote) fail("agent-unavailable");
  push();
  if (!tokens.length || !tokens[0] || tokens[0].startsWith("-"))
    fail("agent-unavailable");
  return tokens;
}

function logicalLaunch(
  intent: AgentLaunchIntent,
  config: ResolvedAgentConfig,
  context: AgentLaunchTrustedContext,
): LogicalAgentLaunch {
  const parsed = parseTrustedLaunchCommand(config.launchCmd);
  let executable = parsed[0];
  const baseArgs = parsed.slice(1);
  if (config.builtin)
    executable = agentLaunchProgram(
      config.id,
      executable,
      context.sharedIdentityAvailable,
    );

  if (intent.permissionMode !== undefined && !hasPermissionMode(config.id))
    fail("invalid-intent");
  const approval = intent.permissionMode
    ? approvalFlags(config.id, intent.permissionMode, {
        codexApprovalValues: context.codexApprovalValues,
      })
    : [];
  // Same rule as `withCodexNoDaemon`, applied to argv instead of a typed line.
  const noDaemon =
    config.id === "codex" &&
    context.codexNoDaemon === true &&
    !baseArgs.some(
      (a) =>
        a === CODEX_NO_DAEMON_FLAG || a === "--remote" || a.startsWith("--remote="),
    )
      ? [CODEX_NO_DAEMON_FLAG]
      : [];
  const modeFlags = [...approval, ...noDaemon];

  if (intent.action === "resume") {
    if (!config.builtin || !canResume(config.id)) fail("agent-unavailable");
    // Same grammar as `resumeCommandWith` (shared/agents/config.ts): copilot and antigravity are
    // verified only in their `--flag=<id>` spelling, so they keep it here too.
    const resumeArgs =
      config.id === "codex"
        ? ["resume", intent.sessionId]
        : config.id === "opencode"
          ? ["--session", intent.sessionId]
          : config.id === "copilot"
            ? [`--resume=${intent.sessionId}`]
            : config.id === "antigravity"
              ? [`--conversation=${intent.sessionId}`]
              : ["--resume", intent.sessionId];
    return { executable, args: [...baseArgs, ...resumeArgs, ...modeFlags] };
  }

  const sessionArgs: string[] = [];
  if (intent.newSessionId !== undefined) {
    if (!mintsSessionId(config.id)) fail("invalid-intent");
    // `withSessionId`'s grammar: copilot's verified contract is `--session-id=<uuid>` (1.0.80);
    // cursor mints by resuming an id that does not exist yet (see withSessionId in shared/agents/launch).
    if (config.id === "copilot")
      sessionArgs.push(`--session-id=${intent.newSessionId}`);
    else if (config.id === "cursor")
      sessionArgs.push("--resume", intent.newSessionId);
    else sessionArgs.push("--session-id", intent.newSessionId);
  }

  const hasPrompt = Object.hasOwn(intent, "prompt");
  const prompt = hasPrompt ? (intent.prompt ?? "") : undefined;
  // Gemini's existing creation contract is a positional prompt even though its capability
  // metadata describes a possible stdin transport. Changing that would require a measured child
  // readiness handshake; the generic terminal prompt is not evidence that Gemini is ready.
  const promptInjectionMode =
    config.builtin && config.id === "gemini"
      ? "argv"
      : config.promptInjectionMode;
  if (promptInjectionMode === "stdin-after-start") {
    return {
      executable,
      args: [...baseArgs, ...modeFlags, ...sessionArgs],
      ...(hasPrompt ? { stdinAfterStart: prompt } : {}),
    };
  }

  if (
    promptInjectionMode === "flag-prompt" ||
    promptInjectionMode === "flag-interactive"
  ) {
    // Same flag choice as `assembleLaunchCommand`: copilot's `--interactive`, agy's own
    // `--prompt-interactive`. A positional here would be read as a subcommand by both.
    const flag =
      promptInjectionMode === "flag-prompt"
        ? "--prompt"
        : (config.promptFlag ?? "--interactive");
    return {
      executable,
      args: [
        ...baseArgs,
        ...(hasPrompt ? [flag, prompt as string] : []),
        ...modeFlags,
        ...sessionArgs,
      ],
    };
  }

  if (hasPrompt && config.argvPromptSeparator) {
    return {
      executable,
      args: [
        ...baseArgs,
        ...modeFlags,
        ...sessionArgs,
        config.argvPromptSeparator,
        prompt as string,
      ],
    };
  }

  return {
    executable,
    args: [
      ...baseArgs,
      ...(hasPrompt ? [prompt as string] : []),
      ...modeFlags,
      ...sessionArgs,
    ],
  };
}

function posixQuote(value: string): string {
  return `'${value.replace(/'/g, `'\\''`)}'`;
}

function powershellQuote(value: string): string {
  return `'${value.replace(/'/g, "''")}'`;
}

function explicitExecutableKind(
  executable: string,
): AgentLaunchExecutableKind | null {
  const lower = executable.toLowerCase();
  if (lower.endsWith(".exe") || lower.endsWith(".com")) return "native";
  if (lower.endsWith(".ps1")) return "powershell-script";
  if (lower.endsWith(".cmd") || lower.endsWith(".bat")) return "cmd-script";
  return null;
}

function validateResolvedExecutable(value: unknown): value is string {
  return (
    typeof value === "string" &&
    !!value &&
    !FORBIDDEN_INLINE_CHARACTER.test(value)
  );
}

async function resolveWindowsExecutable(
  executable: string,
  dialect: Exclude<AgentLaunchDialect, "posix">,
  resolver: AgentLaunchExecutableKindResolver | undefined,
): Promise<{ executable: string; kind: AgentLaunchExecutableKind }> {
  if (!resolver) fail("unsupported-shell");

  let resolution: AgentLaunchExecutableResolution | null;
  try {
    resolution = await resolver(executable, dialect);
  } catch {
    fail("agent-unavailable");
  }
  if (!resolution) fail("agent-unavailable");
  if (
    resolution.kind !== "native" &&
    resolution.kind !== "powershell-script" &&
    resolution.kind !== "cmd-script"
  )
    fail("agent-unavailable");
  const resolved = resolution.executable;
  if (
    !validateResolvedExecutable(resolved) ||
    !path.win32.isAbsolute(resolved) ||
    !/^[A-Za-z]:[\\/]/.test(resolved)
  )
    fail("agent-unavailable");
  // The resolver also proves current existence. Its kind must agree with the actual resolved
  // suffix so a forged/stale "native" answer cannot route a .cmd shim through native quoting.
  if (explicitExecutableKind(resolved) !== resolution.kind)
    fail("agent-unavailable");
  return { executable: resolved, kind: resolution.kind };
}

/** Microsoft CRT/CommandLineToArgvW quoting for one native-process argument. */
function windowsNativeArg(value: string): string {
  if (value && !/[\s"]/u.test(value)) return value;
  let quoted = '"';
  let backslashes = 0;
  for (const ch of value) {
    if (ch === "\\") {
      backslashes++;
      continue;
    }
    if (ch === '"') {
      quoted += "\\".repeat(backslashes * 2 + 1) + '"';
      backslashes = 0;
      continue;
    }
    quoted += "\\".repeat(backslashes) + ch;
    backslashes = 0;
  }
  return `${quoted}${"\\".repeat(backslashes * 2)}"`;
}

function powershellInvocation(
  executable: string,
  kind: AgentLaunchExecutableKind,
  args: string[],
): string {
  // A batch shim introduces a second cmd parse. `%`, `!`, quotes and Unicode cannot all be carried
  // losslessly through it as arbitrary argv, so require the trusted resolver to choose a native or
  // PowerShell-script entry point (npm installations normally provide the sibling `.ps1` shim).
  if (kind === "cmd-script") fail("unsupported-shell");
  if (kind === "powershell-script")
    return [
      "&",
      powershellQuote(executable),
      ...args.map(powershellQuote),
    ].join(" ");

  // Windows PowerShell 5.1's native-command marshaller loses embedded quotes before a program's
  // CRT parser sees them. Give Start-Process one already-quoted command-line string instead; it
  // inherits the ConPTY handles with -NoNewWindow and waits so the interactive shell remains the
  // agent's parent for the whole TUI lifetime.
  const argumentLine = args.map(windowsNativeArg).join(" ");
  if (executable.length + argumentLine.length + 2 > MAX_WINDOWS_COMMAND_LINE)
    fail("invalid-intent");
  return [
    `$ntAgent = Start-Process -FilePath ${powershellQuote(executable)}`,
    ...(args.length ? [`-ArgumentList ${powershellQuote(argumentLine)}`] : []),
    "-NoNewWindow -Wait -PassThru",
    "; $global:LASTEXITCODE = $ntAgent.ExitCode",
  ].join(" ");
}

function trustedWindowsPowerShellPath(value: string | undefined): string {
  if (
    !value ||
    !path.win32.isAbsolute(value) ||
    !/^[A-Za-z]:[\\/]/.test(value) ||
    FORBIDDEN_INLINE_CHARACTER.test(value) ||
    /["&|<>^%!]/.test(value) ||
    !value.toLowerCase().endsWith(".exe")
  )
    fail("unsupported-shell");
  return value;
}

function encodedPowerShellCommand(script: string): string {
  return Buffer.from(script, "utf16le").toString("base64");
}

/**
 * Validate a semantic request, resolve only trusted host configuration, and encode it for the
 * concrete live profile dialect. The returned command is core-private launch material.
 */
export async function prepareAgentLaunch(
  intent: AgentLaunchIntent,
  dialect: AgentLaunchDialect,
  context: AgentLaunchTrustedContext,
): Promise<PreparedAgentLaunch> {
  validateIntentRuntime(intent, context.expectedAgentId);
  const config = resolveTrustedAgentConfig(intent, context);
  // A custom process has no trusted readiness signal. Writing its prompt after a timer or generic
  // shell-output probe can race the child, leak text into the parent shell, or lose it on exit.
  if (!config.builtin && config.promptInjectionMode === "stdin-after-start")
    fail("unsupported-shell");
  const logical = logicalLaunch(intent, config, context);

  if (dialect === "posix") {
    const tokens = [logical.executable, ...logical.args];
    if (
      tokens.some(
        (token) =>
          Buffer.byteLength(token, "utf8") > MAX_PORTABLE_POSIX_ARGUMENT_BYTES,
      )
    )
      fail("invalid-intent");
    const command = tokens.map(posixQuote).join(" ");
    if (Buffer.byteLength(command, "utf8") > MAX_PORTABLE_POSIX_COMMAND_BYTES)
      fail("invalid-intent");
    return {
      command,
      ...(logical.stdinAfterStart !== undefined
        ? { stdinAfterStart: logical.stdinAfterStart }
        : {}),
    };
  }

  if (
    dialect !== "pwsh" &&
    dialect !== "windows-powershell" &&
    dialect !== "cmd"
  )
    fail("unsupported-shell");
  const resolved = await resolveWindowsExecutable(
    logical.executable,
    dialect,
    context.resolveExecutableKind,
  );
  const script = powershellInvocation(
    resolved.executable,
    resolved.kind,
    logical.args,
  );
  if (script.length > MAX_WINDOWS_COMMAND_LINE) fail("invalid-intent");

  if (dialect === "cmd") {
    const wrapper = trustedWindowsPowerShellPath(context.windowsPowerShellPath);
    const command = `"${wrapper}" -NoLogo -NoProfile -EncodedCommand ${encodedPowerShellCommand(script)}`;
    if (command.length > MAX_CMD_INTERACTIVE_LINE) fail("invalid-intent");
    return {
      command,
      ...(logical.stdinAfterStart !== undefined
        ? { stdinAfterStart: logical.stdinAfterStart }
        : {}),
    };
  }

  return {
    command: script,
    ...(logical.stdinAfterStart !== undefined
      ? { stdinAfterStart: logical.stdinAfterStart }
      : {}),
  };
}