Hermes byo harness

client.go
package main

import (
	"context"
	"sync"

	acp "github.com/coder/acp-go-sdk"
	harnessruntime "github.com/kagent-dev/kagent/go/harness/runtime"
)

type hermesACPClient struct {
	mu        sync.RWMutex
	sink      harnessruntime.EventSink
	toolNames map[string]string
}

func newHermesACPClient() *hermesACPClient {
	return &hermesACPClient{toolNames: map[string]string{}}
}

func (c *hermesACPClient) setSink(sink harnessruntime.EventSink) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.sink = sink
}

func (c *hermesACPClient) SessionUpdate(_ context.Context, notification acp.SessionNotification) error {
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.sink == nil {
		return nil
	}
	update := notification.Update
	switch {
	case update.AgentMessageChunk != nil && update.AgentMessageChunk.Content.Text != nil:
		return c.sink.TextDelta(harnessruntime.TextDelta{Text: update.AgentMessageChunk.Content.Text.Text})
	case update.ToolCall != nil:
		name := update.ToolCall.Title
		id := string(update.ToolCall.ToolCallId)
		c.toolNames[id] = name
		arguments, _ := update.ToolCall.RawInput.(map[string]any)
		return c.sink.ToolCall(harnessruntime.ToolCall{ID: id, Name: name, Arguments: arguments})
	case update.ToolCallUpdate != nil && update.ToolCallUpdate.Status != nil:
		status := *update.ToolCallUpdate.Status
		if status != acp.ToolCallStatusCompleted && status != acp.ToolCallStatusFailed {
			return nil
		}
		id := string(update.ToolCallUpdate.ToolCallId)
		return c.sink.ToolResult(harnessruntime.ToolResult{
			ID: id, Name: c.toolNames[id], Result: update.ToolCallUpdate.RawOutput,
			IsError: status == acp.ToolCallStatusFailed,
		})
	default:
		return nil
	}
}

func (c *hermesACPClient) RequestPermission(_ context.Context, request acp.RequestPermissionRequest) (acp.RequestPermissionResponse, error) {
	for _, option := range request.Options {
		if option.Kind == acp.PermissionOptionKindRejectOnce || option.Kind == acp.PermissionOptionKindRejectAlways {
			return acp.RequestPermissionResponse{Outcome: acp.RequestPermissionOutcome{
				Selected: &acp.RequestPermissionOutcomeSelected{Outcome: "selected", OptionId: option.OptionId},
			}}, nil
		}
	}
	return acp.RequestPermissionResponse{Outcome: acp.RequestPermissionOutcome{
		Cancelled: &acp.RequestPermissionOutcomeCancelled{Outcome: "cancelled"},
	}}, nil
}

func (c *hermesACPClient) ReadTextFile(context.Context, acp.ReadTextFileRequest) (acp.ReadTextFileResponse, error) {
	return acp.ReadTextFileResponse{}, acp.NewMethodNotFound("fs/read_text_file")
}

func (c *hermesACPClient) WriteTextFile(context.Context, acp.WriteTextFileRequest) (acp.WriteTextFileResponse, error) {
	return acp.WriteTextFileResponse{}, acp.NewMethodNotFound("fs/write_text_file")
}

func (c *hermesACPClient) CreateTerminal(context.Context, acp.CreateTerminalRequest) (acp.CreateTerminalResponse, error) {
	return acp.CreateTerminalResponse{}, acp.NewMethodNotFound("terminal/create")
}

func (c *hermesACPClient) KillTerminal(context.Context, acp.KillTerminalRequest) (acp.KillTerminalResponse, error) {
	return acp.KillTerminalResponse{}, acp.NewMethodNotFound("terminal/kill")
}

func (c *hermesACPClient) TerminalOutput(context.Context, acp.TerminalOutputRequest) (acp.TerminalOutputResponse, error) {
	return acp.TerminalOutputResponse{}, acp.NewMethodNotFound("terminal/output")
}

func (c *hermesACPClient) ReleaseTerminal(context.Context, acp.ReleaseTerminalRequest) (acp.ReleaseTerminalResponse, error) {
	return acp.ReleaseTerminalResponse{}, acp.NewMethodNotFound("terminal/release")
}

