Agent Executor (AX) is Google's open agentic orchestration runtime
Go
Serve the Antigravity Interactions harness over HarnessService (#274)
zbl94e764d366a5c6
diff --git a/cmd/ax/harness.go b/cmd/ax/harness.goindex a9735e6..fc72be8 100644--- a/cmd/ax/harness.go+++ b/cmd/ax/harness.go@@ -25,10 +25,12 @@ import ("net/http""os""os/signal"+ "path/filepath""strconv""syscall""time"+ "github.com/google/ax/internal/harness/antigravityinteractions""github.com/google/ax/internal/pythonsidecar""github.com/spf13/cobra""google.golang.org/grpc"@@ -116,6 +118,34 @@ func runHarness(cmd *cobra.Command, args []string) error {return nil}+func runAntigravityInteractionsHarness(ctx context.Context, systemInstructions string) error {+ if err := setHarnessWorkDir(); err != nil {+ return err+ }+ stateDir, err := harnessStateDir()+ if err != nil {+ return err+ }+ cfg := antigravityinteractions.AntigravityInteractionsConfig{+ SystemInstruction: systemInstructions,+ StateDir: stateDir,+ }+ return antigravityinteractions.Serve(ctx, cfg, harnessHost, harnessPort, harnessReadyzPort)+}++// harnessStateDir returns the directory for persisting resume cursors: a+// dedicated "~/.ax/cursors" under the user's home directory. It lives OUTSIDE the+// agent's working directory on purpose -- the working directory is the agent's+// operating surface (it reads and edits files there, including hidden ones), so+// AX's internal state is kept separate to avoid the agent seeing or clobbering it.+func harnessStateDir() (string, error) {+ home, err := os.UserHomeDir()+ if err != nil {+ return "", fmt.Errorf("resolving home directory for resume-cursor state: %w", err)+ }+ return filepath.Join(home, ".ax", "cursors"), nil+}+// serveReadyz serves the HTTP /readyz endpoint on readyzPort that substrate's// readiness probe polls (during golden snapshotting and per-actor Run/Restore).// Each request forwards to the forked harness's gRPC health Check.diff --git a/internal/harness/antigravityinteractions/server.go b/internal/harness/antigravityinteractions/server.gonew file mode 100644index 0000000..7d77a43--- /dev/null+++ b/internal/harness/antigravityinteractions/server.go@@ -0,0 +1,225 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package antigravityinteractions++import (+ "context"+ "errors"+ "fmt"+ "log"+ "net"+ "net/http"+ "os"+ "os/signal"+ "strconv"+ "sync"+ "syscall"++ "github.com/google/ax/internal/harness"+ "github.com/google/ax/proto"+ "google.golang.org/grpc"+ "google.golang.org/grpc/health"+ healthpb "google.golang.org/grpc/health/grpc_health_v1"+)++// server adapts the Antigravity Interactions harness (a Go harness.Harness) onto+// the gRPC HarnessService that the AX controller connects to. One server serves+// one actor's lifetime; substrate creates the actor per request.+type server struct {+ proto.UnimplementedHarnessServiceServer+ h harness.Harness+}++// Serve builds the Antigravity Interactions harness from cfg and serves the+// HarnessService (plus gRPC health) on host:port, and an HTTP /readyz endpoint on+// readyzPort that reflects this server's own serving state. It blocks until ctx+// is cancelled or a termination signal (SIGINT/SIGTERM) is received, then shuts+// down gracefully.+func Serve(ctx context.Context, cfg AntigravityInteractionsConfig, host string, port, readyzPort int) error {+ h, err := New(cfg)+ if err != nil {+ return fmt.Errorf("creating antigravity interactions harness: %w", err)+ }++ lis, err := net.Listen("tcp", net.JoinHostPort(host, strconv.Itoa(port)))+ if err != nil {+ return fmt.Errorf("listen on %s:%d: %w", host, port, err)+ }++ grpcServer := grpc.NewServer()+ proto.RegisterHarnessServiceServer(grpcServer, &server{h: h})++ // gRPC health: report SERVING for the default service so the controller's+ // health checks pass.+ hs := health.NewServer()+ hs.SetServingStatus("", healthpb.HealthCheckResponse_SERVING)+ healthpb.RegisterHealthServer(grpcServer, hs)++ // Go-based readiness: /readyz is OK once this server is up and serving.+ readyzSrv := serveReadyz(host, readyzPort)++ // Shut down on ctx cancellation or termination signals.+ ctx, stop := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)+ defer stop()+ go func() {+ <-ctx.Done()+ log.Printf("antigravity interactions harness: shutting down")+ if readyzSrv != nil {+ _ = readyzSrv.Close()+ }+ grpcServer.GracefulStop()+ }()++ log.Printf("antigravity interactions harness serving on %s:%d (readyz :%d)", host, port, readyzPort)+ if err := grpcServer.Serve(lis); err != nil {+ return fmt.Errorf("harness gRPC server: %w", err)+ }+ return nil+}++// serveReadyz starts an HTTP server exposing /readyz that returns 200 as long as+// this process's gRPC server is running. Readiness is intrinsic to this server.+func serveReadyz(host string, readyzPort int) *http.Server {+ mux := http.NewServeMux()+ mux.HandleFunc("/readyz", func(w http.ResponseWriter, r *http.Request) {+ w.WriteHeader(http.StatusOK)+ _, _ = w.Write([]byte("ok\n"))+ })+ srv := &http.Server{+ Addr: net.JoinHostPort(host, strconv.Itoa(readyzPort)),+ Handler: mux,+ }+ go func() {+ if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {+ log.Printf("readyz server on %s exited: %v", srv.Addr, err)+ }+ }()+ return srv+}++// Connect drives one harness execution. Per the HarnessService contract, the+// client sends HarnessRequest{start} (and may send one HarnessRequest{cancel}+// mid-stream); the server streams zero or more HarnessResponse{outputs} frames+// terminated by exactly one HarnessResponse{end}.+func (s *server) Connect(stream proto.HarnessService_ConnectServer) error {+ ctx, cancel := context.WithCancel(stream.Context())+ defer cancel()++ // The first frame must be a start.+ req, err := stream.Recv()+ if err != nil {+ return err+ }+ start := req.GetStart()+ if start == nil {+ return fmt.Errorf("first HarnessRequest must be a start frame")+ }+ convID := req.GetConversationId()++ exec, err := s.h.Start(ctx, convID, start.GetHarnessConfig())+ if err != nil {+ return sendEnd(stream, convID, proto.State_STATE_FAILED, err)+ }+ defer func() { _ = exec.Close(context.WithoutCancel(ctx)) }()++ if len(start.GetMessages()) > 0 {+ if err := exec.Queue(ctx, start.GetMessages()...); err != nil {+ return sendEnd(stream, convID, proto.State_STATE_FAILED, err)+ }+ }++ // Watch for a mid-stream cancel frame; it cancels the run's context.+ //+ // Note: mid-run steering (injecting extra human input while a turn is running)+ // is intentionally NOT supported here. The execution can accept steering via+ // Queue, but the HarnessRequest oneof only defines {start, cancel} -- there is+ // no wire frame to carry additional input after start -- so a client cannot+ // deliver steering over Connect. Multi-turn conversation is instead expressed+ // as separate Connect executions that resume via the persisted cursor. Any+ // non-cancel frame received here is therefore ignored.+ go func() {+ for {+ r, err := stream.Recv()+ if err != nil {+ return // stream closed or errored; run ends by other means+ }+ if r.GetCancel() != nil {+ cancel()+ return+ }+ }+ }()++ // Run the turn, forwarding each agent message as an outputs frame.+ handler := &streamHandler{stream: stream, convID: convID}+ if err := exec.Run(ctx, handler); err != nil {+ if ctx.Err() != nil {+ return sendEnd(stream, convID, proto.State_STATE_CANCELED, ctx.Err())+ }+ return sendEnd(stream, convID, proto.State_STATE_FAILED, err)+ }+ if serr := handler.err(); serr != nil {+ return serr // failed while sending an outputs frame; stream is broken+ }+ return sendEnd(stream, convID, proto.State_STATE_COMPLETED, nil)+}++// streamHandler forwards each message the harness produces during a turn as a+// HarnessResponse{outputs} frame.+type streamHandler struct {+ stream proto.HarnessService_ConnectServer+ convID string++ mu sync.Mutex+ sendErr error+}++var _ harness.Handler = (*streamHandler)(nil)++func (h *streamHandler) OnMessage(_ context.Context, _ string, msg *proto.Message) error {+ err := h.stream.Send(&proto.HarnessResponse{+ ConversationId: h.convID,+ Type: &proto.HarnessResponse_Outputs{+ Outputs: &proto.HarnessOutputs{Messages: []*proto.Message{msg}},+ },+ })+ if err != nil {+ h.mu.Lock()+ h.sendErr = err+ h.mu.Unlock()+ }+ return err+}++func (h *streamHandler) OnComplete(_ context.Context, _ string) error { return nil }++func (h *streamHandler) err() error {+ h.mu.Lock()+ defer h.mu.Unlock()+ return h.sendErr+}++// sendEnd sends the single terminal HarnessResponse{end} frame. If err is+// non-nil, it is attached as the terminal Error.+func sendEnd(stream proto.HarnessService_ConnectServer, convID string, state proto.State, err error) error {+ end := &proto.HarnessEnd{State: state}+ if err != nil {+ end.Error = &proto.Error{Description: err.Error()}+ }+ return stream.Send(&proto.HarnessResponse{+ ConversationId: convID,+ Type: &proto.HarnessResponse_End{End: end},+ })+}diff --git a/internal/harness/antigravityinteractions/server_test.go b/internal/harness/antigravityinteractions/server_test.gonew file mode 100644index 0000000..e0e454b--- /dev/null+++ b/internal/harness/antigravityinteractions/server_test.go@@ -0,0 +1,142 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package antigravityinteractions++import (+ "context"+ "errors"+ "io"+ "net"+ "testing"++ "github.com/google/ax/internal/harness/harnesstest"+ "github.com/google/ax/proto"+ "google.golang.org/grpc"+ "google.golang.org/grpc/credentials/insecure"+ "google.golang.org/grpc/test/bufconn"+)++// startTestServer serves the HarnessService (backed by h) over an in-memory+// bufconn and returns a connected HarnessService client.+func startTestServer(t *testing.T, h *AntigravityInteractionsHarness) proto.HarnessServiceClient {+ t.Helper()+ lis := bufconn.Listen(1024 * 1024)+ s := grpc.NewServer()+ proto.RegisterHarnessServiceServer(s, &server{h: h})+ go func() { _ = s.Serve(lis) }()+ t.Cleanup(s.Stop)++ conn, err := grpc.NewClient(+ "passthrough:///bufnet",+ grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {+ return lis.DialContext(ctx)+ }),+ grpc.WithTransportCredentials(insecure.NewCredentials()),+ )+ if err != nil {+ t.Fatalf("dial bufconn: %v", err)+ }+ t.Cleanup(func() { _ = conn.Close() })+ return proto.NewHarnessServiceClient(conn)+}++// TestConnect_StartToEnd verifies the Connect wire contract: a start frame drives+// one harness turn, and the stream terminates with exactly one HarnessEnd+// (COMPLETED) against the fake Interactions API.+func TestConnect_StartToEnd(t *testing.T) {+ fake := &fakeInteractions{interactionIDs: []string{"INT-1"}}+ h := newTestHarness(t, fake, t.TempDir())+ client := startTestServer(t, h)++ stream, err := client.Connect(context.Background())+ if err != nil {+ t.Fatalf("Connect: %v", err)+ }+ if err := stream.Send(&proto.HarnessRequest{+ ConversationId: "conv-1",+ HarnessId: "antigravity-interactions",+ Type: &proto.HarnessRequest_Start{+ Start: &proto.HarnessStart{Messages: []*proto.Message{harnesstest.UserText("hello")}},+ },+ }); err != nil {+ t.Fatalf("send start: %v", err)+ }+ _ = stream.CloseSend()++ var gotEnd *proto.HarnessEnd+ for {+ resp, err := stream.Recv()+ if errors.Is(err, io.EOF) {+ break+ }+ if err != nil {+ t.Fatalf("recv: %v", err)+ }+ if end := resp.GetEnd(); end != nil {+ if gotEnd != nil {+ t.Fatalf("received more than one HarnessEnd")+ }+ gotEnd = end+ }+ }++ if gotEnd == nil {+ t.Fatal("stream ended without a HarnessEnd frame")+ }+ if gotEnd.GetState() != proto.State_STATE_COMPLETED {+ t.Errorf("terminal state = %v, want COMPLETED (error: %v)", gotEnd.GetState(), gotEnd.GetError())+ }++ // The fake recorded the request: first turn has no previous_interaction_id.+ reqs := fake.recorded()+ if len(reqs) != 1 {+ t.Fatalf("fake received %d requests, want 1", len(reqs))+ }+ if reqs[0].PreviousInteractionID != "" {+ t.Errorf("previous_interaction_id = %q, want empty", reqs[0].PreviousInteractionID)+ }+}++// TestConnect_FirstFrameMustBeStart verifies that a non-start first frame is+// rejected.+func TestConnect_FirstFrameMustBeStart(t *testing.T) {+ fake := &fakeInteractions{}+ h := newTestHarness(t, fake, t.TempDir())+ client := startTestServer(t, h)++ stream, err := client.Connect(context.Background())+ if err != nil {+ t.Fatalf("Connect: %v", err)+ }+ if err := stream.Send(&proto.HarnessRequest{+ ConversationId: "conv-1",+ Type: &proto.HarnessRequest_Cancel{Cancel: &proto.HarnessCancel{}},+ }); err != nil {+ t.Fatalf("send cancel: %v", err)+ }+ _ = stream.CloseSend()++ // Draining the stream should surface an error (Connect returns it).+ for {+ _, err := stream.Recv()+ if err == nil {+ continue+ }+ if errors.Is(err, io.EOF) {+ t.Fatal("expected an error for a non-start first frame, got clean EOF")+ }+ break // got the expected non-EOF error+ }+}