orchestra/internal/herdr/adapter.go

package herdr

import (
	"context"
	"encoding/json"
	"fmt"
	"path/filepath"
	"strings"
	"time"
)

type Adapter interface {
	Lease(context.Context, string, string) (Session, error)
	Bootstrap(context.Context, Session, string) error
	Release(context.Context, Session) (string, error)
	Kill(context.Context, Session) error
	Occupancy(Session) (float64, error)
}

type WorktreeCreator interface {
	CreateWorktree(context.Context, string, string, string) (string, error)
}

// TurnBoundary is optional so older herdr deployments remain usable. A true
// result means the current harness turn has ended and handoff is safe.
type TurnBoundary interface {
	AtTurnBoundary(context.Context, Session) (bool, error)
}
type PaneExit interface {
	PaneExited(context.Context, Session) (bool, error)
}

// AgentStatus is a live, non-lifecycle status reported by herdr. Consumers
// must not infer task completion or release from it.
type AgentStatus interface {
	AgentStatus(context.Context, Session) (string, error)
}
type AgentBlocker interface {
	AgentBlocker(context.Context, Session) (string, error)
}
type PaneCapture interface {
	PaneCapture(context.Context, Session, string) (string, error)
}
type CLIAdapter struct {
	Client  *Client
	Harness string
	Window  int64
	Usage   func(string) (Usage, error)
}

func (a CLIAdapter) CreateWorktree(ctx context.Context, repo, root, taskID string) (string, error) {
	path, err := a.Client.Worktree(ctx, repo, filepath.Join(root, taskID), "orchestra/"+taskID)
	if err != nil {
		return "", err
	}
	if path == "" {
		return "", fmt.Errorf("adapter: herdr returned empty worktree path")
	}
	return path, nil
}

func (a CLIAdapter) Lease(ctx context.Context, task, worktree string) (Session, error) {
	if a.Client == nil {
		return Session{}, fmt.Errorf("adapter: client required")
	}
	s, err := a.Client.StartAgent(ctx, worktree, worktree, "orchestra/"+task, a.Harness, task)
	if err != nil {
		return Session{}, err
	}
	if err := a.Client.Prompt(ctx, s.PaneID, fmt.Sprintf("Begin Orchestra task %s. Inspect the repository, understand the task context, and proceed with the requested work.", task), time.Minute); err != nil {
		return Session{}, err
	}
	return s, nil
}
func (a CLIAdapter) Bootstrap(ctx context.Context, s Session, ref string) error {
	return a.Client.Prompt(ctx, s.PaneID, fmt.Sprintf("Read handoff %s, validate the anchor and TASK.md, then continue.", ref), time.Minute)
}
// Release previously called the invented "pane.release" method expecting a
// handoff_ref back. Neither exists in the real protocol (confirmed against a
// live herdr instance, AUDIT.md Phase 0): the real method is
// pane.release_agent(pane_id, source, agent), which only releases herdr's
// claim on the agent session — it cannot return a handoff_ref, because herdr
// does not write handoffs, the agent does (§6.1). Wiring this correctly needs
// the Phase 4 handoff-production path (agent writes handoff, stop hook
// uploads it to CAS, plane validates and mints the ref) before Release has
// anything real to return. Refusing loudly until then rather than calling a
// method that doesn't exist.
func (a CLIAdapter) Release(ctx context.Context, s Session) (string, error) {
	return "", fmt.Errorf("adapter: Release not implemented — pane.release is not a real herdr method and handoff production (AUDIT.md Phase 4) is not wired yet")
}
func (a CLIAdapter) Kill(ctx context.Context, s Session) error {
	return a.Client.Call(ctx, "pane.close", map[string]any{"pane_id": s.PaneID}, nil)
}
func (a CLIAdapter) AtTurnBoundary(ctx context.Context, s Session) (bool, error) {
	status, err := a.AgentStatus(ctx, s)
	if err != nil {
		return false, err
	}
	return !IsBusy(status), nil
}
func (a CLIAdapter) PaneExited(ctx context.Context, s Session) (bool, error) {
	status, err := a.AgentStatus(ctx, s)
	if err != nil {
		return false, err
	}
	return strings.EqualFold(status, "exited") || strings.EqualFold(status, "dead"), nil
}
func (a CLIAdapter) AgentStatus(ctx context.Context, s Session) (string, error) {
	// Current herdr protocol exposes agent state through agent.get; older
	// Orchestra code used pane.status, which is not a valid protocol method.
	var r map[string]any
	if err := a.Client.Call(ctx, "agent.get", map[string]any{"target": s.PaneID}, &r); err != nil {
		return "", err
	}
	return statusFromAgentResult(r), nil
}

