Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

8.0 KB
Raw Blame
import type { AttributionContract, EngineLaunch, StatusLineContract } from './facets/launch.js'
import type { AgentEngine } from './types.js'
import { launch as claude } from './claude/launch.js'
import { launch as codex } from './codex/launch.js'
import { attributionArgsIn, attributionInstruction, instructionsArgsIn, type Instruction } from './kit/attribution.js'
import { contextArgsOf, envArgsOf, fill, ownProviderArgs, readConfig } from './kit/launchArgs.js'
import { joinedSettings, statusLineSetting } from './kit/statusLine.js'
import { claudeCodeGitBash } from '../lib/windows/claudeCodeGitBash.js'
import { env } from '../config/env.js'
import { launchHome, launchHomeOf, launchPersonalHome } from '../lib/engineHomes.js'

/**
 * Launch metadata has no transcript imports: preparing argv must not load transcript readers. The contracts
 * are data; what reads them is the kit's (kit/launchArgs.ts, kit/launchStartup.ts), run in core, since a
 * launch is session control (docs/design/2026-10-08-engine-launch.md).
 */
export const engineLaunches = { claude, codex } satisfies Record<string, EngineLaunch>
type MigratedEngine = keyof typeof engineLaunches

/** An engine's launch contract, for an engine that declares one. Any name: a session row's engine is a string. */
export function launchContract(engine: AgentEngine | string): EngineLaunch | undefined {
  return Object.hasOwn(engineLaunches, engine) ? engineLaunches[engine as MigratedEngine] : undefined
}

/** The instruction file Harness writes its own notes into for `engine`, where it declares one. */
export function instructionFileOf(engine: AgentEngine | string): string | undefined {
  return launchContract(engine)?.instructionFile
}

/** Compatibility tables take their migrated entries from the same launch contract. */
export function launchField<K extends keyof EngineLaunch>(key: K): Record<MigratedEngine, EngineLaunch[K]> {
  return Object.fromEntries(Object.entries(engineLaunches).map(([name, launch]) => [name, launch[key]])) as Record<MigratedEngine, EngineLaunch[K]>
}

/** What a harness (dsh/adapters.ts) hands each engine: its instruction files, and its declared flags as argv. */
export const harnessAdapters = Object.fromEntries(Object.entries(engineLaunches).map(([name, launch]: [string, EngineLaunch]) => [name, {
  instructionFiles: launch.instructionFiles,
  ...(launch.contextArgs ? { contextArgs: contextArgsOf(launch.contextArgs) } : {}),
  ...(launch.envArgs ? { envArgs: envArgsOf(launch.envArgs) } : {}),
}])) as Record<MigratedEngine, {
  instructionFiles: readonly string[]
  contextArgs?: (contextFile: string) => string[]
  envArgs?: (env: Record<string, string>) => string[]
}>

/**
 * The argv that puts `engine` back on its own provider as it leaves a grid, or nothing for an engine that
 * keeps none of its own (`EngineLaunch.ownProvider`). Read from the home this launch's engine reads: the
 * agent's own profile, else the one the person's shell moves, else the daemon's (lib/engineHomes.ts).
 */
export function ownLoginProviderArgs(
  engine: AgentEngine,
  profile: string | null | undefined,
  deps: { read?: (path: string) => string | null; env?: NodeJS.ProcessEnv } = {},
): string[] {
  const own = launchContract(engine)?.ownProvider
  return own ? ownProviderArgs(own, launchHome(own.home, profile, deps.env), deps.read) : []
}

/** Where a launch reads the person's settings from, for `attributionArgs`. */
export interface AttributionPlace {
  /** The harness's folder, or null where it has none. */
  cwd: string | null
  /** The agent's own engine home (a Codex agent's profile), where the engine's home takes one. */
  profile?: string | null
  /** The launch's environment as its shell set it (a native launch's); the daemon's launch environment when absent. */
  environment?: NodeJS.ProcessEnv
  /** A seam, like `readCodexConfig`: a spec's launch reads no settings of the machine it runs on. The real file when absent. */
  read?: (path: string) => string | null
  /** A Swarm session's instructions (lib/agentAttribution.ts): its folder is a branch, whose own settings are not run. */
  swarmInstructions?: string
}

