You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat: machine-readable Substrate compatibility metadata, version handshake, and safe snapshot defaults for Coding Agents #545
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:
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:
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-...).
Activity