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.

3.1 KB
Raw Blame
/** The portable harness ABI is files + a shell, not an engine's plugin format.
 * Each adapter names the project instruction files its engine actually reads, in precedence order.
 * Skills and executable tools are exposed through the session's context, so native skill/MCP
 * support is an optional optimization rather than a condition for running a harness.
 * Contracts and primary sources: store/spec/portability.md.
 */
import { harnessAdapters } from '../engines/launches.js'
import type { AgentEngine, ProcessEngine } from '../engines/types.js'

export interface HarnessAdapter {
  instructionFiles: readonly string[]
  /** A session-local instruction flag, when the engine provides one. */
  contextArgs?: (contextFile: string) => string[]
  /** The session's variables as flags, for an engine whose commands do not inherit its own environment. */
  envArgs?: (env: Record<string, string>) => string[]
}

export const HARNESS_ADAPTERS = {
  ...harnessAdapters,
  cursor: { instructionFiles: ['AGENTS.md'] },
  opencode: { instructionFiles: ['AGENTS.md', 'CLAUDE.md'] },
  pi: { instructionFiles: ['AGENTS.md', 'CLAUDE.md'], contextArgs: (file: string) => ['--append-system-prompt', file] },
  omp: { instructionFiles: ['AGENTS.md', 'CLAUDE.md'], contextArgs: (file: string) => ['--append-system-prompt', file] },
  hermes: { instructionFiles: ['.hermes.md', 'AGENTS.md', 'CLAUDE.md', '.cursorrules'] },
  commandcode: { instructionFiles: ['AGENTS.md'] },
  devin: { instructionFiles: ['AGENTS.md'] },
  muse: { instructionFiles: ['AGENTS.md', 'CLAUDE.md'] },
  amp: { instructionFiles: ['AGENTS.md'] },
  kilo: { instructionFiles: ['AGENTS.md'] },
  grok: { instructionFiles: ['AGENTS.md'] },
  agy: { instructionFiles: ['AGENTS.md', 'GEMINI.md'] },
  copilot: { instructionFiles: ['AGENTS.md'] },
} satisfies Record<ProcessEngine, HarnessAdapter>

/**
 * Every project file Harness itself may write into: any adapter's instruction files (the session
 * bootstrap, `runtime.ts`) and the files the saved-API notes go in (`lib/apiInstructions.ts`). Asked of
 * the workspace's SCM before those writes (`prepareScmWrite`), for an SCM that holds tracked files
 * read-only. Not every name exists in a given workspace.
 */
export const PROJECT_INSTRUCTION_FILES: readonly string[] = [...new Set([
  ...Object.values(HARNESS_ADAPTERS).flatMap(adapter => adapter.instructionFiles), 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md',
])]

/** A terminal has no instruction loader or agent tools. It remains a Coding-only choice. */
export function harnessAdapter(engine: AgentEngine): HarnessAdapter {
  if (engine === 'terminal') throw new Error('A harness needs an agent engine; Terminal cannot run harness instructions.')
  return HARNESS_ADAPTERS[engine]
}

export const HARNESS_BOOTSTRAP = `<!-- harness:runtime v1 -->
## Harness session context

If HARNESS_CONTEXT_FILE is set in your environment, read that file before working:

\`\`\`sh
if [ -n "$HARNESS_CONTEXT_FILE" ]; then cat "$HARNESS_CONTEXT_FILE"; fi
\`\`\`

It contains the instructions and skill index for this session's selected harness.
If the variable is absent, this is an ordinary coding session with no selected harness.
<!-- /harness:runtime -->
`