openharness

/**
 * What a pane has to be launched WITH, beyond the engine's own argv, for the engine to come back
 * where it was: on the same grid with the same credential, or under the same Codex profile.
 *
 * `agent_create` assembles this from the desktop's fresh `GridLaunchOverride`. Every later relaunch of
 * the same agent — a restart in place, a pane recreated after a reboot — has to assemble the SAME
 * thing from what the registry kept (`gridLaunch`, `codexHome`), or the engine silently comes back on
 * its own login, spending the wrong account while looking identical. Written once so the three
 * callers cannot drift: the half that drifts is the half nobody ran today.
 *
 * Dependency-injected like restoreAgents.ts, because the two machine-specific parts (the tmux version
 * probe and the config directory writer) are exactly the parts worth stubbing in a spec.
 */

import { join } from 'node:path'
import type { AgentEngine } from '../engines/types.js'
import { subscriptionModelLaunch } from './subscriptionModel.js'
import { namedAgentArgs, supportsNamedAgent } from './engineLaunch.js'
import {
  buildGridEngineLaunch,
  gridConflictingEnvToClear,
  type GridEngineLaunch,
  type GridLaunchMachine,
  type GridLaunchOverride,
  type GridLaunchRecord,
} from './gridLaunch.js'
import { TMUX_SESSION_ENV_MIN } from './tmuxVersion.js'
import type { DshLaunch } from '../dsh/launch.js'

export interface LaunchOverrides {
  /** Layered over the pane's inherited environment. The grid key lives here, and only here. */
  env: Record<string, string>
  /** Appended to the engine's argv (`-c model_providers…`, `-m …`, `--mcp-config …`). */
  extraArgs: string[]
  /** Vendor credentials the launch must hide from the engine — see `gridConflictingEnvToClear`. */
  clearEnv: string[]
  /**
   * The grid launch this was built from and what building it decided about web search — present
   * only when this IS a grid launch. Exactly what `registry.setGridLaunch` keeps, so the caller
   * stores it as-is and cannot pair a status with the wrong override. A launch back onto the
   * engine's own login has no such thing to say.
   */
  gridLaunchRecord?: GridLaunchRecord
}

export type LaunchOverridesResult =
  | { ok: true; overrides: LaunchOverrides }
  | { ok: false; error: string; detail: string }

export interface LaunchOverridesDeps {
  /** The facts about THIS machine a contract needs and cannot read for itself — see `GridLaunchMachine`. */
  machine: () => GridLaunchMachine
  writeGridConfigDir: (
    key: string,
    files: NonNullable<GridEngineLaunch['configDir']>['files'],
    links: NonNullable<GridEngineLaunch['configDir']>['links'],
  ) => Promise<string>
  tmuxSupportsSessionEnv: () => Promise<boolean>
  /** Install the daemon's hooks into a non-default Codex profile. The caller decides whether hook
   *  installation is enabled at all. */
  installCodexHooks: (codexHome: string) => void
  /** What a DSH adds to the launch (its env and argv), or null when it is not installed here any
   *  more — in which case the agent relaunches as its plain base engine and says so in the log. */
  dshLaunch?: (dsh: string, workspace: string) => DshLaunch | null
}

/** Where the agent should come back: the registry row, or an override the desktop just sent. */
export interface LaunchSource {
  gridLaunch?: GridLaunchOverride | null
  codexHome?: string | null
  /**
   * The engine's OWN model to come back to, when this relaunch is a move off a grid.
   *
   * Ignored while `gridLaunch` is set — that launch names its own model. Absent means "let the
   * engine decide", which is what happens for an engine with no cited mechanism.
   */
  subscriptionModel?: string | null
  /** The DSH the agent was created as; its env rides on every relaunch (`HARNESS_DSH` included). */
  dsh?: string | null
  /** The workspace, for the DSH's `${workspace}` — the registry row's `cwd`. */
  cwd?: string | null
  /**
   * The engine's named agent this pane was opened as (`agent_create`'s `agent`, opencode
   * `--agent <name>`). Part of every relaunch, unlike a first prompt: a pane opened as `harness-compute`
   * comes back as `harness-compute`, not as a general session with that agent's history.
   */
  agent?: string | null
}

/** Fresh each time: callers hand `env` to tmux and may extend it, and a shared object would carry
 *  one relaunch's additions into the next. */
const noOverrides = (): LaunchOverrides => ({ env: {}, extraArgs: [], clearEnv: [] })

/**
 * Build the overrides for relaunching `engine` from `source`. `configKey` names the config directory
 * a file-configured engine gets (`writeGridConfigDir`); key it on the agent so relaunching the same
 * agent rewrites one directory rather than leaving a trail of them.
 *
 * A grid the launch cannot honour is a refusal, never a fallback — the rule `agent_create` sets.
 */
/**
 * The refusals that need nothing written: the engine has no way onto a grid, or this tmux cannot
 * give a pane its own environment. Split out so a caller with a live process to protect can refuse
 * BEFORE it decides to touch anything (retarget checks these ahead of its busy guards, and only
 * builds — config directory included — once it holds the pane).
 */