func (c *hermesACPClient) WaitForTerminalExit(context.Context, acp.WaitForTerminalExitRequest) (acp.WaitForTerminalExitResponse, error) {
	return acp.WaitForTerminalExitResponse{}, acp.NewMethodNotFound("terminal/wait_for_exit")
}

var _ acp.Client = (*hermesACPClient)(nil)
client_test.go
package main

import (
	"context"
	"testing"

	acp "github.com/coder/acp-go-sdk"
	harnessruntime "github.com/kagent-dev/kagent/go/harness/runtime"
)

type recordingSink struct {
	text   string
	call   harnessruntime.ToolCall
	result harnessruntime.ToolResult
}

func (*recordingSink) SessionStarted(harnessruntime.SessionStarted) error { return nil }
func (s *recordingSink) TextDelta(delta harnessruntime.TextDelta) error {
	s.text += delta.Text
	return nil
}
func (s *recordingSink) ToolCall(call harnessruntime.ToolCall) error { s.call = call; return nil }
func (s *recordingSink) ToolResult(result harnessruntime.ToolResult) error {
	s.result = result
	return nil
}
func (*recordingSink) ModelCall(harnessruntime.ModelCall) {}

func TestHermesACPClientForwardsText(t *testing.T) {
	t.Parallel()
	sink := &recordingSink{}
	client := newHermesACPClient()
	client.setSink(sink)
	err := client.SessionUpdate(context.Background(), acp.SessionNotification{Update: acp.UpdateAgentMessageText("hello")})
	if err != nil {
		t.Fatal(err)
	}
	if sink.text != "hello" {
		t.Fatalf("got %q, want hello", sink.text)
	}
}

func TestHermesACPClientRejectsPermission(t *testing.T) {
	t.Parallel()
	client := newHermesACPClient()
	response, err := client.RequestPermission(context.Background(), acp.RequestPermissionRequest{Options: []acp.PermissionOption{{
		OptionId: "deny", Kind: acp.PermissionOptionKindRejectOnce, Name: "Reject",
	}}})
	if err != nil {
		t.Fatal(err)
	}
	if response.Outcome.Selected == nil || response.Outcome.Selected.OptionId != "deny" {
		t.Fatalf("unexpected response: %#v", response)
	}
}
config.go
package main

import (
	"fmt"
	"os"
	"path/filepath"
	"strings"

	"gopkg.in/yaml.v3"

	runtimeconfig "github.com/kagent-dev/kagent/go/adk/pkg/config"
	configv1 "github.com/kagent-dev/kagent/go/api/gen/kagent/config/v1"
)

type hermesConfig struct {
	Model struct {
		Default   string `yaml:"default"`
		Provider  string `yaml:"provider"`
		BaseURL   string `yaml:"base_url,omitempty"`
		MaxTokens int    `yaml:"max_tokens"`
	} `yaml:"model"`
	Providers map[string]hermesProvider `yaml:"providers"`
	Agent     struct {
		SystemPrompt string `yaml:"system_prompt,omitempty"`
	} `yaml:"agent"`
	Terminal struct {
		Cwd string `yaml:"cwd"`
	} `yaml:"terminal"`
}

type hermesProvider struct {
	BaseURL string `yaml:"base_url"`
	KeyEnv  string `yaml:"key_env"`
	APIMode string `yaml:"api_mode"`
	Model   string `yaml:"model"`
}

// parseConfig reads the ADKConfig that kagent compiles for every BYO runtime.
func parseConfig(raw []byte) (*configv1.ADKConfig, error) {
	cfg := new(configv1.ADKConfig)
	if err := runtimeconfig.Unmarshal(raw, cfg); err != nil {
		return nil, fmt.Errorf("decode %s: %w", configEnv, err)
	}
	return cfg, nil
}

