The internal/agent package provides a shared foundation for all Agent Engines. It abstracts the complexities of runtime environment preparation, Node.js bootstrapping, MCP (Model Context Protocol) server management, prompt delivery, and session result parsing.
The CLIAgent is the primary base struct used by built-in engines like Claude Code and Codex. It implements the Agent interface by wrapping a command-line executable.
| Feature | Implementation Detail |
|---|---|
| Command Execution | Uses rt.Exec to run the RunCmd defined in the agent's configuration internal/agent/cli.go136 |
| Instruction Building | Aggregates message history into a single string via BuildInstructionFromMessages internal/agent/cli.go132 |
| Credential Injection | Automatically merges API keys and environment variables into the ExecOptions internal/agent/cli.go134 |
| Windows Compatibility | Automatically translates POSIX command -v checks to Windows where and redirects /dev/null to nul via checkCommandForOS internal/agent/cli.go173-184 |
| MCP Support | Implements InstallMCP using a configurable template command internal/agent/cli.go25-79 |
Sources: internal/agent/cli.go19-22 internal/agent/cli.go126-158 internal/agent/cli.go187-206
Many Agent Engines are distributed as NPM packages. The ensureNodeRuntime function ensures that a compatible Node.js environment exists within the Runtime before the agent is invoked.
ensureNodeRuntime Logicclaude) is already on the PATH. If found, it exits immediately internal/agent/node_install.go85nvm.sh from $NVM_DIR internal/agent/node_install.go49curl from configured mirrors. It defaults to agentNVMInstallURL but falls back to agentNVMFallbackURL (Gitee) for restricted regions internal/agent/node_install.go56agentNVMInstallSHA256 internal/agent/node_install.go57-58v22) if the current version is older or missing internal/agent/node_install.go15 internal/agent/node_install.go63-66PATH internal/agent/node_install.go69Sources: internal/agent/node_install.go14-35 internal/agent/node_install.go79-98 internal/agent/node_install_test.go52-71
The framework handles the registration of Model Context Protocol servers into the agent's environment via installMCPServers.
The framework supports two primary transport types:
For Claude-compatible agents (including Qwen Code), it generates commands like claude mcp add --scope project <name> -- <command> via buildClaudeCompatibleMCPInstallCmd internal/agent/mcp.go47-100 It also handles shell environment variable expansion (e.g., ${API_KEY}) to ensure secrets are correctly resolved within the runtime using shellExpandedValue internal/agent/mcp.go109-141
Sources: internal/agent/mcp.go25-45 internal/agent/mcp.go47-100 internal/agent/cli.go25-79
To handle extremely large prompts that might exceed shell command length limits (ARG_MAX), the infrastructure includes a delivery mechanism called deliverPrompt.
SKILL_UP_PROMPT_INLINE_MAX_BYTES), it is passed directly in the command string internal/agent/prompt_delivery.go15-16 internal/agent/prompt_delivery.go44-46.skill-up/prompts/prompt.txt) and delivered to the agent via a cat pipe or file argument internal/agent/prompt_delivery.go54-66Sources: internal/agent/prompt_delivery.go33-67 internal/agent/prompt_delivery_test.go13-35
The factory system resolves which agent implementation to use based on the engine.name from eval.yaml.
DetectAgentWithInitParams (typically called via DetectAgent) maps credentials (API keys, Base URLs) and models into the specific agent configuration internal/agent/factory.go37-75 It handles engine-specific credential mapping, such as QODER_PERSONAL_ACCESS_TOKEN for QoderCLI engines internal/agent/factory.go65-68
The engine.kwargs map allows passing engine-specific flags.
logUnknownEngineKwargs emits a DEBUG line for unrecognized keys to catch typos like bypas_sandbox internal/agent/kwargs.go46-63EngineKwargBool provides robust parsing for values like "true", "1", or "T" using strconv.ParseBool internal/agent/kwargs.go29-39bypass_sandbox is a recognized kwarg used to disable agent-level sandboxing (e.g., Landlock in Codex) when the host kernel is incompatible or execution is already isolated by the runtime internal/agent/kwargs.go12-17Sources: internal/agent/factory.go11-32 internal/agent/factory.go37-75 internal/agent/kwargs.go12-25
This diagram shows how the DetectAgent factory leads to a configured CLIAgent and its eventual execution.
Sources: internal/agent/factory.go11-32 internal/agent/cli.go136 internal/agent/node_install.go79-88 internal/agent/kwargs.go46 internal/agent/prompt_delivery.go33
This diagram bridges the transcript types to the instruction building used by agents.
Sources: internal/agent/cli.go132-133
pkg/transcriptThe transcript package defines the standard message format used for communication between skill-up and the Agent Engines.
Message: Contains a Role (user, assistant, system, tool) and the string Content.Transcript: A slice of Message objects representing the conversation history. It provides helper methods for evaluation and reporting.internal/agent Public TypesSessionResult: The final output of an agent run, containing ExitCode, FinalMessage, DurationMs, Transcript, and Artifacts internal/agent/cli.go137-145ExecOptions: Configuration for a specific execution, including environment variables (Env), current working directory (Cwd), and artifact directories internal/agent/cli.go136 internal/agent/prompt_delivery.go33PromptDeliveryMetadata: Records how an agent prompt was delivered (inline vs file) and the associated paths internal/agent/prompt_delivery.go20-26Agents like Claude Code and QoderCLI generate session traces in JSONL format.
parseSessionFile (defined in internal/agent/claude_code.go) to extract transcripts and token usage internal/agent/README.md18-21Sources: internal/agent/cli.go126-158 internal/agent/README.md9-43 internal/agent/prompt_delivery.go20-26
Refresh this wiki