8000 feat: machine-readable Substrate compatibility metadata, version handshake, and safe snapshot defaults for Coding Agents · Issue #545 · google/ax · GitHub
[go: up one dir, main page]

Skip to content

feat: machine-readable Substrate compatibility metadata, version handshake, and safe snapshot defaults for Coding Agents #545

Open

Description

@jpawelczak

Summary

When autonomous coding agents (and automated CI/CD pipelines) provision and operate Google AX alongside Agent Substrate on Kubernetes/GKE, they frequently encounter silent or cryptic gRPC/proto API mismatches between AX (ax-server, ax CLI) and Substrate (ate-api-server).

For instance, when Agent Substrate upgraded its protobuf definitions in v1.0.0-rc.1 (moving from package ateapi; with gRPC service /ateapi.Control/* to package substrate.ateapi.v1; with Go module go.ate.dev/substrate/api/ateapi/v1), ax apply halts with:

rpc error: code = Unimplemented desc = unknown service ateapi.Control

Additionally, DefaultSnapshotsBucket = "gs://dberkov-gke-dev3/ate-env/" in internal/substrate/client.go hardcodes a bucket which triggers:

rpc error: code = InvalidArgument desc = actor_template.snapshot_config.storage_location: Forbidden

under Substrate v1.0.0 preview gating rules (unless PerTemplateSnapshotLocation is explicitly enabled and preview headers are passed).

Because this compatibility information is not exposed in a machine-readable format or validated at startup, coding agents cannot autonomously detect or reconcile version drift, leading to workflow halts.

Proposed Enhancements

1. Machine-Readable Compatibility Matrix (ax-compat.json / ax version --compat --json)

Provide a structured schema or CLI command that autonomous agents and tooling can query:

{
  "ax_version": "v0.4.0",
  "substrate_compatibility": {
    "supported_range": ">=v1.0.0-rc.1, <v2.0.0",
    "proto_package": "substrate.ateapi.v1",
    "go_module": "go.ate.dev/substrate/api/ateapi/v1"
  }
}

This enables agent orchestrators to inspect cluster ate-api-server version and select or compile the matching AX container/binary without trial-and-error.

2. Runtime Version Handshake / Actionable Error Diagnostic

  • In ax-server startup and client.go, perform a lightweight handshake against ate-api-server.
  • If ate-api-server returns gRPC Unimplemented for ateapi.Control or substrate.ateapi.v1.Control, wrap the error with an explicit diagnostic:

    "Proto package mismatch: ax-server was compiled with Substrate client [v0.6.0 (pkg ateapi)], but ate-api-server expects [v1.0.0+ (pkg substrate.ateapi.v1)]. Please align AX and Substrate versions."

3. Default DefaultSnapshotsBucket to Empty String ""

  • When snapshotsBucket is empty string "", protobuf omits actor_template.snapshot_config.storage_location.
  • Substrate automatically uses its cluster-wide --snapshot-location, avoiding preview gate failures (PerTemplateSnapshotLocation: Forbidden) and removing developer-specific bucket references (gs://dberkov-gke-dev3/... / gs://snapshot-substrate-test-...).

4. Agent Guidance (AGENTS.md / docs/agent-orchestration.md)

Add concise documentation or an AGENTS.md spec outlining standard conventions for AI agents orchestrating AX:

  • How to match AX CLI, ax-server, and Substrate images by digest/tag.
  • Recommended RBAC and NetworkPolicy labels (e.g. ate.dev/api-access=true on AX namespaces).
  • Recommended environment overrides (AX_SNAPSHOTS_BUCKET="").

Context & Impact

Autonomous coding agents are increasingly orchestrating full lifecycle workflows (dispatching tasks, monitoring actors, deploying fixes). Providing machine-readable compatibility metadata and self-describing error diagnostics turns opaque gRPC failures into automated self-healing workflows.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      0