func materializeHermesConfig(cfg *configv1.ADKConfig, dataDir, workspace string) error {
	model := cfg.GetAgent().GetModel()
	openai := model.GetOpenai()
	if openai == nil {
		return fmt.Errorf("Hermes BYO runtime currently supports only OpenAI ModelConfig")
	}
	if strings.TrimSpace(model.GetModel()) == "" {
		return fmt.Errorf("OpenAI model name is required")
	}

	var output hermesConfig
	output.Model.Default = model.GetModel()
	output.Model.Provider = "openai"
	output.Model.BaseURL = openai.GetBaseUrl()
	output.Model.MaxTokens = int(openai.GetMaxCompletionTokens())
	if output.Model.MaxTokens == 0 {
		output.Model.MaxTokens = int(openai.GetMaxTokens())
	}
	if output.Model.MaxTokens == 0 {
		output.Model.MaxTokens = 32768
	}
	if output.Model.BaseURL == "" {
		output.Model.BaseURL = "https://api.openai.com/v1"
	}
	output.Providers = map[string]hermesProvider{"openai": {
		BaseURL: output.Model.BaseURL,
		KeyEnv:  "OPENAI_API_KEY",
		APIMode: "chat_completions",
		Model:   output.Model.Default,
	}}
	output.Agent.SystemPrompt = cfg.GetAgent().GetInstruction()
	output.Terminal.Cwd = workspace

	home := filepath.Join(dataDir, "hermes")
	if err := os.MkdirAll(home, 0o700); err != nil {
		return fmt.Errorf("create Hermes home: %w", err)
	}
	if err := os.MkdirAll(workspace, 0o700); err != nil {
		return fmt.Errorf("create Hermes workspace: %w", err)
	}
	contents, err := yaml.Marshal(output)
	if err != nil {
		return fmt.Errorf("marshal Hermes configuration: %w", err)
	}
	if err := os.WriteFile(filepath.Join(home, "config.yaml"), contents, 0o600); err != nil {
		return fmt.Errorf("write Hermes configuration: %w", err)
	}
	return nil
}
config_test.go
package main

import (
	"os"
	"path/filepath"
	"strings"
	"testing"
)

func TestMaterializeHermesConfig(t *testing.T) {
	t.Parallel()
	root := t.TempDir()
	workspace := filepath.Join(root, "workspace")
	cfg, err := parseConfig([]byte(`{"runtime":{"control_plane_url":"http://kagent-controller.kagent:8083","name":"hermes-assistant","namespace":"kagent"},` +
		`"agent":{"name":"hermes_assistant","instruction":"Be concise.","model":{"model":"gpt-4.1-mini","openai":{"base_url":"https://api.openai.com/v1"}}}}`))
	if err != nil {
		t.Fatal(err)
	}
	if err := materializeHermesConfig(cfg, root, workspace); err != nil {
		t.Fatal(err)
	}
	contents, err := os.ReadFile(filepath.Join(root, "hermes", "config.yaml"))
	if err != nil {
		t.Fatal(err)
	}
	text := string(contents)
	for _, expected := range []string{
		"default: gpt-4.1-mini", "provider: openai", "base_url: https://api.openai.com/v1",
		"max_tokens: 32768", "key_env: OPENAI_API_KEY", "api_mode: chat_completions", "system_prompt: Be concise.",
	} {
		if !strings.Contains(text, expected) {
			t.Fatalf("configuration does not contain %q:\n%s", expected, text)
		}
	}
}

func TestMaterializeHermesConfigRejectsUnsupportedProvider(t *testing.T) {
	t.Parallel()
	cfg, err := parseConfig([]byte(`{"agent":{"name":"hermes_assistant","model":{"model":"claude-sonnet-4-5","anthropic":{}}}}`))
	if err != nil {
		t.Fatal(err)
	}
	err = materializeHermesConfig(cfg, t.TempDir(), t.TempDir())
	if err == nil || !strings.Contains(err.Error(), "only OpenAI") {
		t.Fatalf("expected unsupported provider error, got %v", err)
	}
}

func TestParseConfigRejectsLegacyShape(t *testing.T) {
	t.Parallel()
	if _, err := parseConfig([]byte(`{"model":{"type":"openai","model":"gpt-4.1-mini"},"instruction":"Be concise."}`)); err == nil {
		t.Fatal("expected the pre-1.0 configuration shape to be rejected")
	}
}
main.go
package main

import (
	"cmp"
	"context"
	"encoding/json"
	"flag"
	"fmt"
	"log/slog"
	"os"
	"strings"

	a2atype "github.com/a2aproject/a2a-go/v2/a2a"
	"github.com/kagent-dev/kagent/go/adk/pkg/app"
	runtimea2a "github.com/kagent-dev/kagent/go/harness/runtime/a2a"
	"github.com/kagent-dev/kagent/go/harness/runtime/continuation"
	"github.com/kagent-dev/kagent/go/pkg/logging"
	"github.com/kagent-dev/kagent/go/pkg/tracing"
)