/**
 * The argv that has `engine` add `line` to the pull requests it opens (`EngineLaunch.attribution`), from the person's
 * settings as this launch would read them: nothing for an engine that declares no way to, or where they hid the
 * engine's own attribution (kit/attribution.ts). Read at each launch, as the person may change them in between.
 */
export function attributionArgs(engine: AgentEngine | string, line: string, place: AttributionPlace): string[] {
  const contract = launchContract(engine)?.attribution
  return contract ? attributionArgsIn(contract, line, attributionFiles(contract, place)) : []
}

const attributionFiles = (contract: AttributionContract, place: AttributionPlace) => ({
  home: launchHomeOf(contract.home, place.profile, place.environment), personal: launchPersonalHome(place.environment),
  cwd: place.cwd, read: place.read ?? readConfig,
})

/**
 * The argv that tells `engine` Harness's own instructions ([instructions], `EngineLaunch.harnessInstructions`) and, with
 * [prLine], has it add that line to its pull requests (`attributionArgs`): for an engine that keeps both in one config
 * value (Codex), in one argument, as two of the same `-c` would leave only the last. Nothing for what the engine declares
 * no way to take, or where the person's settings say not to.
 */
export function agentInstructionArgs(engine: AgentEngine | string, said: { instructions: string | null; prLine: string | null }, place: AttributionPlace): string[] {
  const launch = launchContract(engine)
  const attribution = launch?.attribution
  const told = launch?.harnessInstructions
  const status = statusLineArgs(launch?.statusLine, place)
  if (!attribution && !told) return status
  said = { ...said, instructions: said.instructions && told?.also ? `${said.instructions} ${told.also}` : said.instructions }
  if (attribution?.kind === 'instruction') {
    const instructions: Instruction[] = [
      ...(said.instructions && told?.kind === 'attribution' ? [{ text: said.instructions, mark: said.instructions }] : []),
      ...(said.prLine ? [attributionInstruction(attribution, said.prLine)] : []),
    ]
    return [...instructionsArgsIn(attribution, instructions, attributionFiles(attribution, place)), ...status]
  }
  const setting = said.prLine && attribution ? attributionArgsIn(attribution, said.prLine, attributionFiles(attribution, place)) : []
  // Only beside the setting it backs: where the person's settings hide the engine's attribution, neither is given.
  const reminder = setting.length && attribution?.instruction ? attributionInstruction({ instruction: attribution.instruction }, said.prLine!).text : null
  const texts = told?.kind === 'append' ? [said.instructions, reminder].filter((text): text is string => !!text) : []
  const args = [...setting, ...status, ...(texts.length && told?.kind === 'append' ? told.args.map((arg) => fill(arg, 'text', texts.join('\n\n'))) : [])]
  return launch?.statusLine ? joinedSettings(launch.statusLine.args[0]!, args) : args
}

/**
 * The argv that gives a launch Harness's status line (kit/statusLine.ts): every session of an engine that declares one,
 * the person's own or an agent's. A Swarm session's folder is a branch, which could commit a status line command, and
 * one Harness ran would run outside the setting sources its launch keeps to (claude/launch.ts `teamWritten`): only the
 * person's own settings are read for it.
 */
function statusLineArgs(contract: StatusLineContract | undefined, place: AttributionPlace): string[] {
  if (!contract) return []
  const files = { home: launchHomeOf(contract.home, place.profile, place.environment), personal: launchPersonalHome(place.environment),
    cwd: place.cwd, read: place.read ?? readConfig, folder: !place.swarmInstructions }
  const setting = statusLineSetting(contract, files, env.ADAPTER_DATA_DIR, process.platform,
    () => claudeCodeGitBash({ env: place.environment ?? process.env }))
  return setting ? contract.args.map((arg) => fill(arg, 'settings', JSON.stringify(setting))) : []
}