Add structured error field to ControlResponse for CONTROL_ACTION_ERROR

[lanycrost]

Problem statement

CONTROL_ACTION_ERROR is defined as a ControlAction enum value, but ControlResponse has no structured field to carry error details. Implementations must communicate error information through the untyped metadata map, leading to inconsistent error handling and potential information leakage (stack traces in metadata values).

enum ControlAction {
  // ...
  CONTROL_ACTION_ERROR = 15;
}

message ControlResponse {
  ControlAction action = 1;
  map<string, string> metadata = 2;  // Error details go here?
  FlowControl flow = 3;
  string custom_action = 4;
  // No structured error field
}

Proposed change

Add a ControlError message and an optional error field to ControlResponse:

// ControlError carries structured error details for CONTROL_ACTION_ERROR responses.
message ControlError {
  // code is an application-level error code. Values are implementation-defined.
  int32 code = 1;
  // message is a human-readable error description safe for logging.
  // Do not include stack traces or internal paths.
  string message = 2;
  // details carries additional context keyed by error domain.
  map<string, string> details = 3;
}

message ControlResponse {
  ControlAction action = 1;
  map<string, string> metadata = 2;
  FlowControl flow = 3;
  string custom_action = 4;
  // error carries structured error details when action == CONTROL_ACTION_ERROR.
  ControlError error = 5;
}

Affected area

• Proto definitions

Compatibility / migration

Adding a new field (5) to ControlResponse and a new message are both additive and wire-compatible. Old consumers ignore the new field. New consumers can check error != nil when action == CONTROL_ACTION_ERROR.

Additional context

Identified during architectural review. Without structured errors, each consumer invents its own metadata key convention (error, error_message, err, etc.), making cross-component debugging harder.