const (
	configEnv    = "KAGENT_CONFIG_JSON"
	agentCardEnv = "KAGENT_AGENT_CARD_JSON"
	dataDir      = "/data"
	workspaceDir = "/data/workspace"
	privatePort  = "80"
)

func main() {
	check := flag.Bool("check", false, "validate configuration and Hermes ACP startup, then exit")
	flag.Parse()
	logger, err := logging.New(os.Stderr, "info")
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	ctx := logging.IntoContext(context.Background(), logger)
	if err := run(ctx, logger, *check); err != nil {
		logger.ErrorContext(ctx, "Hermes Harness stopped", "error", err)
		os.Exit(1)
	}
}

func run(ctx context.Context, logger *slog.Logger, check bool) error {
	configJSON, err := requiredEnvironment(configEnv)
	if err != nil {
		return err
	}
	agentCardJSON, err := requiredEnvironment(agentCardEnv)
	if err != nil {
		return err
	}

	var card a2atype.AgentCard
	if err := json.Unmarshal(agentCardJSON, &card); err != nil {
		return fmt.Errorf("decode Agent Card: %w", err)
	}
	if strings.TrimSpace(card.Name) == "" {
		return fmt.Errorf("Agent Card name is required")
	}

	cfg, err := parseConfig(configJSON)
	if err != nil {
		return err
	}
	// The compiled runtime config carries the log level, so rebuild the logger once it is known.
	if logger, err = logging.New(os.Stderr, cmp.Or(cfg.GetRuntime().GetLogLevel(), "info")); err != nil {
		return err
	}
	ctx = logging.IntoContext(ctx, logger)
	if err := materializeHermesConfig(cfg, dataDir, workspaceDir); err != nil {
		return err
	}
	runner := newHermesRunner(logger, []string{"hermes", "acp"}, dataDir, workspaceDir)
	defer runner.Close()
	if check {
		if err := runner.Check(ctx); err != nil {
			return fmt.Errorf("check Hermes runtime: %w", err)
		}
		return nil
	}
	store, err := continuation.New(dataDir+"/adapter", "hermes", validateSessionID)
	if err != nil {
		return fmt.Errorf("create continuation store: %w", err)
	}
	// A BYO runtime has no compiled telemetry identity, so the executor gets the empty one.
	executor, err := runtimea2a.New(runner, store, tracing.RuntimeTelemetry{})
	if err != nil {
		return fmt.Errorf("create A2A executor: %w", err)
	}
	application, err := app.New(app.AppConfig{
		AgentCard:       card,
		Port:            privatePort,
		AppName:         card.Name,
		ControlPlaneURL: cfg.GetRuntime().GetControlPlaneUrl(),
		Logger:          logger,
	}, executor)
	if err != nil {
		return fmt.Errorf("construct private A2A app: %w", err)
	}
	return application.Run()
}

func requiredEnvironment(name string) ([]byte, error) {
	value := strings.TrimSpace(os.Getenv(name))
	if value == "" {
		return nil, fmt.Errorf("%s is required", name)
	}
	return []byte(value), nil
}

func validateSessionID(id string) error {
	if strings.TrimSpace(id) == "" {
		return fmt.Errorf("Hermes session ID is empty")
	}
	return nil
}
runner.go
package main

import (
	"context"
	"errors"
	"fmt"
	"io"
	"log/slog"
	"os"
	"os/exec"
	"sync"

	acp "github.com/coder/acp-go-sdk"
	harnessruntime "github.com/kagent-dev/kagent/go/harness/runtime"
)

type hermesRunner struct {
	logger    *slog.Logger
	command   []string
	dataDir   string
	workspace string

	mu         sync.Mutex
	process    *exec.Cmd
	input      io.WriteCloser
	connection *acp.ClientSideConnection
	client     *hermesACPClient
	sessionID  string
}

func newHermesRunner(logger *slog.Logger, command []string, dataDir, workspace string) *hermesRunner {
	return &hermesRunner{logger: logger, command: command, dataDir: dataDir, workspace: workspace}
}

func (r *hermesRunner) Check(ctx context.Context) error {
	r.mu.Lock()
	defer r.mu.Unlock()
	return r.ensureConnected(ctx, "")
}

