Skip to content

armgit / ax

Public Imported from GitHub
0

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.go
index 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 nil
diff --git a/internal/pythonsidecar/sidecar.go b/internal/pythonsidecar/sidecar.go
new file mode 100644
index 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.go
new file mode 100644
index 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")
+ }
+}