export async function validateLaunchOverrides(
  deps: Pick<LaunchOverridesDeps, 'tmuxSupportsSessionEnv' | 'machine'>,
  engine: AgentEngine,
  source: LaunchSource,
): Promise<{ ok: true } | { ok: false; error: string; detail: string }> {
  if (!source.gridLaunch) return { ok: true }
  const built = buildGridEngineLaunch(engine, source.gridLaunch, deps.machine())
  if (!built.ok) return { ok: false, error: built.error, detail: built.detail }
  // Only a launch that SETS variables needs the tmux that can set them.
  if (!(await deps.tmuxSupportsSessionEnv())) {
    return {
      ok: false,
      error: 'TMUX_TOO_OLD_FOR_GRID',
      detail: `this machine's tmux is older than ${TMUX_SESSION_ENV_MIN.major}.${TMUX_SESSION_ENV_MIN.minor}, `
        + `which is the first version that can give a pane its own environment — so ${engine} could not be `
        + `pointed at grid ${source.gridLaunch.networkName}.`,
    }
  }
  return { ok: true }
}

export async function buildLaunchOverrides(
  deps: LaunchOverridesDeps,
  engine: AgentEngine,
  source: LaunchSource,
  configKey: string,
): Promise<LaunchOverridesResult> {
  const base = await buildBaseLaunchOverrides(deps, engine, source, configKey)
  if (!base.ok) return base
  let overrides = base.overrides
  if (source.dsh && source.cwd) {
    const dsh = deps.dshLaunch?.(source.dsh, source.cwd) ?? null
    // The DSH's variables layer over the grid's or the profile's; `HARNESS_*` are the daemon's own
    // and a manifest cannot set them (see `dshLaunch`), so nothing here can shadow a grid credential.
    if (dsh) {
      overrides = {
        ...overrides,
        env: { ...overrides.env, ...dsh.env },
        extraArgs: [...overrides.extraArgs, ...dsh.args],
      }
    }
  }
  // The named agent rides every relaunch, in the same argv slot `agent_create` put it in. Only an
  // engine with a contract could have had it recorded (create refuses the rest, AGENT_UNSUPPORTED),
  // so the guard is for a row edited by hand — it relaunches as a general session rather than
  // handing the engine a flag it does not know.
  if (source.agent && supportsNamedAgent(engine)) {
    overrides = { ...overrides, extraArgs: [...overrides.extraArgs, ...namedAgentArgs(engine, source.agent)] }
  }
  return { ok: true, overrides }
}

async function buildBaseLaunchOverrides(
  deps: LaunchOverridesDeps,
  engine: AgentEngine,
  source: LaunchSource,
  configKey: string,
): Promise<LaunchOverridesResult> {
  const valid = await validateLaunchOverrides(deps, engine, source)
  if (!valid.ok) return valid
  if (!source.gridLaunch) {
    // Coming back to the engine's own login: re-select the model this agent was on before it left,
    // so the engine does not fall back to a house default. See `subscriptionModel.ts` for why an
    // engine with no cited mechanism is given nothing rather than a guess.
    const restored = subscriptionModelLaunch(engine, source.subscriptionModel)
    if (restored) {
      const base = noOverrides()
      return {
        ok: true,
        overrides: {
          ...base,
          env: { ...base.env, ...restored.env },
          extraArgs: [...base.extraArgs, ...restored.args],
        },
      }
    }
  }
  if (source.gridLaunch) {
    const built = buildGridEngineLaunch(engine, source.gridLaunch, deps.machine())
    if (!built.ok) return { ok: false, error: built.error, detail: built.detail }
    const env: Record<string, string> = { ...built.launch.env }
    if (built.launch.configDir) {
      const { envVar, files, pointAt, links } = built.launch.configDir
      try {
        const dir = await deps.writeGridConfigDir(configKey, files, links ?? [])
        // Pi is handed the directory; OpenCode's OPENCODE_CONFIG wants the file inside it.
        env[envVar] = pointAt ? join(dir, pointAt) : dir
      } catch (error) {
        const detail = `could not write ${engine}'s grid configuration · ${error instanceof Error ? error.message : error}`
        return { ok: false, error: 'GRID_CONFIG_FAILED', detail }
      }
    }
    // Derived from what this launch actually provides (the config-dir variable included), so an
    // inherited vendor key never outranks the grid the engine was handed.
    return {
      ok: true,
      overrides: {
        env,
        extraArgs: [...built.launch.args],
        clearEnv: gridConflictingEnvToClear({ env }),
        gridLaunchRecord: { override: source.gridLaunch, webSearch: built.launch.webSearch },
      },
    }
  }
  if (source.codexHome) {
    // A Codex agent on a profile OTHER than this machine's default reads hooks.json from THAT folder,
    // not the one `harness login` installed into — without this it fires no hook at all. Idempotent.
    deps.installCodexHooks(source.codexHome)
    return { ok: true, overrides: { env: { CODEX_HOME: source.codexHome }, extraArgs: [], clearEnv: [] } }
  }
  return { ok: true, overrides: noOverrides() }
}