func (a CLIAdapter) AgentBlocker(ctx context.Context, s Session) (string, error) {
	var r struct {
		Read struct {
			Text string `json:"text"`
		} `json:"read"`
	}
	if err := a.Client.Call(ctx, "pane.read", map[string]any{"pane_id": s.PaneID, "source": "recent"}, &r); err != nil {
		return "", err
	}
	text := strings.TrimSpace(r.Read.Text)
	lines := strings.Split(text, "\n")
	for i, raw := range lines {
		line := strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(raw), "┃"))
		if !strings.EqualFold(line, "Permission required") && !strings.EqualFold(line, "Approval required") && !strings.HasPrefix(strings.ToLower(line), "waiting for") {
			continue
		}
		for _, next := range lines[i+1:] {
			command := strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(next), "┃"))
			if strings.HasPrefix(command, "$ ") {
				return strings.ToLower(line) + ": shell command `" + strings.TrimSpace(strings.TrimPrefix(command, "$ ")) + "`", nil
			}
		}
		return strings.ToLower(line), nil
	}
	return "", nil
}

func (a CLIAdapter) PaneCapture(ctx context.Context, s Session, source string) (string, error) {
	if source == "" {
		source = "recent"
	}
	var r struct {
		Read struct {
			Text string `json:"text"`
		} `json:"read"`
	}
	if err := a.Client.Call(ctx, "pane.read", map[string]any{"pane_id": s.PaneID, "source": source}, &r); err != nil {
		return "", err
	}
	return r.Read.Text, nil
}

func statusFromAgentResult(v any) string {
	if m, ok := v.(map[string]any); ok {
		for _, key := range []string{"status", "agent_status", "state"} {
			if s, ok := m[key].(string); ok && s != "" {
				return s
			}
		}
		for _, child := range m {
			if s := statusFromAgentResult(child); s != "" {
				return s
			}
		}
	}
	if a, ok := v.([]any); ok {
		for _, child := range a {
			if s := statusFromAgentResult(child); s != "" {
				return s
			}
		}
	}
	return ""
}

var _ = json.RawMessage{}

// Occupancy reads the harness's own session state — never the herdr pane id,
// which ClaudeUsage/CodexUsage/OpenCodeUsage cannot open (spec §5.2.1: "the
// whole rotation system rests on this number"). A session file that cannot
// be resolved or read is a hard error, not a silently-empty Usage{}, so
// callers (Coordinator.rotate, refreshSessionHealth) surface it instead of
// mistaking "we don't know" for "occupancy is zero".
func (a CLIAdapter) Occupancy(s Session) (float64, error) {
	if a.Usage == nil {
		return 0, fmt.Errorf("adapter: usage reader required")
	}
	path := s.SessionFile
	if path == "" {
		resolved, err := a.resolveSessionFile(s)
		if err != nil {
			return 0, fmt.Errorf("adapter: resolve session file: %w", err)
		}
		path = resolved
	}
	u, e := a.Usage(path)
	if e != nil {
		return 0, fmt.Errorf("adapter: read usage from %s: %w", path, e)
	}
	return Fraction(u, a.Window), nil
}

func (a CLIAdapter) resolveSessionFile(s Session) (string, error) {
	switch a.Harness {
	case "claude":
		return ClaudeSessionFile(s.Worktree)
	case "codex":
		_, path, err := CodexActiveUsage("")
		return path, err
	default:
		// opencode's session-file resolution needs the running session id,
		// which is only available via the SSE/status API (OpenCodeStatus),
		// not derivable from the worktree alone. Per AUDIT.md Phase 1, wiring
		// this needs verification against a live opencode instance before it
		// can drive rotation — refuse loudly rather than guess a path.
		return "", fmt.Errorf("adapter: harness %q has no session-file resolver; verify against a live session first (AUDIT.md Phase 1)", a.Harness)
	}
}

var Claude = func(c *Client, w int64) CLIAdapter {
	return CLIAdapter{Client: c, Harness: "claude", Window: w, Usage: ClaudeUsage}
}
var Codex = func(c *Client, w int64) CLIAdapter {
	return CLIAdapter{Client: c, Harness: "codex", Window: w, Usage: CodexUsage}
}
var OpenCode = func(c *Client, w int64) CLIAdapter {
	return CLIAdapter{Client: c, Harness: "opencode", Window: w, Usage: OpenCodeUsage}
}