feat: implement 14 features from herm/langdag comparison

- Two-mode sub-agents (explore=read-only/cheap vs general=full/strong)
- Tool registry filtering for sub-agent allowlisting
- Container sandbox with Docker lifecycle and hot-swap support
- Dynamic DevEnv manager with Dockerfile caching per-project
- Background agent pool with async completion cycles
- Project snapshot cache with 10s TTL for rapid sub-agent spawns
- HTTP API server (health, version, chat stub)
- Per-node token/latency metrics collector (ring buffer)

All 48 packages pass with race detector.

Author: Patel230

.gitignore

@@ -26,4 +26,4 @@ dist/
 .gocache/
 .gomodcache/
 go.work
-go.work.sum
+go.work.sum.hawk/

api/server.go

@@ -0,0 +1,135 @@
+// Package api provides an HTTP API server for hawk, consumable by SDKs.
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"net/http"
+	"sync"
+)
+
+// Version is the current hawk API version.
+const Version = "0.4.0"
+
+// Server is the HTTP API server for hawk.
+type Server struct {
+	addr   string
+	mux    *http.ServeMux
+	server *http.Server
+	mu     sync.Mutex
+}
+
+// ChatRequest is the request body for POST /chat.
+type ChatRequest struct {
+	Message string `json:"message"`
+	Model   string `json:"model"`
+}
+
+// ChatResponse is the response body for POST /chat.
+type ChatResponse struct {
+	Response string `json:"response"`
+}
+
+// HealthResponse is the response body for GET /health.
+type HealthResponse struct {
+	Status string `json:"status"`
+}
+
+// VersionResponse is the response body for GET /version.
+type VersionResponse struct {
+	Version string `json:"version"`
+}
+
+// New creates a new API server listening on the given address.
+func New(addr string) *Server {
+	mux := http.NewServeMux()
+	s := &Server{
+		addr: addr,
+		mux:  mux,
+	}
+	s.registerRoutes()
+	return s
+}
+
+// registerRoutes sets up the HTTP endpoints.
+func (s *Server) registerRoutes() {
+	s.mux.HandleFunc("GET /health", s.handleHealth)
+	s.mux.HandleFunc("GET /version", s.handleVersion)
+	s.mux.HandleFunc("POST /chat", s.handleChat)
+}
+
+// Start starts the HTTP server. It blocks until the context is cancelled or an error occurs.
+func (s *Server) Start(ctx context.Context) error {
+	s.mu.Lock()
+	s.server = &http.Server{
+		Addr:    s.addr,
+		Handler: s.mux,
+	}
+	s.mu.Unlock()
+
+	ln, err := net.Listen("tcp", s.addr)
+	if err != nil {
+		return err
+	}
+
+	go func() {
+		<-ctx.Done()
+		s.server.Shutdown(context.Background())
+	}()
+
+	err = s.server.Serve(ln)
+	if err == http.ErrServerClosed {
+		return nil
+	}
+	return err
+}
+
+// Stop gracefully shuts down the HTTP server.
+func (s *Server) Stop(ctx context.Context) error {
+	s.mu.Lock()
+	srv := s.server
+	s.mu.Unlock()
+
+	if srv == nil {
+		return nil
+	}
+	return srv.Shutdown(ctx)
+}
+
+// Handler returns the underlying http.Handler for testing purposes.
+func (s *Server) Handler() http.Handler {
+	return s.mux
+}
+
+func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, HealthResponse{Status: "ok"})
+}
+
+func (s *Server) handleVersion(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, VersionResponse{Version: Version})
+}
+
+func (s *Server) handleChat(w http.ResponseWriter, r *http.Request) {
+	var req ChatRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, `{"error":"invalid request body"}`, http.StatusBadRequest)
+		return
+	}
+	if req.Message == "" {
+		http.Error(w, `{"error":"message is required"}`, http.StatusBadRequest)
+		return
+	}
+
+	// Stub response
+	resp := ChatResponse{
+		Response: "This is a stub response. Model: " + req.Model + ", Message: " + req.Message,
+	}
+	writeJSON(w, http.StatusOK, resp)
+}
+
+func writeJSON(w http.ResponseWriter, status int, v interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(v)
+}

api/server_test.go

@@ -0,0 +1,116 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestHealthEndpoint(t *testing.T) {
+	srv := New(":0")
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	w := httptest.NewRecorder()
+
+	srv.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+
+	var resp HealthResponse
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if resp.Status != "ok" {
+		t.Fatalf("expected status 'ok', got %q", resp.Status)
+	}
+}
+
+func TestVersionEndpoint(t *testing.T) {
+	srv := New(":0")
+	req := httptest.NewRequest(http.MethodGet, "/version", nil)
+	w := httptest.NewRecorder()
+
+	srv.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+
+	var resp VersionResponse
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if resp.Version != "0.4.0" {
+		t.Fatalf("expected version '0.4.0', got %q", resp.Version)
+	}
+}
+
+func TestChatEndpoint_Success(t *testing.T) {
+	srv := New(":0")
+
+	body := ChatRequest{Message: "hello", Model: "gpt-4"}
+	b, _ := json.Marshal(body)
+	req := httptest.NewRequest(http.MethodPost, "/chat", bytes.NewReader(b))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	srv.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+
+	var resp ChatResponse
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if resp.Response == "" {
+		t.Fatal("expected non-empty response")
+	}
+}
+
+func TestChatEndpoint_EmptyMessage(t *testing.T) {
+	srv := New(":0")
+
+	body := ChatRequest{Message: "", Model: "gpt-4"}
+	b, _ := json.Marshal(body)
+	req := httptest.NewRequest(http.MethodPost, "/chat", bytes.NewReader(b))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	srv.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestChatEndpoint_InvalidJSON(t *testing.T) {
+	srv := New(":0")
+
+	req := httptest.NewRequest(http.MethodPost, "/chat", bytes.NewReader([]byte("not json")))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	srv.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestHealthEndpoint_ContentType(t *testing.T) {
+	srv := New(":0")
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	w := httptest.NewRecorder()
+
+	srv.Handler().ServeHTTP(w, req)
+
+	ct := w.Header().Get("Content-Type")
+	if ct != "application/json" {
+		t.Fatalf("expected Content-Type 'application/json', got %q", ct)
+	}
+}