func (r *hermesRunner) Run(ctx context.Context, turn harnessruntime.Turn, sink harnessruntime.EventSink) (harnessruntime.Outcome, error) {
	r.mu.Lock()
	defer r.mu.Unlock()
	if err := r.ensureConnected(ctx, turn.ContinuationID); err != nil {
		return harnessruntime.Outcome{}, err
	}
	if turn.ContinuationID == "" {
		if err := sink.SessionStarted(harnessruntime.SessionStarted{ContinuationID: r.sessionID}); err != nil {
			return harnessruntime.Outcome{}, err
		}
	}

	r.client.setSink(sink)
	defer r.client.setSink(nil)
	_, err := r.connection.Prompt(ctx, acp.PromptRequest{
		SessionId: acp.SessionId(r.sessionID),
		Prompt:    []acp.ContentBlock{acp.TextBlock(turn.Prompt)},
	})
	if err != nil {
		return harnessruntime.Outcome{}, fmt.Errorf("prompt Hermes session %s: %w", r.sessionID, err)
	}
	return harnessruntime.Outcome{}, nil
}

func (r *hermesRunner) ensureConnected(ctx context.Context, continuationID string) error {
	if r.connection != nil {
		select {
		case <-r.connection.Done():
			r.stopProcess()
		default:
			if continuationID == "" || continuationID == r.sessionID {
				return nil
			}
			return fmt.Errorf("Hermes runtime is bound to session %s, not %s", r.sessionID, continuationID)
		}
	}
	if len(r.command) == 0 {
		return fmt.Errorf("Hermes command is required")
	}

	cmd := exec.Command(r.command[0], r.command[1:]...)
	cmd.Dir = r.workspace
	cmd.Env = append(os.Environ(), "HERMES_HOME="+r.dataDir+"/hermes", "HOME="+r.dataDir)
	cmd.Stderr = os.Stderr
	stdin, err := cmd.StdinPipe()
	if err != nil {
		return fmt.Errorf("open Hermes stdin: %w", err)
	}
	stdout, err := cmd.StdoutPipe()
	if err != nil {
		_ = stdin.Close()
		return fmt.Errorf("open Hermes stdout: %w", err)
	}
	if err := cmd.Start(); err != nil {
		_ = stdin.Close()
		return fmt.Errorf("start Hermes ACP process: %w", err)
	}

	client := newHermesACPClient()
	connection := acp.NewClientSideConnection(client, stdin, stdout)
	connection.SetLogger(r.logger)
	if _, err := connection.Initialize(ctx, acp.InitializeRequest{
		ProtocolVersion:    acp.ProtocolVersionNumber,
		ClientCapabilities: acp.ClientCapabilities{},
	}); err != nil {
		stopCommand(cmd, stdin)
		return fmt.Errorf("initialize Hermes ACP connection: %w", err)
	}

	if continuationID == "" {
		session, err := connection.NewSession(ctx, acp.NewSessionRequest{Cwd: r.workspace, McpServers: []acp.McpServer{}})
		if err != nil {
			stopCommand(cmd, stdin)
			return fmt.Errorf("create Hermes ACP session: %w", err)
		}
		r.sessionID = string(session.SessionId)
	} else {
		if _, err := connection.LoadSession(ctx, acp.LoadSessionRequest{
			Cwd: r.workspace, SessionId: acp.SessionId(continuationID), McpServers: []acp.McpServer{},
		}); err != nil {
			stopCommand(cmd, stdin)
			return fmt.Errorf("load Hermes ACP session %s: %w", continuationID, err)
		}
		r.sessionID = continuationID
	}

	r.process = cmd
	r.input = stdin
	r.connection = connection
	r.client = client
	return nil
}

func (r *hermesRunner) Close() error {
	r.mu.Lock()
	defer r.mu.Unlock()
	return r.stopProcess()
}

func (r *hermesRunner) stopProcess() error {
	var err error
	if r.input != nil {
		err = r.input.Close()
	}
	if r.process != nil && r.process.Process != nil {
		if killErr := r.process.Process.Kill(); killErr != nil && !errors.Is(killErr, os.ErrProcessDone) && err == nil {
			err = killErr
		}
		_ = r.process.Wait()
	}
	r.process = nil
	r.input = nil
	r.connection = nil
	r.client = nil
	r.sessionID = ""
	return err
}

func stopCommand(cmd *exec.Cmd, input io.Closer) {
	_ = input.Close()
	if cmd.Process != nil {
		_ = cmd.Process.Kill()
		_ = cmd.Wait()
	}
}