Agent Executor (AX) is Google's open agentic orchestration runtime
Go
Introduce pythonsidecar package (#273)
Jaana Doganc507098025f6
diff --git a/cmd/ax/harness.go b/cmd/ax/harness.goindex a046c77..a9735e6 100644--- a/cmd/ax/harness.go+++ b/cmd/ax/harness.go@@ -24,12 +24,12 @@ import ("net""net/http""os"- "os/exec""os/signal""strconv""syscall""time"+ "github.com/google/ax/internal/pythonsidecar""github.com/spf13/cobra""google.golang.org/grpc""google.golang.org/grpc/credentials/insecure"@@ -80,19 +80,23 @@ func runHarness(cmd *cobra.Command, args []string) error {return err}- py := exec.Command("python3", "-m", "python.antigravity.harness_server",- "--host", harnessHost,- "--port", strconv.Itoa(harnessPort),- )- py.Stdin = os.Stdin- py.Stdout = os.Stdout- py.Stderr = os.Stderr- py.Env = os.Environ()+ cfg := pythonsidecar.Config{+ Module: "python.antigravity.harness_server",+ Args: []string{+ "--host", harnessHost,+ "--port", strconv.Itoa(harnessPort),+ },+ Stdin: os.Stdin,+ Stdout: os.Stdout,+ Stderr: os.Stderr,+ ReadyFunc: pythonsidecar.TCPReady(net.JoinHostPort("127.0.0.1", strconv.Itoa(harnessPort))),+ }- if err := py.Start(); err != nil {+ sidecar := pythonsidecar.New(cfg)+ if err := sidecar.Start(cmd.Context()); err != nil {return fmt.Errorf("failed to start antigravity harness server: %w", err)}- log.Printf("forked antigravity harness server (pid %d) on %s:%d", py.Process.Pid, harnessHost, harnessPort)+ log.Printf("forked antigravity harness server (pid %d) on %s:%d", sidecar.Pid(), harnessHost, harnessPort)// Serve the /readyz endpoint that substrate's readiness probe polls (during// golden snapshotting and per-actor Run/Restore).@@ -102,12 +106,11 @@ func runHarness(cmd *cobra.Command, args []string) error {sigChan := make(chan os.Signal, 1)signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)go func() {- for sig := range sigChan {- _ = py.Process.Signal(sig)- }+ <-sigChan+ _ = sidecar.Stop()}()- if err := py.Wait(); err != nil {+ if err := sidecar.Wait(); err != nil {return fmt.Errorf("antigravity harness server exited: %w", err)}return nildiff --git a/internal/pythonsidecar/sidecar.go b/internal/pythonsidecar/sidecar.gonew file mode 100644index 0000000..f4ffb0d--- /dev/null+++ b/internal/pythonsidecar/sidecar.go@@ -0,0 +1,255 @@+// 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 pythonsidecar provides a mechanism to manage the lifecycle+// of a Python process as a sidecar component in a Go application.+package pythonsidecar++import (+ "context"+ "fmt"+ "io"+ "net"+ "os/exec"+ "sync"+ "syscall"+ "time"+)++// Config holds the configuration parameters for the sidecar lifecycle.+type Config struct {+ // Module is the Python module name to run using the "-m" flag. (Required)+ Module string+ // Args contains any additional arguments to pass to the module. (Optional)+ Args []string+ // Stdin redirects the sidecar's standard input. (Optional)+ Stdin io.Reader+ // Stdout redirects the sidecar's standard output. (Optional)+ Stdout io.Writer+ // Stderr redirects the sidecar's standard error. (Optional)+ Stderr io.Writer+ // ReadyFunc is an optional function to check if the server is ready to accept requests.+ // When provided, Start will poll ReadyFunc until it returns nil or the context expires. (Optional)+ ReadyFunc func(ctx context.Context) error+}++// TODO: AntigravityHarness should use pythonsidecar.+// TODO: Use /var/ax_agy_harness_service for communication instead of TCP.+// TODO: Use go:embed to embed python/ directory into the ax binary.+// TODO: Add a Setup method to extract embedded assets, pip install, etc.++// Sidecar manages the lifecycle of the underlying Python process.+type Sidecar struct {+ cfg Config++ mu sync.Mutex+ cmd *exec.Cmd+ running bool+ stopping bool+ exitErr error+ doneChan chan struct{}+}++// New creates a new Sidecar instance using the provided configuration struct.+func New(cfg Config) *Sidecar {+ return &Sidecar{+ cfg: cfg,+ }+}++// Start launches the Python process and monitors its lifecycle in the background.+// If ReadyFunc is configured, Start blocks until the server is ready or the context expires.+// If the process fails to start or become ready, an error is returned immediately.+func (s *Sidecar) Start(ctx context.Context) error {+ s.mu.Lock()+ if s.running {+ s.mu.Unlock()+ return fmt.Errorf("sidecar is already running")+ }++ if s.cfg.Module == "" {+ s.mu.Unlock()+ return fmt.Errorf("Module cannot be empty")+ }++ // Prepare arguments: python3 -u -m module [args...]+ // -u forces unbuffered stdout/stderr so logs stream to Go instantly+ fullArgs := append([]string{"-u", "-m", s.cfg.Module}, s.cfg.Args...)++ cmd := exec.CommandContext(ctx, "python3", fullArgs...)++ if s.cfg.Stdin != nil {+ cmd.Stdin = s.cfg.Stdin+ }+ if s.cfg.Stdout != nil {+ cmd.Stdout = s.cfg.Stdout+ }+ if s.cfg.Stderr != nil {+ cmd.Stderr = s.cfg.Stderr+ }++ if err := cmd.Start(); err != nil {+ s.mu.Unlock()+ return fmt.Errorf("failed to start python process: %w", err)+ }++ s.cmd = cmd+ s.running = true+ s.stopping = false+ s.exitErr = nil+ s.doneChan = make(chan struct{})+ s.mu.Unlock()++ // Monitor lifecycle asynchronously+ go s.monitor()++ // If a readiness probe is configured, wait for the server to become ready+ if s.cfg.ReadyFunc != nil {+ if err := s.WaitUntilReady(ctx); err != nil {+ _ = s.Stop()+ return fmt.Errorf("server failed to become ready: %w", err)+ }+ }++ return nil+}++// monitor waits for the process to exit and records its exit status.+func (s *Sidecar) monitor() {+ err := s.cmd.Wait()+ s.mu.Lock()+ s.running = false+ if err != nil && !s.stopping {+ s.exitErr = fmt.Errorf("python process exited with error: %w", err)+ } else {+ s.exitErr = nil+ }+ s.mu.Unlock()+ close(s.doneChan)+}++// IsRunning returns true if the Python process is currently active.+func (s *Sidecar) IsRunning() bool {+ s.mu.Lock()+ defer s.mu.Unlock()+ return s.running+}++// Pid returns the process ID of the running sidecar, or 0 if not running.+func (s *Sidecar) Pid() int {+ s.mu.Lock()+ defer s.mu.Unlock()+ if !s.running || s.cmd == nil || s.cmd.Process == nil {+ return 0+ }+ return s.cmd.Process.Pid+}++// WaitUntilReady blocks until ReadyFunc returns nil, the context is canceled, or the process exits prematurely.+// If no ReadyFunc is configured in Config, this method returns nil immediately.+func (s *Sidecar) WaitUntilReady(ctx context.Context) error {+ if s.cfg.ReadyFunc == nil {+ return nil+ }++ ticker := time.NewTicker(50 * time.Millisecond)+ defer ticker.Stop()++ for {+ // 1. Check if the process exited prematurely+ s.mu.Lock()+ running := s.running+ exitErr := s.exitErr+ s.mu.Unlock()+ if !running {+ if exitErr != nil {+ return fmt.Errorf("process exited before becoming ready: %w", exitErr)+ }+ return fmt.Errorf("process exited unexpectedly before becoming ready")+ }++ // 2. Try the readiness check+ if err := s.cfg.ReadyFunc(ctx); err == nil {+ return nil+ }++ // 3. Wait for the next ticker or context cancellation+ select {+ case <-ctx.Done():+ return ctx.Err()+ case <-ticker.C:+ continue+ }+ }+}++// Wait blocks until the sidecar exits or crashes, returning the exit error if any.+func (s *Sidecar) Wait() error {+ s.mu.Lock()+ done := s.doneChan+ s.mu.Unlock()+ if done != nil {+ <-done+ }+ s.mu.Lock()+ defer s.mu.Unlock()+ return s.exitErr+}++// Stop gracefully terminates the Python process using SIGTERM, falling back to SIGKILL if necessary.+func (s *Sidecar) Stop() error {+ s.mu.Lock()+ if !s.running || s.cmd == nil || s.cmd.Process == nil {+ s.mu.Unlock()+ return nil+ }+ s.stopping = true+ done := s.doneChan+ s.mu.Unlock()++ // 1. Send graceful SIGTERM+ if err := s.cmd.Process.Signal(syscall.SIGTERM); err != nil {+ _ = s.cmd.Process.Kill()+ if done != nil {+ <-done+ }+ return nil+ }++ // 2. Give it a small window to exit gracefully before killing it+ select {+ case <-done:+ return nil+ case <-time.After(3 * time.Second):+ // Fallback to force kill+ _ = s.cmd.Process.Kill()+ if done != nil {+ <-done+ }+ return nil+ }+}++// TCPReady returns a ReadyFunc that attempts to establish a TCP connection to addr (e.g., "127.0.0.1:50053").+func TCPReady(addr string) func(ctx context.Context) error {+ return func(ctx context.Context) error {+ var d net.Dialer+ conn, err := d.DialContext(ctx, "tcp", addr)+ if err != nil {+ return err+ }+ _ = conn.Close()+ return nil+ }+}diff --git a/internal/pythonsidecar/sidecar_test.go b/internal/pythonsidecar/sidecar_test.gonew file mode 100644index 0000000..f147feb--- /dev/null+++ b/internal/pythonsidecar/sidecar_test.go@@ -0,0 +1,160 @@+// 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 pythonsidecar_test++import (+ "bytes"+ "context"+ "fmt"+ "net"+ "os"+ "path/filepath"+ "strconv"+ "strings"+ "testing"+ "time"++ "github.com/google/ax/internal/pythonsidecar"+)++func getFreePort(t *testing.T) int {+ t.Helper()+ l, err := net.Listen("tcp", "127.0.0.1:0")+ if err != nil {+ t.Fatalf("failed to get free port: %v", err)+ }+ port := l.Addr().(*net.TCPAddr).Port+ _ = l.Close()+ return port+}++func TestSidecar_ConfigValidation(t *testing.T) {+ ctx := context.Background()++ t.Run("empty Module", func(t *testing.T) {+ s := pythonsidecar.New(pythonsidecar.Config{})+ err := s.Start(ctx)+ if err == nil || !strings.Contains(err.Error(), "Module cannot be empty") {+ t.Fatalf("expected error about empty Module, got %v", err)+ }+ })+}++func TestSidecar_ModuleExecution(t *testing.T) {+ tmpDir := t.TempDir()+ modulePath := filepath.Join(tmpDir, "test_module.py")+ moduleContent := `+import sys+print("hello stdout")+print("hello stderr", file=sys.stderr)+sys.exit(0)+`+ if err := os.WriteFile(modulePath, []byte(moduleContent), 0644); err != nil {+ t.Fatalf("failed to write module: %v", err)+ }++ t.Setenv("PYTHONPATH", tmpDir)+ var stdout, stderr bytes.Buffer+ cfg := pythonsidecar.Config{+ Module: "test_module",+ Stdout: &stdout,+ Stderr: &stderr,+ }++ s := pythonsidecar.New(cfg)+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)+ defer cancel()++ if err := s.Start(ctx); err != nil {+ t.Fatalf("Start() failed: %v", err)+ }++ if err := s.Wait(); err != nil {+ t.Fatalf("Wait() failed: %v", err)+ }++ if !strings.Contains(stdout.String(), "hello stdout") {+ t.Errorf("stdout expected 'hello stdout', got %q", stdout.String())+ }+ if !strings.Contains(stderr.String(), "hello stderr") {+ t.Errorf("stderr expected 'hello stderr', got %q", stderr.String())+ }+ if s.IsRunning() {+ t.Errorf("expected IsRunning() to be false after exit")+ }+}+++func TestSidecar_ModuleServerWithTCPReady(t *testing.T) {+ port := getFreePort(t)+ addr := fmt.Sprintf("127.0.0.1:%d", port)++ cfg := pythonsidecar.Config{+ Module: "http.server",+ Args: []string{strconv.Itoa(port), "--bind", "127.0.0.1"},+ ReadyFunc: pythonsidecar.TCPReady(addr),+ }++ s := pythonsidecar.New(cfg)+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)+ defer cancel()++ if err := s.Start(ctx); err != nil {+ t.Fatalf("Start() with TCPReady failed: %v", err)+ }++ if !s.IsRunning() {+ t.Fatalf("expected server sidecar to be running")+ }+ if s.Pid() <= 0 {+ t.Fatalf("expected valid PID, got %d", s.Pid())+ }++ if err := s.Stop(); err != nil {+ t.Fatalf("Stop() failed: %v", err)+ }+}++func TestSidecar_ReadinessFailureOnPrematureExit(t *testing.T) {+ tmpDir := t.TempDir()+ modulePath := filepath.Join(tmpDir, "crash.py")+ if err := os.WriteFile(modulePath, []byte("import sys; sys.exit(1)\n"), 0644); err != nil {+ t.Fatalf("failed to write script: %v", err)+ }++ t.Setenv("PYTHONPATH", tmpDir)+ port := getFreePort(t)+ addr := fmt.Sprintf("127.0.0.1:%d", port)++ cfg := pythonsidecar.Config{+ Module: "crash",+ ReadyFunc: pythonsidecar.TCPReady(addr),+ }++ s := pythonsidecar.New(cfg)+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)+ defer cancel()++ err := s.Start(ctx)+ if err == nil {+ t.Fatalf("expected Start() to fail when process exits prematurely")+ }+ if !strings.Contains(err.Error(), "exited before becoming ready") {+ t.Fatalf("expected 'exited before becoming ready' in error, got: %v", err)+ }+ if s.IsRunning() {+ t.Fatalf("expected IsRunning() to be false")+ }+}