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), 0); 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} }